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