Shortcode Class

Creating a Custom Shortcode Class

To create a custom shortcode in WooCommerce with YayMail, you’ll need to use the BaseShortcode class provided by YayMail as a starting point. Here’s a clear example to help you set up your own custom shortcode class

1. Extending BaseShortcode:

   class YourNewShortcodes extends \YayMail\Abstracts\BaseShortcode {
   
       private static $instance;
       
       public static function instance() {
   	if ( null === static::$instance ) {
   		static::$instance = new static();
   	}
   	return static::$instance;
       }
   
       protected function __construct() {
           /**
           * This refers to the array of template IDs where shortcodes can be applied.
           * We can assign it in 1 of 4 ways
           * 1. Special Array Templates ID: Examples include new_order, customer_processing_order.
           * 2. YAYMAIL_WITH_ORDER_EMAILS: Shortcodes applicable only for templates containing order information.
           * 3. YAYMAIL_NON_ORDER_EMAILS: Shortcodes applicable only for templates without order information.
           * 4. YAYMAIL_ALL_EMAILS: Shortcodes applicable to all email templates.
           */
           $this->available_email_ids = [ YAYMAIL_ALL_EMAILS ];
           parent::__construct();
       }
       
       public function get_shortcodes() {
        // Define your function here
       }
   }

   Begin by defining a new class that extends the BaseShortcode class provided by YayMail. Make sure to include essential variables and methods needed for the custom shortcode to work properly.

2. Function: get_shortcodes

   public function get_shortcodes() {    
       $shortcodes = [];
   
       $shortcodes[] = [
           'name'        => 'new_shortcode_1',
           'description' => 'Custom shortcode 1',
           'group'       => 'Custom Shortcode',
           'callback'    => [ $this, 'new_shortcode_1_render_function' ],
       ];
   
       $shortcodes[] = [
           'name'        => 'yaymail_new_shortcode_2',
           'description' => 'Custom shortcode 2',
           'attributes'  => [
               'text_link' => 'here',
           ],
           'group'       => 'Custom Shortcode',
           'callback'    => [ $this, 'new_shortcode_2_render_function' ],
       ];
   
       return $shortcodes;
   }

   The get_shortcodes function creates a list of shortcodes. Each shortcode follows this structure:

   When setting up a shortcode, include these key fields:

   • Name: A unique identifier for the shortcode.

   • Description: A short explanation of what the shortcode does.

   • Group: A category to organize related shortcodes together.

   • Callback: The function that generates the shortcode’s output.

   • Attributes (optional): Custom properties, like text_link or color, to enhance the shortcode’s functionality.

3. Callback function for a shortcode

   public function new_shortcode_1_render_function( $data ) {
       $render_data           = isset( $data['render_data'] ) ? $data['render_data'] : [];
       $is_placeholder        = isset( $data['is_placeholder'] ) ? $data['is_placeholder'] : false;
       $is_sample             = isset( $render_data['is_sample'] ) ? $render_data['is_sample'] : false;
       $is_customized_preview = isset( $render_data['is_customized_preview'] ) ? $render_data['is_customized_preview'] : false;
   
       $content            = 'Shortcode content sample';
   
       return $content;
   }
   
   public function new_shortcode_2_render_function( $data, $shortcode_atts = [] ) {
       $template = ! empty( $data['template'] ) ? $data['template'] : null;
       $is_placeholder = isset( $data['is_placeholder'] ) ? $data['is_placeholder'] : false;
       $text_link = isset( $shortcode_atts['text_link'] ) ? $shortcode_atts['text_link'] : '';
   
       if ( empty( $template ) ) {
           $text_link_color = YAYMAIL_COLOR_WC_DEFAULT;
       } else {
           $text_link_color = $template->get_text_link_color();
       }
       return '<a style="color: ' . esc_attr( $text_link_color ) . ';" href="' . esc_url( get_home_url() ) . '"> ' . $text_link . ' </a>';
   }

   This function fetches content for displaying shortcodes in the YayMail Editor and in actual emails. It uses two parameters: data and shortcode_atts (for shortcodes with attributes, if applicable).

   Variables:

   • data: Contains key properties like render_data, template, and is_placeholder.

   • shortcode_atts: An array of attributes defined for the shortcode in the get_shortcodes function.

   • render_data: Holds important details, such as order, is_sample, and is_customized_preview in the YayMail Editor. It also includes data from the get_content_html function when an actual email is sent.

   

   Email render data

   • is_placeholder: (Boolean) Indicates whether the value should be treated as a placeholder. Returns true if it is a placeholder, false otherwise.

   • is_sample: (Boolean) Returns true when a sample order is selected in the YayMail Editor, false otherwise.

   • is_customized_preview: (Boolean) Returns true when sending a test email or previewing an email in the YayMail Editor, false otherwise.

We’ve followed the steps provided, and the file now correctly includes the use YayMail\Abstracts\BaseShortcode statement.

class YourNewShortcodes extends \YayMail\Abstracts\BaseShortcode {

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

    protected function __construct() {
        /**
        * This refers to the array of template IDs where shortcodes can be applied.
        * We can assign it in 1 of 4 ways
        * 1. Special Array Templates ID: Examples include new_order, customer_processing_order.
        * 2. YAYMAIL_WITH_ORDER_EMAILS: Shortcodes applicable only for templates containing order information.
        * 3. YAYMAIL_NON_ORDER_EMAILS: Shortcodes applicable only for templates without order information.
        * 4. YAYMAIL_ALL_EMAILS: Shortcodes applicable to all email templates.
        */
        $this->available_email_ids = [ YAYMAIL_ALL_EMAILS ];
        parent::__construct();
    }
    
    public function get_shortcodes() {
        $shortcodes = [];
    
        $shortcodes[] = [
            'name'        => 'new_shortcode_1',
            'description' => 'Custom shortcode 1',
            'group'       => 'Custom Shortcode',
            'callback'    => [ $this, 'new_shortcode_1_render_function' ],
        ];
    
        $shortcodes[] = [
            'name'        => 'new_shortcode_2',
            'description' => 'Custom shortcode 2',
            'attributes'  => [
                'text_link' => 'here',
            ],
            'group'       => 'Custom Shortcode',
            'callback'    => [ $this, 'new_shortcode_1_render_function' ],
        ];
    
        return $shortcodes;
    }
    
    public function new_shortcode_1_render_function( $data ) {
        $render_data           = isset( $data['render_data'] ) ? $data['render_data'] : [];
        $is_placeholder        = isset( $data['is_placeholder'] ) ? $data['is_placeholder'] : false;
        $is_sample             = isset( $render_data['is_sample'] ) ? $render_data['is_sample'] : false;
        $is_customized_preview = isset( $render_data['is_customized_preview'] ) ? $render_data['is_customized_preview'] : false;
    
        $content            = 'Shortcode content sample';
    
        return $content;
    }

    public function new_shortcode_2_render_function( $data, $shortcode_atts = [] ) {
        $template = ! empty( $data['template'] ) ? $data['template'] : null;
        $is_placeholder = isset( $data['is_placeholder'] ) ? $data['is_placeholder'] : false;
        $text_link = isset( $shortcode_atts['text_link'] ) ? $shortcode_atts['text_link'] : '';
    
        if ( empty( $template ) ) {
            $text_link_color = YAYMAIL_COLOR_WC_DEFAULT;
        } else {
            $text_link_color = $template->get_text_link_color();
        }
        return '<a style="color: ' . esc_attr( $text_link_color ) . ';" href="' . esc_url( get_home_url() ) . '"> ' . $text_link . ' </a>';
    }
}