בניית תבנית מייל חדשה בווקומרס

בחודש האחרון קיבלתי לקוח אשר בעל חנות גדולה עם מעל ל-2,000 מוצרים.
במסגרת החנות שלו יש לו מחסן גדול אשר מממש את ההזמנות אשר מתבצעות באתר.
כחלק מטיפול בהזמנות המוצרים נשלחים בדואר ועבור כל משלוח מונפק קוד מעקב.
הלקוח רצה את האפשרות שהמחסן יוכל לשלוח מייל ללקוח עם פרטי קוד המעקב.

לאחר מחקר על מערכת המיילים של ווקומרס, הצלחתי לכתוב לו קוד אשר מוסיף תבנית מייל אשר תפקידה לשלוח את קוד המעקב ללקוח כאשר המחסן מעדכן את קוד העמקב.
במאמר זה אני אדגים כיצד ניתן ליצור תבנית מייל חדשה של ווקומרס ולאפשר לבעל החנות לבחור מתי לשלוח את תבנית המייל ללקוח.

שלב ראשון – הגדרת תבנית מייל חדשה

על מנת להגדיר תבנית מייל חדשה יש להרחיב את מחלקת הבסיס WC_Email של ווקומרס, מכיוון שזהו צעד מעט מורכב, אחלק אותו למספר תתי שלבים.

יצירת קוד בסיס

בשלב הראשון עלינו להגדיר וליצור תבנית מייל חדשה, על מנת לעשות זאת אנו מרחיבים את מחלקת הבסיס WC_Email של ווקומרס.
נפתח קובץ חדש עם השם class-custom-email.php תחת תיקיית emails/ בתוסף שלנו ונרשום בתוכו את הקוד הבא:

<?php
/**
 * Class Custom_Email
 *
 * @package    dorzki\WooCommerce\Custom_Email\Emails
 * @subpackage Custom_Email
 * @author     Dor Zuberi <webmaster@dorzki.co.il>
 * @link       https://www.dorzki.io
 * @version    1.0.0
 */

namespace dorzki\WooCommerce\Custom_Email\Emails;

use WC_Email;
use WC_Order;

// Block if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}


/**
 * Class Custom_Email
 *
 * @package dorzki\WooCommerce\Custom_Email\Emails
 */
class Custom_Email extends WC_Email {

}

הגדרות תבנית מייל

לאחר שכתבו את קוד הבסיס, עלינו להגדיר את פרטי תבנית המייל שלנו, נעשה זאת ע״י שימוש בפונקציית __construct().
בנוסף פונקציה זו תקרא לפונקציה המקבילה במחלקת האב על מנת להמשיך את תהליך הרישום.

/**
 * Custom_Email constructor.
 */
public function __construct() {

	// Email Details.
	$this->id = 'dorzki_wc_custom_email';
	$this->title = __( 'Custom Email', 'dorzki-wc-custom-email' );
	$this->description = __( 'Custom email template for WooCommerce.', 'dorzki-wc-custom-email' );

	$this->subject = __( 'Custom Email Subject', 'dorzki-wc-custom-email' );
	$this->customer_email = true;

	$this->template_html = 'views/custom-email.php';
	$this->template_plain = 'views/plain/custom-email.php';
	$this->template_base = DZ_WC_CEMAIL_PATH . 'emails/';

	$this->heading = __( 'Custom Email Title', 'dorzki-wc-custom-email' );

	parent::__construct();

}

בקוד הנ״ל אנו מגדירים מספר פרמטרים:

• id – מזהה כלשהו, יכול להכיל אותיות באנגלית, מספרים ומקף תחתון בלבד.
• title – כותרת תבנית המייל, הערך שיכנס כאן יופיעו בעמוד הגדרות אימיילים תחת ווקומרס.
• description – תיאור תבנית המייל, הערך שיכנס כאן יופיעו בעמוד הגדרות אימיילים תחת ווקומרס.
• subject – כותרת המייל אשר ישלח.
• customer_email – האם תבנית המייל אמורה להשלח ללקוח (true) או לאדמין (false).
• template_html – נתיב ושם הקובץ אשר מכיל את קוד ה-HTML של תבנית המייל.
• template_plain – נתיב ושם הקובץ אשר מכיל את תוכן תבנית המייל שלנו כאשר לא נשלח מיילים מסוג HTML.
• template_base – נתיב לתיקיית התבניות של התוסף.
• heading – הכותרת הראשית של המייל אשר מוצגת בחלק הסגול בתבנית.

הגדרת קוד שליחה

לאחר שהגדרנו את תבנית המייל עלינו להגדיר את שליחת התבנית, לרוב הקוד יהיה זהה ברוב התבניות אלא אם כן תרצו לבצע לוגיקה שונה עבור תבנית המייל.
במקרה שלנו אנחנו שולחים תבנית רגילה וסטנדרטית לכן אין פה קוד מורכב מידי. ניצור פונקציה חדשה בשם trigger ונרשום בה את הקוד הבא:

/**
 * Triggered on event.
 *
 * @param WC_Order $order current order object.
 *
 * @return void
 */
public function trigger( $order ) {

	if ( ! $order instanceof WC_Order ) {
		return;
	}

	$this->object = $order;
	$this->recipient = $this->object->get_billing_email();

	if ( ! $this->is_enabled() || ! $this->get_recipient() ) {
		return;
	}

	$this->send( $this->get_recipient(), $this->get_subject(), $this->get_content(), $this->get_headers(), $this->get_attachments() );

}

הפונקציה מקבלת אובייקט מסוג WC_Order אשר מכיל את ההזמנה הנוכחית.
לאחר מכן מתבצעת בדיקה תקינות שמטרתה לוודא שקיבלנו אובייקט תקין מסוג WC_Order, שמירה של אובייקט ההזמנה למשתנה של המחלקה, והגדרת כתובת מקבל המייל לכתובת מייל החיוב של ההזמנה.
לאחר מכן מתבצעת בדיקה שבודקת האם התבנית פעילה ושהוגדרה כתובת מייל לקבלת המייל ולבסוף שליחה של תבנית המייל.

טעינת תבנית המייל

שתי הפונקציות הבאות אחריות על טעינת קובץ התבנית של תבנית המייל החדשה שלנו, אחת עבור טעינת תבנית מייל מסוג HTML והשנייה עבור טעינת תבנית מייל מסוג טקסט פשוט (Plain).

/**
 * Get content html.
 *
 * @return string
 */
public function get_content_html() {

	return wc_get_template_html( $this->template_html, [
		'order'         => $this->object,
		'email_heading' => $this->get_heading(),
		'sent_to_admin' => false,
		'plain_text'    => false,
		'email'         => $this,
	], '', $this->template_base );

}


/**
 * Get content plain.
 *
 * @return string
 */
public function get_content_plain() {

	return wc_get_template_html( $this->template_plain, [
		'order'         => $this->object,
		'email_heading' => $this->get_heading(),
		'sent_to_admin' => false,
		'plain_text'    => true,
		'email'         => $this,
	], '', $this->template_base );

}

אנו משתמשים בפונקציה המובנת wc_get_template_html על מנת לקרוא לקובץ של תבנית המייל שלנו.
אנו משתמשים בפונקציה זו על מנת שנוכל לאפשר למי שישתמש בתוסף שלנו להעתיק את קבצי תבנית המייל לתבנית.
זאת על מנת שהוא יוכל ישנו את נראות המייל ותוכן המייל דרך תבנית הוורדפרס שלו.

שלב שני – עיצוב ועימוד תבנית המייל

לאחר שבנינו את קוד הגדרת תבנית המייל עלינו לבנות את המייל עצמו שישלח ואת התוכן שלו.
על מנת לעשות זאת אנו צריכים לבנות שני קבצים, האחד לתבנית מייל מסוג HTML והשנייה לתבנית מייל מסוג טקסט פשוט.
שימו לב כי הנתיבים ושמות הקבצים חייבים להיות תואמים למה שהגדרנו בערכי ה-template_* בפונקציית ה-__construct() בשלב הקודם.

בניית תבנית מייל HTML

ניצור קובץ חדש בשם custom-email.php תחת הנתיב emails/views/ בתיקיית התוסף שלנו ונדביק בה את הקוד הבא:

<?php

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/*
 * @hooked WC_Emails::email_header() Output the email header
 */
do_action( 'woocommerce_email_header', $email_heading, $email ); ?>

	<p><?php esc_html_e( 'This is our custom email content.', 'dorzki-wc-custom-email' ); ?></p>

<?php

/*
 * @hooked WC_Emails::customer_details() Shows customer details
 * @hooked WC_Emails::email_address() Shows email address
 */
do_action( 'woocommerce_email_customer_details', $order, $sent_to_admin, $plain_text, $email );

/*
 * @hooked WC_Emails::email_footer() Output the email footer
 */
do_action( 'woocommerce_email_footer', $email );

על מנת לשאוב את הגדרות העיצוב והעימוד של שאר תבניות המייל הקיימות, אנו מייבאים את ה-Header ו-Footer של תבניות המייל הדיפולטיביות של ווקומרס.
לאחר ה-Header אנו מכניסים את הקוד והתוכן אותו נרצה לשלוח בגוף המייל. ולבסוף אנו מדפיסים את פרטי הלקוח.

בניית תבנית טקסט פשוטה (Plain)

ניצור קובץ חדש בשם custom-email.php תחת הנתיב emails/views/plain/ בתיקיית התוסף שלנו ונדביק בה את הקוד הבא:

<?php

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

echo '= ' . esc_html( $email_heading ) . " =\n\n";

/* translators: %s: Customer billing full name */
echo esc_html_e( 'This is our custom email content.', 'dorzki-wc-custom-email' ) . "\n\n";

echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=\n\n";

/*
 * @hooked WC_Emails::customer_details() Shows customer details
 * @hooked WC_Emails::email_address() Shows email address
 */
do_action( 'woocommerce_email_customer_details', $order, $sent_to_admin, $plain_text, $email );

echo "\n=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=\n\n";

echo esc_html( apply_filters( 'woocommerce_email_footer_text', get_option( 'woocommerce_email_footer_text' ) ) );

שלב שלישי – רישום תבנית המייל החדשה

לאחר שבנינו את תבנית המייל שלנו, והכנסו את התוכן הרלוונטי, עלינו לרשום את תבנית המייל.
רישום זה יאפשר לנו לראות אותה בפאנל הניהול ועל מנת שווקומרס תדע להתייחס אליה.
נפתח קובץ חדש בתיקיית התוסף הראשית שלנו ונרשום בה את הקוד הבא:

/**
 * Register custom emails.
 *
 * @param array $emails WooCommerce registered emails.
 *
 * @return array
 */
function dorzki_wc_register_emails( $emails ) {

	require_once 'emails/class-custom-email.php';

	$emails['custom_email'] = new Custom_Email();

	return $emails;

}

add_filter( 'woocommerce_email_classes', 'dorzki_wc_register_emails' );

אנו מקבלים בפונקציה זו מערך אשר מכיל את כל המיילים הבסיסיים של ווקומרס, למערך זה אנו מכניסים את התבנית שבנינו בשלב הראשון.
שימו לב שיש לתת מזהה יחודי לתבנית המייל שלנו (במקרה שלנו custom_email) וזאת על מנת שלא נדרוס תבניות מייל אחרות.

לאחר רישום התבנית, נוכל להכנס להגדרות תבנית המיילים של ווקומרס תחת ווקומרס -> הגדרות -> אימיילים, ושם נוכל לראות את תבנית המייל החדשה שלנו.

שלב רביעי – אפשור שליחת המייל

לאחר שרשמנו את תבנית המייל שלנו, עלינו לאפשר למנהל האתר לשלוח את תבנית המייל בצורה אוטומטית.
נוכל לעשות זאת ע״י שימוש בתיבת ״פעולות״ אשר נמצאת כאשר צופים בהזמנה, כך נוכל לאפשר למנהל האתר לשלוח את תבנית המייל בלחיצת כפתור.

רישום פעולה חדשה

בתור התחלה עלינו לרשום את הפעולה, נעשה זאת ע״י שימוש בפילטר woocommerce_order_actions באופן הבא:

/**
 * Register custom order actions.
 *
 * @param array $actions WooCommerce registered order actions.
 *
 * @return array
 */
function dorzki_wc_register_actions( $actions ) {

	$actions['dorzki_wc_send_custom_email'] = __( 'Send Custom Email', 'dorzki-wc-custom-email' );

	return $actions;

}

add_filter( 'woocommerce_order_actions', 'dorzki_wc_register_actions' );

הרישום מורכב משני חלקים חשובים, האחד, מזהה הפעולה, בו נשתמש בהמשך בשביל לזהות את הפעולה ולהפעיל את שליחת המייל.
החלק השני הוא שם הפעולה, זה בעצם מה שיוצג למנהל האתר על מנת שידע מהי הפעולה.

שליחת תבנית המייל

לאחר שרשמו את הפעולה, עלינו להגדיר מה יקרה כאשר בעל האתר רוצה לבצע את הפעולה, נעשה זאת ע״י כתיבת הקוד הבא:

/**
 * Send custom email on request.
 *
 * @param WC_Order $order current order.
 */
function dorzki_wc_send_custom_email( $order ) {

	WC()->mailer()->emails['custom_email']->trigger( $order );

	// Optional: Add order note.
	$order->add_order_note( __( 'Custom Email Sent!', 'dorzki-wc-custom-email' ), false, false );

}

add_action( 'woocommerce_order_action_dorzki_wc_send_custom_email', 'dorzki_wc_send_custom_email' );

ההוק שלנו מורכב משני חלקים, החלק הראשון הוא woocommerce_order_action_ והחלק השני ממזה הפעולה שהגדרנו בעת רישום הפעולה.
כאשר פונקציה זו תקרא, אנו מבקשים לקבל את מנהל המיילים של ווקומרס ואשר ניגשים לתבנית המייל שלנו לפי המזהה שהשתמש בעת הרישום ומפעילים את פונקציית trigger אשר אחראית על השליחה.

על מנת לשמור על היסטוריית הפעולות, אנחנו מוסיפים להזמנה גם הערה אשר אומרת שהמייל נשלח, זהו צעד לא הכרחי, אך בהחלט עוזר לתיעוד הפעולה שהמייל נשלח.

סיכום

הוספת תבנית מייל יכולה לתרום לבעל החנות כאשר יש תבניות מייל אשר צריכות להישלח במקרים מסויימים, עם מספר שינויים בקוד ניתן להגדיר אפילו שליחה אוטומטית של תבנית המייל.