> For the complete documentation index, see [llms.txt](https://docs.yaycommerce.com/yaymail/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yaycommerce.com/yaymail/developer-zone/api/register-shortcodes/shortcode-class.md).
# 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`**:**
```php
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`
```php
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
```php
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 ' ' . $text_link . ' ';
}
```
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.
```php
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 ' ' . $text_link . ' ';
}
}
```