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

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:

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:

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:

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:

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

A teljes osztály

/**
 * 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

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.