المان‌های Nestable (API)

Bricks 1.5 المان‌های Nestable را معرفی می‌کند. به‌علاوه یک API که به شما امکان می‌دهد المان‌های سفارشی خود را که می‌توانند حاوی المان‌های دیگری باشند، به‌صورت برنامه‌نویسی تعریف کنید. دقیقاً در ساختاری که شما می‌خواهید.

قبل از Bricks 1.5 هر المان در Bricks «مسطح» بود. به این معنی که حتی اگر یک المان دارای ساختار عمیق HTML (مانند slider و غیره) بود، نمی‌توانستید روی قسمت داخلی آن کلیک کنید تا مستقیماً ویرایش کنید (مثلاً محتویات اسلاید ۳)، یا ساختار داخلی آن را از طریق Drag & Drop به دلخواه تغییر دهید، همان‌طور که می‌توانید در یک المان layout انجام دهید.

سفارشی‌سازی صحیح المان‌های پیچیده‌تر مانند icon box، جدول قیمت، فهرست و غیره اغلب غیرممکن می‌شد.

المان‌های پیچیده‌ای مانند accordion، slider و tabs اصلاً به‌درستی قابل سفارشی‌سازی نبودند.

دسترسی و کنترل کامل بر ساختار عنصر فردی

با شروع نسخه 1.5، Bricks سه المان nestable ارائه می‌دهد:

• Accordion (nestable)
• Slider (nestable)
• Tabs (nestable)

به دلیل ساختار پیچیده آن‌ها و محدودیت‌های ساختار المان «مسطح»، سفارشی‌سازی صحیح آن‌ها به‌سختی ممکن بود.

اکنون که می‌توانید هر اسلاید را با المان‌هایی که می‌خواهید پر کنید، المان‌های خاص مانند «Carousel» و «Team Members» واقعاً ضروری نیستند.

آکاردئون - آشیانه

توجه

المان‌های Nestable در کنار نسخه‌های مسطح اصلی خود برای آینده‌ای قابل پیش‌بینی وجود خواهند داشت تا زمانی که بازخورد کافی جمع‌آوری کنیم و اشکالات اصلی را برطرف کنیم تا به‌طور کامل به المان‌های Nestable تغییر دهیم.

توجه

برخی المان‌های Nestable تعاملی که به‌شدت مبتنی بر JavaScript هستند (مانند Accordion، Slider و Tabs) ممکن است مانع از کار ۱۰۰٪ Drag & Drop روی canvas شوند. اگر با این رفتار مواجه شدید، می‌توانید از پانل Structure نیز برای افزودن و مرتب‌سازی المان‌ها استفاده کنید.

توجه

Tabs (nestable): اگر می‌خواهید ویژگی display یک «pane» را تغییر دهید، این کار را با افزودن یک المان «Block» دیگر داخل pane و تنظیم display در آن انجام دهید. خود pane از display: none برای پنهان‌کردن همه paneهای غیرفعال استفاده می‌کند. اگر display را مستقیم روی pane تغییر دهید، همه tab paneها همیشه قابل مشاهده خواهند بود.

بنابراین می‌توانید شروع به کار با المان‌های جدید nestable کنید و به‌تدریج از المان‌های ساده قدیمی فاصله بگیرید.

با گذشت زمان، المان‌های بیشتری از flat به nestable تبدیل می‌شوند تا بتوانید اکثر المان‌ها در Bricks را به‌درستی سفارشی کنید.

Nestable Elements API

بقیه این مقاله نشان می‌دهد که چگونه به‌صورت برنامه‌نویسی المان‌های nestable سفارشی خود را بسازید.

یک نقطه شروع خوب برای یادگیری در مورد ساختار المان‌های Nestable، بررسی فایل‌های زیر در کد منبع Bricks است:

• accordion-nested.php
• slider-nested.php
• Tabs-nested.php

المان سفارشی خود را به عنوان "nestable" تعریف کنید

ابتدا مطمئن شوید که ویژگی $nestable در کلاس المان سفارشی خود را روی true تنظیم کنید.

این مورد ضروری است تا Bricks بداند که این المان سفارشی را با تابع render nestable در builder ارائه کند و Drag & Drop را داخل builder برای این المان سفارشی فعال کند.

الگوی المان Nestable

می‌توانید ساختار المان سفارشی خود را از طریق تابع get_nestable_children تعریف کنید. این تابع انتظار دارد آرایه‌ای از تعاریف المان‌ها را برگرداند.

این با نگاهی به تابع get_nestable_children المان Nestable Slider به‌خوبی نشان داده می‌شود:

public function get_nestable_children() {
  return [
      [
        'name'     => 'block',
        'label'    => esc_html__( 'Slide', 'bricks' ) . ' {item_index}',
        'settings' => [
          '_hidden' => [
            '_cssClasses' => 'hidden-class', // CSS class not visible in builder UI
          ],
        ],
        'children' => [
            [
              'name'     => 'heading',
              'settings' => [
                'text' => esc_html__( 'Slide', 'bricks' ) . ' {item_index}',
              ],
            ],
            [
              'name'     => 'button',
              'settings' => [
                'text'  => esc_html__( 'I am a button', 'bricks' ),
                'size'  => 'lg',
                'style' => 'primary',
              ],
            ],
          ],
      ],
  ];
}

کد بالا یک بلوک «Slide» داخل slider nestable اضافه می‌کند که سپس حاوی یک المان «Heading» و «Button» است.

ویژگی children، اگر تنظیم شود، آرایه‌ای از المان‌های تودرتو می‌پذیرد. آرایه settings را مشخص کنید تا در صورت نیاز المان‌های داخلی المان nestable مقداردهی اولیه شوند.

تابع Nestable Render (PHP)

تنها تابع جدیدی که باید به تابع render() PHP خود اضافه کنید render_children نام دارد و لازم است $this به‌عنوان اولین پارامتر ارسال شود:

public function render() {
  $output = "<div {$this->render_attributes( '_root' )}>";

  // Render children elements (= individual items)
  $output .= Frontend::render_children( $this );

  $output .= '</div>';

  echo $output;
}

تابع Nestable Render (Vue x-template)

برای رندر المان‌ها داخل المان nestable در x-template سفارشی خود، کافی است bricks-element-children را همان‌طور که در قطعه کد زیر نشان داده شده اضافه کنید:

public function render_builder() {
  <script type="text/x-template" id="tmpl-bricks-element-custom-nestable">
    <component :is="tag">
      <h2>Title before nestable children</h2>
      <bricks-element-children :element="element"/>
      <p>Text node after nestable children</p>
    </component>
  </script>
}

موارد المان‌های Nestable (در پانل)

اگر ساختار المان Nestable مبتنی بر موارد در همان سطح است (مانند Accordion در بالا)، می‌توانید با افزودن یک کنترل repeater با ویژگی items که روی children تنظیم شده، یک Repeater اضافه کنید (به پانل builder در تصویر بالا مراجعه کنید):

public function set_controls() {
  // Array of nestable element.children (@since 1.5)
  $this->controls['_children'] = [
    'type'          => 'repeater',
    'titleProperty' => 'label',
    'items'         => 'children',
  ];
];

توجه

اگر شروع به استفاده و/یا آزمایش با Nestable Elements API جدید برای المان‌های سفارشی خود کرده‌اید، ما دوست داریم نظرات شما را بشنویم. آیا این API هیچ ویژگی را از دست می‌دهد، آیا با اشکالی مواجه شده اید؟