Egymásba ágyazható elemek (API)

Az egymásba ágyazható (nestable) elemek olyan elemek, amelyek más elemeket tartalmazhatnak, pontosan abban a szerkezetben, amilyenben szeretnéd. Ehhez a Bricks programozói felületet (API-t) is ad, amellyel saját ilyen elemet készíthetsz.

Miért jók

Korábban a Bricks minden eleme „lapos” volt. Hiába volt mély HTML-szerkezete (például a Diavetítésnek), a belsejében nem kattinthattál egy részre, hogy közvetlenül szerkeszd (például a 3. dia tartalmát), és a belső szerkezetet sem alakíthattad át húzással, ahogy egy elrendezéselemben. Ezért az összetettebb elemek (Ikondoboz, Árazási táblázat, Lista) testreszabása gyakran nehézkes volt, a Harmonikáé, a Diavetítésé és a Füleké pedig szinte lehetetlen.

Három egymásba ágyazható elem van: Harmonika (egymásba ágyazható), Diavetítés (egymásba ágyazható) és Fülek (egymásba ágyazható). Mivel minden diát azokkal az elemekkel tölthetsz meg, amelyeket szeretnél, az olyan célelemekre, mint a Körhinta és a Csapattagok, már kevésbé van szükség. Érdemes ezeket kipróbálni, és fokozatosan áttérni rájuk a régi, egyszerű elemekről.

A programozói felület jó kiindulópontja a Bricks három egymásba ágyazható elemének forráskódja: accordion-nested.php, slider-nested.php és tabs-nested.php.

Saját egymásba ágyazható elem

1. Jelöld nestable-nek

Az elemosztályban állítsd a $nestable tulajdonságot true értékre. Ettől tudja a Bricks, hogy az elemet az egymásba ágyazható megjelenítő függvénnyel kell kirajzolni, és hogy a szerkesztőben engedélyeznie kell a húzással való elhelyezést.

2. Az elem sablonja

Az elem szerkezetét a get_nestable_children függvény adja meg, amely elemdefiníciók tömbjét adja vissza. A Diavetítés elem példáján látszik a legjobban:

public function get_nestable_children() {
  return [
    [
      'name'     => 'block',
      'label'    => esc_html__( 'Slide', 'bricks' ) . ' {item_index}',
      'settings' => [
        '_hidden' => [
          '_cssClasses' => 'hidden-class', // A szerkesztő felületén nem látszó CSS-osztály
        ],
      ],
      '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',
          ],
        ],
      ],
    ],
  ];
}

A fenti kód egy „Slide” blokkot ad a diavetítéshez, amely egy Címsor és egy Gomb elemet tartalmaz. A children tulajdonság (ha megadod) további beágyazott elemek tömbje. A settings tömbbel az egyes elemeket töltheted ki.

3. Megjelenítés PHP-ban

A render() függvényedbe egyetlen új hívást kell tenned: a render_children függvényt, az elempéldánnyal ($this) első paraméterként:

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

  // A gyermekelemek (az egyes tételek) kiírása
  $output .= Frontend::render_children( $this );

  $output .= '</div>';

  echo $output;
}

4. Megjelenítés a szerkesztőben (Vue x-template)

Ha az elemed a szerkesztőben saját x-template-et használ, a gyermekelemeket a bricks-element-children komponenssel jelenítsd meg, az element paraméterrel:

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>
<?php }

5. Tételek a panelben

Ha az elem szerkezete azonos szinten lévő tételekből áll (mint a Harmonika), a panelben ismétlő (repeater) vezérlővel kezelheted őket. Adj a vezérlőhöz repeater típust, és állítsd az items tulajdonságot children értékre:

public function set_controls() {
  // Az egymásba ágyazott elem gyermekeinek tömbje
  $this->controls['_children'] = [
    'type'          => 'repeater',
    'titleProperty' => 'label',
    'items'         => 'children',
  ];
}

A titleProperty mondja meg, melyik tulajdonság szolgál a tétel címeként a listában.