# Egyéni elem készítése

> Saját Bricks-elem programozása: az elemosztály tulajdonságai és metódusai, vezérlők, megjelenítés, szkriptek betöltése és az elem regisztrálása.

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
<?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](https://hub.hellowp.io/hu/plugins/bricks-child/fejlesztoknek-egymasba-agyazhato-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
<?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:

```php
/**
 * 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.