What is a Directive?

From time to time, in Magento, you may run across code snippets with two squiggly opening and closing brackets.
1-DirectivesInCms
What are those “squiggly bracketed” snippets of code officially called? They are called directives. These are very similar to “shortcodes” in WordPress. The first word after the two opening squiggly brackets is the name of the directive. So, in the picture on the right, we have examples of the skin directive, media directive, config directive, store directive, and the customvar 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……….

2-DirectivesInCms-Result

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:

3-DirectivesInCms-Mapping(raw)

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:

4-configDirective

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.

5-configDirectiveCmsEditor

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”

6-customVarDirective-CMS

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.

7-customvarDirective-code

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……..

8-mediaDirective

Refers to this location in the media folder……….

9-mediaFolderinFileStructure

The picture of the mediaDirective function below contains $params[‘url’]. $params[‘url’] is equal to the value of the parameter called “url”.

10-mediaDirectiveCode

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.

11-mediaDirectiveShortCode

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”.

12-skinDirectiveShortcode

This refers to this location in the skin folder pictured below……….

13-skinFolderFIleStructure

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’]

14-skinDirectiveCodeExample

The “block” Directive

In the Magento CMS editor, I typed in the following directives………..

15-blockDirectiveShortCodeExample

These directives in the picture above produce the colored blocks shown below…………

16-blockDirectiveOutput

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.

17-layoutDirectiveXML

Here is the directive that I am calling:

18-layoutDirectiveShortcode

Here is the result:

19-layoutDirectiveOutput

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