Egyéni elem készítése

Saját elemet a WordPress-widgetekhez hasonló módon készíthetsz: kiterjeszted a Bricks\Element osztályt, és kitöltöd az elemhez szükséges tulajdonságokat és metódusokat. A Bricks gyermektéma egy egyszerű bemutató elemet már tartalmaz.

Az elem kódját a gyermektéma gyökérmappájában hozd létre, például element-test.php néven.

Üres elemosztály

<?php
if ( ! defined( 'ABSPATH' ) ) exit; // Kilépés, ha közvetlenül hívják

class Prefix_Element_Test extends \Bricks\Element {
  // Tulajdonságok
  public $category     = '';
  public $name         = '';
  public $icon         = '';
  public $css_selector = '';
  public $scripts      = [];
  public $nestable     = false;

  // Metódusok: a szerkesztőhöz
  public function get_label() {}
  public function get_keywords() {}
  public function set_control_groups() {}
  public function set_controls() {}

  // Metódusok: a webhelyhez
  public function enqueue_scripts() {}
  public function render() {}
}

Tulajdonságok

Tulajdonság	Jelentés
$category (kötelező)	Az elem kategóriájának neve, csupa kisbetűvel, szóköz nélkül. Használhatsz előre megadott kategóriát (például general, media), vagy sajátot. Saját kategóriához a szerkesztő számára fordítható feliratot is adj a bricks/builder/i18n szűrővel.
$name (kötelező)	Az elem egyedi azonosítója, csupa kisbetűvel, szóköz nélkül. Az ütközések elkerülésére adj neki előtagot, például prefix-element-test.
$icon	Az elem ikonjának CSS-osztálya a szerkesztő paneljében. A Bricks három ikonbetűkészletet tartalmaz: Font Awesome 6 (például fas fa-anchor), Ionicons 4 (például ion-md-alarm) és Themify Icons (például ti-bolt-alt).
$css_selector	Alapból minden CSS-vezérlő a .bricks-element-wrapper burkolóra vonatkozik. Ha egy belső HTML-elemre akarod irányítani, itt add meg a szelektort.
$nestable	Egyszerű elemnél hagyd el. true értékkel egymásba ágyazható elem lesz belőle (lásd az Egymásba ágyazható elemek fejezetet).
$scripts	Azon JavaScript-függvények tömbje, amelyek az elem megjelenítésekor a webhelyen, illetve a szerkesztőben való frissítésekor futnak. A Számláló elem például a bricksCounter szkriptet használja (public $scripts = ['bricksCounter'];). A saját szkripteknek is adj előtagot, például prefixElementTest.

Metódusok

Metódus	Feladat
get_label() (kötelező)	Az elem lefordított felirata.
get_keywords()	Kulcsszavak tömbje. Ha a szerkesztő elemkeresője ezekre keres, az elem megjelenik a találatok között.
set_control_groups()	Alapból az elem összes vezérlője csoportosítás nélkül a Tartalom fülön jelenik meg. Itt vezérlőcsoportokat adhatsz meg, csoportonként title (lefordított cím) és tab (content vagy style) értékkel.
set_controls() (kötelező)	Az elem vezérlőinek definíciója.
enqueue_scripts()	Az elemhez tartozó szkriptek és stíluslapok betöltése. Ezek csak azokon az oldalakon töltődnek be, ahol az elem szerepel, ami jobb teljesítményt ad. Például: wp_enqueue_script( 'prefix-element-test', get_template_directory_uri() . '/js/custom.js', ['jquery'], '1.0', true );
render() (kötelező)	Kiírja az elem HTML-jét. A HTML-attribútumokat a $this->set_attribute() állítja be, és a $this->render_attributes() írja ki.

Segédfüggvények a megjelenítéshez

Függvény	Feladat
set_attribute( $key, $attribute, $value )	Bármelyik HTML-címke attribútumát beállítja. A $key a címke egyedi azonosítója, az $attribute az attribútum neve, a $value pedig szöveg vagy tömb az érték(ek)kel.
render_attributes( $key )	Kiírja a set_attribute() segítségével megadott attribútumokat a $key azonosítójú címkéhez.
render_dynamic_data_tag( $tag, $context, $args )	Dinamikus adat címkét (például {post_title}) jelenít meg a render() függvényben. A segédfüggvény a megfelelő bejegyzésazonosítót állítja be attól függően, hol jelenik meg az elem.
render_dynamic_data( $content )	Dinamikus adat címkéket tartalmazó szöveget jelenít meg. Ez is a megfelelő bejegyzésazonosítót állítja be a környezetnek megfelelően.

Teljes példa

<?php
if ( ! defined( 'ABSPATH' ) ) exit; // Kilépés, ha közvetlenül hívják

class Prefix_Element_Test extends \Bricks\Element {
  public $category     = 'general';              // Előre megadott kategória
  public $name         = 'prefix-test';          // Mindig adj előtagot
  public $icon         = 'ti-bolt-alt';          // Themify-ikon
  public $css_selector = '.prefix-test-wrapper'; // Alapértelmezett CSS-szelektor
  public $scripts      = ['prefixElementTest'];  // Az elem megjelenítésekor futó szkript

  // Az elem lefordított felirata
  public function get_label() {
    return esc_html__( 'Test element', 'bricks' );
  }

  // Vezérlőcsoportok
  public function set_control_groups() {
    $this->control_groups['text'] = [
      'title' => esc_html__( 'Text', 'bricks' ),
      'tab'   => 'content',
    ];

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

  // Vezérlők
  public function set_controls() {
    $this->controls['content'] = [
      'tab'     => 'content',
      'group'   => 'text',
      'label'   => esc_html__( 'Content', 'bricks' ),
      'type'    => 'text',
      'default' => esc_html__( 'Content goes here ..', 'bricks' ),
    ];

    $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',
    ];
  }

  // Szkriptek és stílusok betöltése
  public function enqueue_scripts() {
    wp_enqueue_script( 'prefix-test-script' );
  }

  // Az elem HTML-jének kiírása
  public function render() {
    $root_classes[] = 'prefix-test-wrapper';

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

    // A gyökércímke class attribútuma
    $this->set_attribute( '_root', 'class', $root_classes );

    // A '_root' attribútum kötelező: ez tartalmazza az elem azonosítóját, osztályait stb.
    echo "<div {$this->render_attributes( '_root' )}>";
      if ( ! empty( $this->settings['content'] ) ) {
        echo "<div>{$this->settings['content']}</div>";
      }
    echo '</div>';
  }
}

A vezérlők típusai és beállításai a Bricks vezérlődokumentációjában vannak felsorolva. A példában a text és a select típust használtuk.

Az elem betöltése és regisztrálása

Az elkészült elemet be kell tölteni és regisztrálni. Nyisd meg a gyermektéma functions.php fájlját, és illeszd be:

/**
 * Egyéni elemek regisztrálása
 */
add_action( 'init', function() {
  $element_files = [
    __DIR__ . '/element-test.php',
  ];

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

A register_element három paramétert fogad:

• $file (kötelező): az egyéni elem PHP-fájljának teljes útvonala a szerveren.
• $name (nem kötelező): az elem neve, például prefix-element-test.
• $element_class (nem kötelező): az elem osztályának neve, például Prefix_Element_Test. Az osztálynak a \Bricks\Element osztályból kell származnia.