VOOZH about

URL: https://deepwiki.com/MahoCommerce/maho/14.7-email-template-directives

⇱ Email Template Directives | MahoCommerce/maho | DeepWiki

Loading...
Loading...
Last indexed: 15 May 2026 (ea8ab8)
Menu

Email Template Directives

Purpose and Scope

Email template directives are a templating syntax used in Maho to insert dynamic content into email templates, newsletters, CMS pages, and blocks. Directives use double-curly-brace syntax ({{...}}) to inject variables, configuration values, widgets, and blocks into content.

In the Maho backend, these directives are processed by a specialized filter system Mage_Core_Model_Email_Template_Filter which extends the base template filter class. This page is a detailed technical reference of the email template syntax, variables, and the directive parsing implementation, covering the data flow and key classes involved.

Directive Syntax

All directives follow the general syntax pattern:



    

  • type: The directive type, e.g., var, config, block, layout, skin, media.
    • 

  • Key-value pairs provide parameters dependent on the directive type.
    • 



There is also a shorthand for variable directives:




This is parsed internally equivalently to:




Parameters are parsed by the tokenizer class Maho\Filter\Template\Tokenizer\Parameter to extract the key-value pairs in the directive's parameter string app/code/core/Mage/Core/Model/Email/Template/Filter.php239-245




Directive Types


1. Variable Directives (var)


Inject template variables passed during email sending. For example:




Variables are passed as an array argument to the send() method of the template model (Mage_Core_Model_Email_Template) app/code/core/Mage/Core/Model/Email/Template.php25-29 The filter replaces {{var ...}} by looking up variables by their paths in the passed variable set.


2. Configuration Directives (config)


Retrieve values from Maho's configuration, typically stored in core_config_data, e.g.:




The class Mage_Core_Model_Email_Template defines constants for config paths related to email sending, like XML_PATH_TEMPLATE_EMAIL app/code/core/Mage/Core/Model/Email/Template.php77-80 These config values can be injected dynamically into templates.


3. Block Directives (block)


Used to instantiate and render blocks (view components) inside email templates. Syntax example:




The filter method blockDirective() implements this by parsing the parameters and creating the block via the layout singleton (Mage_Core_Model_Layout::createBlock) if the block type is on the allowlist app/code/core/Mage/Core/Model/Email/Template/Filter.php141-181 This ensures only safe block types can render in emails.


4. Layout Directives (layout)


Layouts can be included by handle within email templates to assemble complex contents like order item tables. Example:




The filter's layoutDirective() creates a new layout instance, loads the specified handle, generates XML and blocks for it, and renders the output app/code/core/Mage/Core/Model/Email/Template/Filter.php190-231


5. Skin Directives (skin)


Generate URLs to skin assets (CSS, JS, images) to be included in templates, with optionally absolute URLs. Example:






Directive Processing Architecture


Email templates are raw text with embedded directives bridging natural language to executable code entities. Processing involves several layered classes:


    

  • Mage_Core_Model_Email_Template: Primary model to load and send email templates. Provides variables and template body.
    • 

  • Mage_Core_Model_Email_Template_Filter: Processes directive parsing and replacement.
    • 

  • Maho\Filter\Template: Base template filter class extended by the email template filter.
    • 



Call flow for processing directives in email:






Security and Validation


Maho implements critical security measures during email template directive evaluation:



These combined controls ensure directive usage cannot compromise system security when processing email content.




Template Metadata Extraction


Default email templates contain embedded metadata wrapped inside HTML comments to specify email subjects, variable hints for UI, and styles.



























Metadata TagRegex PatternPurpose
@subject/<!--@subject\s*(.*?)\s*@-->/uExtracts the email subject line Template.php156-159
@vars/<!--@vars\s*((?:.)*?)\s*@-->/usExtracts variables available to the template (for admin UI display) Template.php161-165
@styles/<!--@styles\s*(.*?)\s*@-->/sExtracts inline CSS styles for the template Template.php167-169


When a default template is loaded (loadDefault()), these are parsed out and stored in corresponding model properties. The comments are then removed, and internal {* *} style template comments are stripped from the final template text app/code/core/Mage/Core/Model/Email/Template.php140-180




Implementation Flow: Default Template Loading


The process of loading a default email template with metadata parsing can be summarized as:




    

  • loadDefault() calls getDefaultTemplates() to retrieve template config.
    • 

  • Fetches template file contents via translation system.
    • 

  • Uses regex patterns to extract subject, variables, styles embedded as HTML comments.
    • 

  • Removes Maho-style template comments.
    • 

  • Saves the cleaned text and metadata into the model.
    • 



This flow ensures rich email templates with consistent metadata and content sanitization app/code/core/Mage/Core/Model/Email/Template.php140-180 app/code/core/Mage/Core/Model/Email/Template.php156-174




Summary Table of Key Classes and Methods






























































Class/MethodPurposeLocation
Mage_Core_Model_Email_TemplateEmail template model, template loading, sending, default template metadata parsingapp/code/core/Mage/Core/Model/Email/Template.php
getTemplateFilter()Returns the email template filter for parsing directivesTemplate.php111-119
loadDefault($templateId)Loads a default template with metadata extractionTemplate.php140-180
Mage_Core_Model_Email_Template_FilterProcesses template directives, extended from Maho\Filter\Templateapp/code/core/Mage/Core/Model/Email/Template/Filter.php
blockDirective($construction)Parses and renders block directivesTemplate/Filter.php141-181
layoutDirective($construction)Parses and renders layout directivesTemplate/Filter.php190-231
Maho\Filter\Template\Tokenizer\ParameterTokenizer class to parse directive parametersUsed in Template/Filter.php239-245
Mage_Admin_Model_Block::isTypeAllowed()Security check for allowed block typesTemplate/Filter.php149-154
Mage_Admin_Helper_Rules_Fallback::fallbackResourcePermissions()ACL fallback for permissionsapp/code/core/Mage/Admin/Helper/Rules/Fallback.php
Mage_Adminhtml_System_ConfigControllerManages config ACL checksapp/code/core/Mage/Adminhtml/controllers/System/ConfigController.php




References and Further Reading


    

  • 

    Code files
    

      

    • app/code/core/Mage/Core/Model/Email/Template.php 
      • 

    • app/code/core/Mage/Core/Model/Email/Template/Filter.php 15-231
      • 

    • app/code/core/Mage/Admin/Helper/Rules/Fallback.php 18-66
      • 

    • app/code/core/Mage/Adminhtml/controllers/System/ConfigController.php 13-196
      • 

    

    • 

  • 

    Tokenizer
    

      

    • Maho\Filter\Template\Tokenizer\Parameter (used for parsing parameters in directives)
      • 

    

    • 





This completes the detailed reference on Email Template Directives handling in Maho.