Markup Tags - CMS Directives

Last modified by benz001 on Thu, April 14, 2011 23:26
Source|Old Revisions  

This is an old revision of the document!

This article details which template tags can be used on CMS pages, in static blocks, and in email templates.

What is a template tag?

A template tag is a bit of text surrounded by double curly braces which has a special meaning to Magento, e.g., {{store url=""}}.

You might use a template tag to

  • link to a page within your store without typing out your domain name
  • embed a block within a page without editing layout or template files

Template tags have a variety of uses.

Where can I use template tags?

You can use template tags on CMS pages, in static blocks, and in email templates.

How do I use template tags?

You use template tags by entering them in one of the places Magento recognizes them (see above).

To illustrate, say you wanted to display your company’s “About Us” image on your store’s home page. (You can manage the content of the home page by navigating to CMS > Manage Pages and then clicking on “Home page” in the back end.) You might do this by typing

  1. <img src="" />

but that’s a lot to type. Instead, using a template tag, you could simply say

  1. <img src="{{skin url='images/media/about_us_img.jpg'}}" />

Which tags can I use?

Note: In the following examples I’m assuming that a working Magento install is set up at

You can use the following tags:

{{block id='block_id'}}

This tag inserts the static block which has the identifier “block_id“. (Static blocks can be managed by navigating to CMS > Static Blocks in the back end.)


  1. {{block id='footer_links'}}

This code will insert the “Footer Links” static block.

{{block type='module/package_classname' template='path/to/template.phtml'}}

This inserts a block of the type module/package_classname using the template path/to/template.phtml. The string module/package_classname translates into a class name which is defined in the Block directory of module. (Thus core/text_list, for instance, translates into Mage_Core_Block_Text_List, which is defined in app/code/core/Mage/Core/Block/Text/List.php.)

If the module’s Block directory contains no sub directories, the package_ part of the string is omitted. (Thus the string tag/popular translates into Mage_Tag_Block_Popular, which is defined in app/code/core/Mage/Tag/Block/Popular.php.)

The value of the template attribute should be the path to the template that corresponds to the block, starting from the theme directory (e.g., tag/popular.phtml).


  1. {{block type='core/template' template='cms/custom_page.phtml'}}

This code will cause cms/custom_page.phtml to be embedded into the page/email.

{{htmlescape var='' allowed_tags=''}}

Escapes all HTML tags in the value of the var attribute, except for those specified in the value of the allowed_tags attribute. (The latter expects a comma separated list of allowed HTML tags).


  1. {{htmlescape var='<a href="javascript:alert(1);">Hello</a>'}}

This will produce the output <a href=”javascript:alert(1);”>Hello</a>, i.e., an escaped string which the browser won’t interpret.

{{layout handle=''}}

Inserts HTML layout output. The handle attribute expects the name of a layout handle, e.g. default.

{{media url=''}}

Inserts the URL of the media directory, e.g., Changing the value of the url attribute to a non-empty string will cause the string to be appended to this URL.


  1. {{media url='catalog/product/l/a/large_phone.jpg'}}

This will produce the output

{{skin url=''}}

Inserts the URL of the current theme’s skin directory, e.g., Changing the value of the url attribute to a non-empty string will cause the string to be appended to this URL.


Assuming you’re using the default theme and the default interface, then

  1. {{skin url='images/media/about_us_img.jpg'}}

will be converted to

{{store url=''}}

Inserts the store’s base URL, i.e., the URL of the store’s home page. (Sample output: Changing the value of the url attribute to a non-empty string will cause the string to be appended to the store’s base URL and a slash (/) to be tacked on to the end of the resulting URL. This trailing slash makes the url attribute suitable for referencing directory-like paths, e.g. customer/account.


  1. {{store url='about-magento-demo-store'}}

This will be converted to Note the terminating slash in this URL; this is what distinguishes the url attribute from the direct_url attribute.

Furthermore the contents of the url attribute are parsed through Magento’s standard URL routing system, meaning that url values of the form module/controller will resolve to their correct URL paths based on the routes defined for each module. It will also preserve session variables/store selectors etc if these are being put into the query string.

If you just want to create a simple link that works like a standard html link you’re probably looking for the direct_url command described below.

{{store direct_url=''}}

Does the same as {{store url=''}} but without appending a slash to the resulting URL or passing it through the module routing system - it will simply add whatever you type to the store’s base URL.

This is suitable for referencing file-like paths, e.g. coffee/kona-fancy-whole-bean.html.

NOTE: The URLs generated will by default have index.php after the base URL. The above example would result in To remove the index.php it is necessary to enable URL Rewriting. See

How do template tags work?

This is roughly what happens when Magento encounters a template tag it understands:

  1. Magento uses the tag to populate an array with three elements. The first element is the whole tag (e.g., {{store url='coffee/test.html'}}). The second element is the keyword which follows immediately after the opening curly braces (e.g., store). The third element is the tag’s keyword=value pair (e.g., url='coffee/test.html').
  2. Magento passes the array to a method of the Mage_Core_Model_Email_Template_Filter class. The name of the method depends on the keyword within the tag: if the keyword is store, for instance, the storeDirective method will be called.
  3. The method returns a value. This value is used instead of the template tag on the front end.

Further information

For more on how template tags work and which parameters they take, see Ivan Weiler’s "Magento CMS syntax – part1".

Appendix: Creating a custom block type which can accept arguments

To learn how you can use a template tag such as

  1. {{block type='namespace_custom/test' my_param1='value 1' my_param2='value 2'}}

see Moshe’s tutorial on creating a block class which extends Mage_Core_Block_Abstract and overloads the _toHtml() method.