ساخت المان‌های سفارشی (Create Your Own Elements)

Child theme Bricks، که می‌توانید از حساب Bricks دانلود کنید، شامل یک المان سفارشی ساده برای اهداف نمایشی است. این مقاله با جزئیات بیشتری توضیح می‌دهد که چگونه المان‌های خود را به‌صورت برنامه‌نویسی بسازید.

ساخت المان‌های سفارشی در Bricks از الگویی مشابه ساخت ویجت‌های وردپرس پیروی می‌کند. با گسترش کلاس Bricks\Element شروع می‌کنید و ویژگی‌ها و متدهای مورد نیاز را برای المان خود پر می‌کنید.

ابتدا یک فایل element-test.php جدید در پوشه اصلی تم فرزند Bricks خود ایجاد کنید.

کلاس المان خالی

<?php
// element-test.php
if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly

class Prefix_Element_Test extends \Bricks\Element {
  // Element properties
  public $category     = '';
  public $name         = '';
  public $icon         = '';
  public $css_selector = '';
  public $scripts      = [];
  public $nestable     = false; // true || @since 1.5

  // Methods: Builder-specific
  public function get_label() {}
  public function get_keywords() {}
  public function set_control_groups() {}
  public function set_controls() {}

  // Methods: Frontend-specific
  public function enqueue_scripts() {}
  public function render() {}
}

بیایید ویژگی‌ها و متدهای المان را مرور کنیم:

$category مورد نیاز	نام دسته (همه حروف کوچک، بدون فاصله). از هر یک از دسته‌بندی‌های المان از پیش تعریف‌شده (به‌عنوان مثال `general`، `media`، و غیره) استفاده کنید یا نام دسته خود را اختصاص دهید. هنگام تنظیم دسته‌بندی خود، مطمئن شوید که یک رشته دسته قابل ترجمه برای سازنده با استفاده از فیلتر ارائه دهید: Bricks/builder/i18n
$name مورد نیاز	شناسه منحصربه‌فرد المان (همه حروف کوچک، بدون فاصله). برای جلوگیری از هرگونه تداخل با المان‌های دیگر، لطفاً نام المان خود را پیشوند بگذارید، به‌عنوان مثال: `prefix-element-test`.
$icon	کلاس CSS فونت آیکون. Bricks شامل فونت‌های آیکون زیر است. برای نمایش المان خود در پانل سازنده، از هر کلاس فونت آیکون CSS استفاده کنید: Font Awesome 6 (مثلاً "fas fa-anchor")، Ionicons 4 (مثلاً "ion-md-alarm")، Themify Icons (مثلاً "ti-bolt-alt").
$css_selector	به‌طور پیش‌فرض، تمام تنظیمات کنترل CSS روی پوشش المان اعمال می‌شود: `.bricks-element-wrapper`. اگر می‌خواهید انتخابگر پیش‌فرض CSS یک المان HTML فرزند را هدف قرار دهد، این انتخابگر را در اینجا تنظیم کنید.
$nestable	برای المان‌های ساده حذف کنید. برای ایجاد یک المان تودرتو روی `true` تنظیم کنید.
$scripts	آرایه‌ای از اسکریپت‌های جاوا اسکریپت که زمانی اجرا می‌شوند که یک المان در فرانت‌اند رندر می‌شود یا در سازنده به‌روزرسانی می‌شود. برای مثال، المان Counter از اسکریپتی به نام "bricksCounter" (تعریف‌شده در frontend.min.js) استفاده می‌کند. برای بارگیری این اسکریپت: `public $scripts = ['bricksCounter'];` لطفاً همه اسکریپت‌های خود را پیشوند بگذارید. به‌عنوان مثال: `prefixElementTest`
get_label() مورد نیاز	برچسب محلی‌سازی‌شده المان را برگردانید.
get_keywords()	آرایه‌ای از رشته‌ها که هنگام جستجوی المان با آن‌ها تطابق داده می‌شود و المان را در نتایج جستجو نشان می‌دهد.
set_control_groups()	به‌طور پیش‌فرض، همه کنترل‌های المان در پانل سازنده زیر برگه «محتوا» بدون گروه‌بندی نشان داده می‌شوند. با تنظیم ویژگی‌های زیر برای هر گروه، کنترل‌گروه‌های سفارشی تعریف کنید: title — عنوان گروه کنترل. tab — روی "content" یا "style" تنظیم کنید.
set_controls() مورد نیاز	تعریف کنترل‌های المان. برای مرور همه کنترل‌های موجود و تنظیمات آن‌ها به اینجا مراجعه کنید: کنترل‌های المان
enqueue_scripts()	اسکریپت‌ها و استایل‌های خاص المان را بارگیری کنید. این موارد فقط در صفحاتی که از این المان استفاده می‌شود بارگیری می‌شوند و باعث عملکرد بهتر می‌شود. مثال: `wp_enqueue_script( 'prefix-element-test', get_template_directory_uri() . '/js/custom.js', ['jquery'], '1.0', true );`
render() مورد نیاز	المان HTML را رندر می‌کند. ویژگی‌های HTML را از طریق `$this->set_attribute()` تعریف کنید و از طریق `$this->render_attribute()` خروجی بگیرید.
`set_attribute( $key, $attribute, $value )`	تابع کمکی برای تنظیم ویژگی‌های HTML برای هر تگ HTML. `$key` به‌عنوان شناسه منحصربه‌فرد برای این تگ HTML عمل می‌کند. `$attribute` نام ویژگی HTML است. `$value` یک رشته یا آرایه است که مقدار(های) ویژگی را نگه می‌دارد.
`render_attributes( $key )`	تابع کمکی برای رندر ویژگی‌های HTML تعریف‌شده از طریق `$this->set_attribute()`. `$key` به‌عنوان شناسه منحصربه‌فرد برای این تگ HTML عمل می‌کند.
`render_dynamic_data_tag( $tag, $context, $args )`	تابع کمکی برای رندر تگ‌های داده پویا داخل تابع render با استفاده از `$this->render_dynamic_data_tag(...)`. نمونه‌ای از `$tag` مانند `{post_title}` است. این تابع کمکی بسته به محیطی که المان در آن رندر می‌شود، شناسه پست صحیح را تنظیم می‌کند.
`render_dynamic_data( $content )`	تابع کمکی برای رندر محتوای (رشته‌ای) که می‌تواند حاوی تگ‌های داده پویا باشد. از این تابع کمکی داخل تابع render که `$this->render_dynamic_data(...)` را فراخوانی می‌کند، استفاده کنید. این تابع بسته به محیطی که المان در آن رندر می‌شود، شناسه پست صحیح را تنظیم می‌کند.

بیایید ویژگی‌ها و متدهای المان خود را با چند داده پر کنیم:

<?php
// element-test.php

if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly

class Prefix_Element_Test extends \Bricks\Element {
  // Element properties
  public $category     = 'general'; // Use predefined element category 'general'
  public $name         = 'prefix-test'; // Make sure to prefix your elements
  public $icon         = 'ti-bolt-alt'; // Themify icon font class
  public $css_selector = '.prefix-test-wrapper'; // Default CSS selector
  public $scripts      = ['prefixElementTest']; // Script(s) run when element is rendered on frontend or updated in builder

  // Return localised element label
  public function get_label() {
    return esc_html__( 'Test element', 'bricks' );
  }

  // Set builder control groups
  public function set_control_groups() {
    $this->control_groups['text'] = [ // Unique group identifier (lowercase, no spaces)
      'title' => esc_html__( 'Text', 'bricks' ), // Localized control group title
      'tab' => 'content', // Set to either "content" or "style"
    ];

    $this->control_groups['settings'] = [
      'title' => esc_html__( 'Settings', 'bricks' ),
      'tab' => 'content',
    ];
  }

  // Set builder controls
  public function set_controls() {
    $this->controls['content'] = [ // Unique control identifier (lowercase, no spaces)
      'tab' => 'content', // Control tab: content/style
      'group' => 'text', // Show under control group
      'label' => esc_html__( 'Content', 'bricks' ), // Control label
      'type' => 'text', // Control type
      'default' => esc_html__( 'Content goes here ..', 'bricks' ), // Default setting
    ];

    $this->controls['type'] = [
      'tab' => 'content',
      'group' => 'settings',
      'label' => esc_html__( 'Type', 'bricks' ),
      'type' => 'select',
      'options' => [
        'info' => esc_html__( 'Info', 'bricks' ),
        'success' => esc_html__( 'Success', 'bricks' ),
        'warning' => esc_html__( 'Warning', 'bricks' ),
        'danger' => esc_html__( 'Danger', 'bricks' ),
        'muted' => esc_html__( 'Muted', 'bricks' ),
      ],
      'inline' => true,
      'clearable' => false,
      'pasteStyles' => false,
      'default' => 'info',
    ];
  }

  // Enqueue element styles and scripts
  public function enqueue_scripts() {
    wp_enqueue_script( 'prefix-test-script' );
  }

  // Render element HTML
  public function render() {
    // Set element attributes
    $root_classes[] = 'prefix-test-wrapper';

    if ( ! empty( $this->settings['type'] ) ) {
      $root_classes[] = "color-{$this->settings['type']}";
    }

    // Add 'class' attribute to element root tag
    $this->set_attribute( '_root', 'class', $root_classes );

    // Render element HTML
    // '_root' attribute is required (contains element ID, class, etc.)
    echo "<div {$this->render_attributes( '_root' )}>"; // Element root attributes
      if ( ! empty( $this->settings['content'] ) ) {
        echo "<div>{$this->settings['content']}</div>";
      }
    echo '</div>';
  }
}

می‌توانید کنترل‌های Bricks مستند را در اینجا مرور کنید: /developer/controls/

توجه

تمام تنظیمات المان در $this->settings ذخیره می‌شود. برای مشاهده تنظیمات المان می‌توانید آن‌ها را روی صفحه چاپ کنید: var_dump( $this->settings ); در تابع render().

المان خود را بارگیری و ثبت کنید

پس از ایجاد المان سفارشی خود، باید آن را بارگیری و ثبت کنید. فایل functions.php از child theme Bricks خود را باز کنید و کد زیر را اضافه کنید:

/**
 * Register custom elements
 */
add_action( 'init', function() {
  $element_files = [
    __DIR__ . '/element-test.php',
  ];

  foreach ( $element_files as $file ) {
    \Bricks\Elements::register_element( $file );
  }
}, 11 );

متد register_element سه آرگومان می‌پذیرد:

$file (الزامی): مسیر کامل فایل PHP المان سفارشی در سرور
$name (اختیاری): رشته‌ای حاوی نام المان سفارشی (به‌عنوان مثال: prefix-element-test)
$element_class (اختیاری): رشته‌ای حاوی نام کلاس المان (به‌عنوان مثال: Prefix_Element_Test) که باید از کلاس پایه Bricks (\Bricks\Element) مشتق شود.

توجه

توجه: استفاده از آرگومان‌های $name و $element_class عملکرد بارگذاری را بهبود می‌بخشد.