In this article, we will be looking at how to build modifiers and functions in Smarty, a very popular templating engine in PHP. If you don’t know how to setup Smarty up in your project, you can refer to my earlier post on Smarty Templating Overview which is accompanied by a screencast.

A quick look into the Smarty plugins directory should give you an idea of what’s under the hood, the obvious thing you would notice is the file naming convention adopted:
type.function_name.php
where type could be modifier, function, etc.
So, you will typically end up with file names of this structure:

• modifier.[modifier name goes here].php
• function.[function name goes here].php
• etc

MODIFIERS

To be a little curious, lets open modifier.lower.php

<?php
// Comments removed for brevity
function smarty_modifier_lower($string)
{
    return strtolower($string);
}
?>

The above file only shows you that a Smarty plugin is just a normal PHP function, as you may be aware functions are first class citizens in PHP, which accepts arguments and returns a value that would be placed at the location it was called in the template file it self. So, {'Hmm, Interesting Discovery' | lower} in a template file would result in hmm, interesting discovery being substituted in the place of {'Hmm, Interesting Discovery' | lower} in the generated file from that template.
General usage:
{ argument_to_pass_to_the_modifier | modifier_name_goes_here}

The modifier always appears at the right, and there is a pipe | separating it and the argument it will work on.

Ok, so now what? Do you have a website with funny, and uninteresting URLs like
http://mysite.com/article.php?id=2,
where 2 may refer to an article with the title “All You Need To Know To Build Smarty Plugins”.
Let’s try and create a Search Engine Optimization or pretty URL for that article which would result in us having a new friendly URL like

http://mysite.com/article/all-you-need-to-know-to-build-smarty-plugins-2*

* To show the article, you will need to use apache mod_rewrite, but that is not the topic for discussion now, we just want to transform or slugify All You Need To Know To Build Smarty Plugins to all-you-need-to-know-to-build-smarty-plugins. And as a personal preference, i always append the unique id at the end of the generated URL so I do not run into problems when the title of the article is changed.

STEPS

Go into the plugins directory and create a file with the name modifier.seourl.php
Open the file and place the content below into it.

<?php
/**
 * Smarty seourl modifier plugin
 *
 * Type:     modifier<br>
 * Name:     seourl<br>
 * Purpose:  creates a Search Engine Optimized string
 *
 * @author   Ransford Okpoti <ranskills at yahoo dot co dot uk>
 * @param string
 * @return string
 */
function smarty_modifier_seourl($string) {
    $notAcceptableCharactersRegex = '#[^-a-zA-Z0-9_ ]#';
    $string = trim(preg_replace($notAcceptableCharactersRegex, '', strtolower($string)));
    return preg_replace('#[-_ ]+#', '-', $string);
}
 
?>

Once the file is saved, you can go to your template and use it like any normal modifier. E.g.
{$articleTitle | seourl}, {'Just what to see it working' | seourl}.
That’s it for modifiers, so just feel at home and create one if you see the need to.

FUNCTIONS

Smarty functions are similar in nature to their modifiers counterpart,but there is substantial difference in the way they are used within templates.

Usage:
{function_name optional_arguments}
where optional_arguments is in the form key1=value [, key2=value2]*

Lets create a very useful function which would enable us to dynamically include javascript files into our template.
This is extremely helpful if you want to stick to the generally accepted standard of adding javascript files to the tail end of your application or site to improve the performance of the site in terms of how long it takes the site to be loaded.

Within the plugins directory, create a file named function.javascript.php with the content below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

<?php 
/**
 * Smarty plugin
 * @package Smarty
 * @subpackage plugins
 */
 
/**
 * Smarty {javascript} function plugin
 *
 * Type:     function<br>
 * Name:     javascript<br>
 * Purpose:  outputs javascript tags for the provided srcs
 * @author Ransford Okpoti <ranskills at yahoo dot co dot uk>
 * @version 1.0
 * @example {javascript srcs='/script location'}
 *          {javascript srcs=$scripts}
 * @param array parameters
 * @return string
 */
function smarty_function_javascript($params) {
	$retval = '';
 
	if(isset($params['srcs'])){
		$scriptTemplate = '<script type="text/javascript" src="{0}"></script>';	
 
		$srcs = $params['srcs'];
	    if(is_array($srcs)){
	        foreach($srcs as $src){
	            $retval .= str_replace('{0}', $src, $scriptTemplate);
	        }
	    }
	    else{
	        $retval = str_replace('{0}', $params['srcs'], $scriptTemplate);
	    }			
	}
 
	return $retval;;
}
 
?>

Usage:
You could have this in your php file that is responsible for rendering the template.

...
// You could have some logic here to determine if a javascript file is required on a certain page
$scripts = array(
       '/public/js/contentslider.js',
       '/public/js/flash.js'
);
 
 
$this->smarty->assign('srcs', $scripts);
$this->smarty->display('template.xhtml');

The template showing just the line where our newly created Smarty function is used.

{javascript srcs=$srcs}

would result in this:

<script type="text/javascript" src="/public/js/contentslider.js"></script>
<script type="text/javascript" src="/public/js/flash.js"></script>

This is just one approach of building Smarty plugins, the other approach is to use your existing classes or functions and register them using the function register_type*(…) on a Smarty instance/object.

*
Type could be any of the following:

1. modifier
2. function
3. block
4. outputfilter
5. etc

Go! Go!! Go!!! Let Smarty work for you by developing your own plugins to provide extra functionalities.

[SCREEN CAST IS COMING SOON...]