Morning Caffeine

Note: I started to write this article a year and a half ago. I finally decided to finish it and create series of posts which will cover some Smarty tips and tricks and writing plugins and modifiers.

THE PROBLEM: PHP and HTML-embedded PHP

As PHP is HTML-embedded scripting language you can easily nest php code inside html and get dynamically generated page. Great, isn’t it? Yes, as long as you know what you are doing. The trouble comes when programmers and designers start to work together on the same project. In that case programmers should try to ‘hide’ their code as much as possible from designer’s eyes, not only because designers doesn’t like to see bunch of weird signs between their HTML, but because they can easily remove a single semicolon and cause parse error in PHP. This result in arguments and blaming who erased what (for solving this you should also consider using code versioning: CVS or Subversion). Let’s see few examples.
[code]
$var = "Hello World";
?>




echo"

“;
?>


[/code]
Looks pretty neat, right? You are asking yourself, why is this bad. It isn’t if we stay on this stage of simplicity.

What if we need to display data we fetched from database within an html table?
[php]
//db configuration inclusion
include "config.php";

if(!($db = @mysql_connect(BASE_SERVER, BASE_USER, BASE_PASS))) //connect to base host
die("Cannot connect to the base server.");
if(!@mysql_select_db(BASE_NAME, $db)) //select base
die("Database doesn't exist!");

$sql = "SELECT * FROM users";

if(($result = @mysql_query($sql, $db)) == 0)
{
echo "\n

---

Database error: “.mysql_error().”

\n”;
die(”Query was ($sql) in file $_SERVER['PHP_SELF']“);
}

$user = array();

?>

while($tmp = mysql_fetch_assoc($result))
{
?>

}
?>
[/php]
Looks ok, right? Yes, because we are trying not to echo html tags within php, but to leave it accessible to designer to beautify it. Can you imagine this code after designer’s hands? I can’t anymore.

SOLUTION 1: CREATE YOUR OWN TEMPLATE SYSTEM

Now try to imagine more complex php code mixed up with html. I don’t even want to. Lets try to make programmers’ and designers’ life easier trying to separate php from html as much as possible. In other words, let’s try to use some kind of template system.

What will happen if we take code from example 2, modify it a little bit and separate it into 2 files. Let’s call first one example-2.php which will look like:
[php]
//db configuration inclusion
include "config.php";

if(!($db = @mysql_connect(BASE_SERVER, BASE_USER, BASE_PASS))) //connect to base host
die("Cannot connect to the base server.");
if(!@mysql_select_db(BASE_NAME, $db)) //select base
die("Database doesn't exist!");

$sql = "SELECT * FROM users";

if(($result = @mysql_query($sql, $db)) == 0)
{
echo "\n

---

Database error: “.mysql_error().”

\n”;
die(”Query was ($sql) in file $_SERVER['PHP_SELF']“);
}

$user = array();

while($tmp = mysql_fetch_assoc($result))
{
$user[] = $tmp;
}

include “templates/example-2.tpl.php”;
?>
[/php]
And the second one example-2.tpl.php and put in a subdirectory templates:
[php]

Name	Lastname	Email

for($i=0; $i {
?>

}?>

Name	Lastname	Email

[/php]
This definitely looks much better. The way it is now, designers doesn’t even need to look at example.php and don’t care what’s in it. As long as he doesn’t touch what is between open and close php tag, everybody is happy.
One more advantage of templates is that we can include template within a template. This way we don’t need to repeat the same code over and over again on different pages. For example, we can separate header and footer of the page into new files and just include them into our example-2.tpl.php.

SOLUTION 2: SMARTY TEMPLATE ENGINE

I won’t go into discussion why some developers like and why some dislike Smarty template engine. First time when I got in touch with it, which was back in 2002., I didn’t want to accept it, it looked to complex and not necessary. It took me a month to realize it that I won’t be able to live without it :).
Smarty offers that you separate your code as much as possible from presentation with a easy-to-learn syntax for both programmers and designers.

In the next example I will show you how to convert example-2 to work with Smarty.
First of all, download latest stable version of Smarty. Once you downloaded it, extract it into temporary dir.

Next thing to do is to setup all directories and files Smarty needs. It requires templates, templates_c, cache and configs directories. Templates dir should be used to place templates you create, templates_c is directory is for complied templates, cache for cached templates and configs for config files. However, you can name them however you want, but make sure you tell Smarty that. I created one more directory named smarty, where you should copy libs directory which comes along with archive you just downloaded.

At this point, you should have structure of your future web app like this:

[cache]
[configs]
[smarty]

[libs]

[templates]
[templates_c]

Make sure to make templates_c and cache directory writable by your web server
I have created one more directory entitled includes where I’m going to put config file which will contain some basic configuration such as database info as well as some code which will be used for initializing Smarty.

Here is the code within config.php file:
[php]

//db configuration
define ("BASE_SERVER","localhost");
define ("BASE_USER","root");
define ("BASE_PASS","");
define ("BASE_NAME","test");

/*******************
SMARTY
*******************/

require_once("smarty/libs/Smarty.class.php");
$smarty = new Smarty;

?>
[/php]
If you decide to rename directories such as templates and templates_c, make sure to add those lines, too, like this:

[php]
$smarty->template_dir = “path_to_your_template_dir”;
$smarty->compile_dir = “path_to_your_compile_dir”;
[/php]
Now, lets modify our latest example file to work it with Smarty.
example.php:
[php]
//db configuration inclusion
include "includes/config.php";

if(!($db = @mysql_connect(BASE_SERVER, BASE_USER, BASE_PASS))) //connect to base host
die("Cannot connect to the base server.");
if(!@mysql_select_db(BASE_NAME, $db)) //select base
die("Database doesn't exist!");

$sql = "SELECT * FROM users";

if(($result = @mysql_query($sql, $db)) == 0)
{
echo "\n

---

Database error: “.mysql_error().”

\n”;
die(”Query was ($sql) in file $_SERVER['PHP_SELF']“);
}

$user = array();

while($tmp = mysql_fetch_assoc($result))
{
$user[] = $tmp;
}

$smarty->assign(”title”, “Example with Smarty”);
$smarty->assign(”user”, $user);
$smarty->display(”example.tpl.htm”);
?>
[/php]
As you can see, only difference are last 3 lines of code. First one is assigning some string to variable title, second one is assigning content of array $user and the last one tells smarty to display example.tpl.htm file.

At this point example.tpl.htm looks like this and it is placed within templates directory:
[html]
{include file=”header.tpl.htm”}

{section name=c loop=$user}

{/section}

No	Name	Lastname	Email
{$smarty.section.c.iteration}	{$user[c].Name}	{$user[c].Lastname}	{$user[c].Email}

{include file=”footer.tpl.htm”}
[/html]
As you may notice, on first line, I am including file header.tpl.htm and on the last one footer.tpl.htm. {include} tags are often used for including other templates files in the current template. All variables which are available in our current template are available for included templates as well. This example demonstrates it with $title var.

header.tpl.htm at this point looks like this:
[html]

[/html]
Footer.tpl.htm
[html]


[/html]

In the example.tpl.htm our initial for loop turned into
[php]
{section name=c loop=$user}

{$smarty.section.c.iteration} {$user[c].Name} {$user[c].Lastname} {$user[c].Email}

{/section}
[/php]
{section} is for a looping over arrays of data and each of section tags must be followed by closing tag {/section}. {section} tag requires only two attributes: name and loop. Name attribute is a name of the section and loop is a value to determine the number of loop iterations. However, {section} has other optional attributes such as start, step, max, show. I will those to you to investigate their purpose.
{section} also has its own variables which handle section properties. One of them I used to show the numer of iteration and it is echoed with {$smarty.section.c.iteration}.
Also, you are able to nest sections within sections, however, make sure that you name those differently.

This is it, Smarty in some basic action. This code only shows how to install and use some basic options. There is so much to smarty, and I will try to show you how to use modifiers, write your own and to take advantage of everything smarty offers.

Here you can download all code I used in my examples.

So, enjoy it. :)

• Posted in Programming, Smarty, Web development