What is a Directive?
What is the purpose of a directive? To put it simply, a directive executes code that inserts content onto a page or email.
What is the Output Generated by the Directives in The above Image?
The above image is a picture of the location in the Magento CMS where you can edit the text on the homepage. So, I’m going to refresh the homepage to see what the directives do……….
The directives in the very first image of this article produce the output shown directly above. Below, is a summary of what is going on:
What do Each of These Directives Do?
The “config” Directive
The first two examples in the above image are “config” directives. These directives are calling the function Mage::getStoreConfig($path). They are passing the “path” into this function. How do we know the Mage::getStoreConfig() function is being called?
Every directive has one function that is responsible for outputting it. The function responsible for outputting the “config” directive is called configDirective. The function responsible for outputting the “media” directive is called mediaDirective. The function that outputs the “skin” directive is called skinDirective. And, so on, and so forth….
All of the functions that output the directives in the above image are located in the class Mage_Core_Model_Email_Template_Filter.
Let’s take a look at the configDirective function:
The above picture shows that the “path” is being inserted into the Mage::getStoreConfig($path) function. Please note that the value of $params[‘path’] is the value you passed into it (general/locale/timezone) as the picture below illustrates.
The getStoreConfig($path) function is pulling data from the core_config_data table. There is a column in this table called path. This function will find the row in this table whose path is equal to the value we specified, “general/locale/timezone”. Then, this function will pull the ‘value’ from this row. The ‘value’ is then output to your screen.
(note: there are certain circumstances where this value will come from a config.xml if it does not exist in the database.)
Please note, for the “config” directive to work, please insert the path you want to output into the permission_variable table. And, please be sure to set the is_allowed column in this table to 1. Then, press the “Flush Cache Storage” button.
The “customvar” Directive
Go to “System” –> “Custom Variables” in the Magento admin and create a custom variable. This “customvar” directive can retrieve the value of any custom variable you have created.
The image below shows the parameter called “code”. The parameter is the part within the squiggly brackets that comes after the directive (the word “customvar” is the directive). The image below shows that the parameter called code. This parameter is set equal to “test_custom_variable”
Please observe how, in the picture below, $params[‘code’] is equal to the value of the parameter, which is “test_custom_variable”. When the code below calls loadByCode(), this retrieves a value from the core_variable table.
The “media” Directive
The media directive looks for and retrieves a url. The path must correspond to a location within the media directory. For example, the directive below……..
Refers to this location in the media folder……….
The picture of the mediaDirective function below contains $params[‘url’]. $params[‘url’] is equal to the value of the parameter called “url”.
The parameters are those things that come after the name of the directive (which is media). Therefore, the image below shows that “url” is the name of the parameter.
The “skin” Directive
The skin directive looks for and retrieves a url. The path must correspond to a location within the skin directory. For example, the parameter called url in the picture below contains the value “images/centinel/sc_learn_62x34.png”.
This refers to this location in the skin folder pictured below……….
And, here is the function that is used to output the skin directive. The reason why the parameter we are using above is called “url” is because the code below contains $params[‘url’]
The “block” Directive
In the Magento CMS editor, I typed in the following directives………..
These directives in the picture above produce the colored blocks shown below…………
Please note, if type is anything different than “core/template”. Then, please add the type to the “permission_block” table and then press the “Flush Cache” storage button. This step must be performed otherwise the “block” directive will be unable to output the block.
The Layout Directive
The layout directive is used to output multiple blocks. Here is a picture of a handle called “custom_handle_for_blocks” in one of my layout.xml files.
Here is the directive that I am calling:
Here is the result:
The layout directive is used in the email that is sent to the customer after an order is placed. This directive is used to load blocks that list all of the items the customer has purchased.
What directives can you use in emails?
You can use all of these directives mentioned in this article in emails too!
Where can Directives be Used?
In the above examples, these directives are being entered into the CMS editor for the home page. But, directives can be used in many other places as well. They can be used on the product detail page, emails, and in newsletters.
Adding Your Own Directives
You can create your own directives:
- To add a directive that can be used on a CMS page overwrite this node: config/global/cms/page/template_filter
- To add a directive that can be used on a CMS block overwrite this node:
- config/global/cms/block/template_filter
- To add a directive that can be used on the product detail page overwrite this node:
- config/global/catalog/content/tempate_filter
- To add a directive that can be used on newsletters overwrite this node:
- config/global/newsletter/tempate_filter
