Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...

When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Creating Custom Block Tags in Smarty

The Block Plug-in Type

There are several different kinds of plug-ins that can be implemented in Smarty, allowing developers to easily extend the capabilities of their templates (or to manipulate how the engine works). We will be looking at the block plug-in type, which allows you to process an entire area of generated content. For example, blocks allow you to use template code similar to that in Listing 1.

Listing 1 Sample usage of a custom block (listing-1.tpl)
    Here is the content inside the block

If we were to use this template code, we would then need to implement the my_custom_block plug-in. The plug-in code would be executed twice: once when the block is opened and again when it is closed. We can determine within the code which of those two events are being handled. When we handle the closing of the block, we have access to the content inside the block (which may contain output from other Smarty tags).

You may already be familiar with one of the built-in blocks Smarty has: {capture}. This plug-in allows you to save the contents of the block to a template variable for later use. I commonly use this in URL generation. Listing 2 shows an example of generating a URL and saving it to the $url variable so it can used multiple times in the template.

Listing 2 Recycling values in a template by using {capture} (listing-2.tpl)
{capture assign=url}/path/to/page?var1={$var1}&var2={$var2}{/capture}
<a href="{$url|escape}">{$url|escape}</a>
Note: Remember to use the escape modifier when outputting template variables in HTML. This is to prevent script injection, as well as to generate valid XHTML (in this case, the & would be output as & rather than &amp; if we didn't use escape).

One of the most useful applications of blocks is to generate a series of HTML tags in a single line of code. For example, if you wanted to publish articles on a web site, you might want to display a summary of each article (known as a teaser) in several locations on the site perhaps in different templates.

Listing 3 shows the HTML code you may use to display an article teaser.

Listing 3 Sample HTML code to display an article teaser (listing-3.tpl)
<div class="teaser">
    <div class="byline">By {$author|escape}</div>

While there is nothing wrong with this, if you end up repeating this code in several templates in your site, it becomes difficult to update if you ever want to change the mark-up. A simpler and cleaner solution is to create a custom block (let's call it teaser) and let the block deal with the specific HTML tags.

Doing so would allow you use the following code in your template instead:

Listing 4 Using your custom {teaser} block to generate HTML (listing-4.tpl)
{teaser title=$title author=$author}

When you implement the teaser block, you can either hard-code the HTML tags in the plug-in's PHP code (not recommended) or you can write the HTML tags to another template and have the block plug-in use that template (this is what the example in this article will use).

Note: Technically speaking, you could implement the same solution using normal Smarty includes (such as {include file='teaser.tpl' title=$title author=$author teaser=$teaser}), however using blocks allows you to perform any other custom logic that is required and also lends itself to much cleaner code, even if it is slightly more work. Additionally, when using blocks, you don't care about the implementation details at all (that is, in your template you don't need to care where the template is stored).

In This Article