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

Implementing a Block Plug-In

We will now look at how to create a block plug-in. Smarty looks for plug-ins in the plugins directory that resides in the same location as the Smarty.class.php file. You can write your custom blocks to this directory, or you can create your own custom plug-in directory.

I highly recommend using a separate directory for your own plug-ins, as it makes upgrading Smarty much easier in the future (you don't need to keep track of which plug-ins are your own especially if you have a large number of custom plug-ins in your site).

In the rest of this article I will assume you have created a directory called customplugins which resides in the same location as Smarty.class.php and the plugins directory.

In addition to defining the template_dir and compile_dir variables when instantiating the Smarty class, you must now also update the plugins_dir variable to include customplugins. As an example, you might use the code in Listing 5 to instantiate Smarty:

Listing 5 Instantiating Smarty and defining a custom plug-in directory (listing-5.php)
    $smarty = new Smarty();
    $smarty->template_dir  = '/path/to/templates';
    $smarty->compile_dir   = '/path/to/templates_c';
    $smarty->plugins_dir[] = 'customplugins';
Note: By default the plugins_dir variable is an array with plugins as its only element. We are simply adding the customplugins value to this array.

The next step is to create a new file in the customplugins directory to hold the plug-in PHP code. All plug-ins in Smarty use a standard file-naming scheme, in the format of Since the type of plug-in we are creating is a block plug-in, we use the filename block.blockname.php. As an example, if we were to create a plug-in called teaser the filename would be block.teaser.php.

Within this file we create a PHP function, which is named in the format smarty_type_name. So in the case of creating a block called teaser the function we create would be called smarty_block_teaser().

When implementing a block plug-in, the PHP function takes four arguments:

  1. $params This is an array of the attributes passed to the block's opening tag. This array is available both when the block is opened and when it is closed.
  2. $content This is a string of the content inside the block. This value is only available when the block function is called for the block being closed. If the block contains template code (such as loops or variable output) then $content contains the evaluated output (not the original template source).
  3. $smarty The Smarty object, allowing you to assign variables or to evaluate another template.
  4. $open This variable is used to determine whether the function is being called for the tag opening or closing. When being called for close, the value of $open is false.

To actually output content to the template, it is simply a matter of returning the output value from the plug-in.

Putting all of this together, if we wanted to create a block plug-in called teaser, we would create a file called block.teaser.php in the customplugins directory with the code as shown in Listing 6.

Listing 6 The starting point for a block plug-in called teaser (listing-6.php)
    function smarty_block_teaser($params, $content, $smarty, $open)
        if ($open) {
            // Called when {teaser} appears in template
        else {
            // Called when {/teaser} appears in template.
            // Additionally, $content contains the evaluated template
            // that lies within the {teaser} {/teaser} tags.

Next we will complete this code by creating a fully-functioning block plug-in.

In This Article