# Fejlesztőknek: e-mail sablonok regisztrálása

> Saját e-mail sablon felvétele a YayMailbe: regisztráció, az e-mail osztálya és a sablonfájl.

Ha egy saját bővítményed új e-mailt küld, azt sablonként regisztrálhatod a YayMailben. Az e-mail ezután megjelenik az **Email Templates** listában, és a szerkesztőben ugyanúgy szerkeszthető, mint a WooCommerce saját e-mailjei. Három részből áll: a regisztrációból, az e-mail osztályából és a sablonfájlból.

## 1. Regisztráció

Az új e-mailt a `yaymail_register_emails` akcióra kapcsolódva regisztrálod. Az akció megkapja a sablonokat kezelő objektumot, amelynek a `register()` metódusával adod át az e-mail osztályod példányát:

```php
public function register_emails( $yaymail_emails ) {
    $yaymail_emails->register( YourNewEmail::get_instance() );
}

add_action( 'yaymail_register_emails', 'register_emails' );
```

## 2. Az e-mail osztálya

Az osztálynak a YayMail `BaseEmail` absztrakt osztályából kell öröklődnie. A konstruktorban a következő tulajdonságokat add meg:

| Tulajdonság | Jelentése |
|---|---|
| `id` | Egyedi azonosító. Érdemes megegyeznie a WooCommerce e-mail azonosítójával, így könnyebb kezelni. |
| `title` | Az e-mail neve, ahogy a YayMail szerkesztőjében és a beállításokban megjelenik. |
| `recipient` | A címzett: például `Customer` (vásárló) vagy `Admin`, esetleg más forrás. |
| `source` | Tömb a bővítmény adataival: `plugin_id` (tetszőleges azonosító) és `plugin_name` (annak a bővítménynek a neve, amelyhez az e-mail tartozik). |
| `email_types` | Az e-mail típusa. `YAYMAIL_WITH_ORDER_EMAILS`: rendelési adatokat tartalmazó e-mail. `YAYMAIL_NON_ORDER_EMAILS`: rendelési adatok nélküli e-mail. Ha nem adod meg, az alapértelmezett a `YAYMAIL_WITH_ORDER_EMAILS`. |

Az osztály `instance()` metódusa egyetlen példányt (singleton) ad vissza.

### Alapértelmezett elemek

A `get_default_elements()` metódus adja vissza azokat az elemeket, amelyekkel az új sablon induláskor megjelenik. Az elemeket az `ElementsLoader::load_elements()` tölti be, a típusukat és az attribútumaikat egy tömbben adod meg:

```php
public function get_default_elements() {
    $default_elements = \YayMail\Elements\ElementsLoader::load_elements(
        [
            [
                'type' => 'Logo',
            ],
            [
                'type'       => 'Heading',
                'attributes' => [
                    'rich_text' => 'Email Heading',
                ],
            ],
            [
                'type'       => 'Text',
                'attributes' => [
                    'rich_text' => '<p><span>Email content</span></p>',
                ],
            ],
            [
                'type' => 'Footer',
            ],
        ]
    );

    return $default_elements;
}
```

Ez a minta egy logót, egy „Email Heading” szövegű címsort, egy szövegblokkot és egy láblécet tartalmazó sablont ad.

### Az e-mail küldésének kapcsolása

Az e-mail kiküldését kiváltó hookot a konstruktorban kötheted be. A `BaseEmail` osztály erre alapértelmezett metódust ad, amelyet felülírhatsz, ha egyedi működés kell. Ugyancsak a konstruktorban kapcsolhatod be a sablonfájl útvonalát megadó szűrőt:

```php
add_filter( 'wc_get_template', [ $this, 'get_template_file' ], 10, 1 );
```

### A sablonfájl útvonala

A `get_template_path()` metódus azt a PHP-fájlt adja vissza, amely az e-mail tartalmát előállítja:

```php
public function get_template_path() {
    return __DIR__ . '/templates/your-new-email-template.php';
}
```

### A teljes osztály

```php
/**
 * YourNewEmail osztály
 *
 * @method static YourNewEmail get_instance()
 */
class YourNewEmail extends \YayMail\Abstracts\BaseEmail {
    private static $instance;

    public static function instance() {
        if ( null === static::$instance ) {
            static::$instance = new static();
        }
        return static::$instance;
    }

    public $email_types = [ YAYMAIL_WITH_ORDER_EMAILS ];

    protected function __construct() {
        $this->id        = 'your_new_email_template_id';
        $this->title     = 'Your New Email';
        $this->recipient = 'Customer';

        $this->source = [
            'plugin_id'   => '3rd-plugin-slug',
            'plugin_name' => 'The plugin email belong to',
        ];
    }

    public function get_default_elements() {
        // lásd fent
    }

    public function get_template_path() {
        return __DIR__ . '/templates/your-new-email-template.php';
    }
}
```

## 3. A sablonfájl: a tartalom kirajzolása

A `get_template_path()` által megadott fájl (például a bővítmény `templates/new-email-1.php` fájlja) kéri le a sablon tartalmát, és írja ki az e-mailbe:

```php
<?php

defined( 'ABSPATH' ) || exit;

$template = YourNewEmail::get_instance()->template;

if ( ! empty( $template ) ) {
    $content = $template->get_content( $args );
    yaymail_kses_post_e( $content );
}
```

Az `$args` változót a WooCommerce adja át a fájlnak. Az e-mail adatai vannak benne, például a rendelés, az e-mail címsora, a kiegészítő tartalom, hogy az e-mail az adminnak megy-e, és hogy sima szöveges-e. A kód ellenőrzi, hogy a sablon létezik-e, és ha igen, az `$args` alapján előállítja a tartalmát. A kimenetet a `yaymail_kses_post_e()` függvény írja ki, amely a nem biztonságos HTML-t kiszűri.