Building Template-Driven Web Applications with Dwoo (part 1)

Form and Function

When discussing the best practices of PHP application development, there’s one that appears on almost every list: separating the business logic of a Web application from its user interface. This separation lets interface designers work on a site’s appearance without disrupting the code of the application developers implementing business-level features and workflows.

Most PHP frameworks, including well-known ones like Zend Framework, Agavi, CakePHP and CodeIgniter, natively support this separation of interface and business logic. However, if your project is small enough that you don’t need a framework (or if you just don’t like them), you can still achieve the same benefits by using a standalone template engine. In this article, I’ll introduce you to one such engine, which goes by the rather unique name of Dwoo.

Ghostly Knocking

This tutorial makes a couple of assumptions. First, it assumes that you know the basics of PHP and database programming, and you have a reasonably-good understanding of using objects and object methods in PHP. Second, it assumes that you have an Apache/PHP/MySQL development environment already set up, and that you’ve managed to successfully install Dwoo. If you’re using the automated PEAR installer, you can install Dwoo simply by running the following commands at your command prompt:

Alternatively, you can manually install the Dwoo package, by downloading it from Dwoo is currently maintained by Jordi Boggiano and is released under the Modified BSD License. This article uses Dwoo v1.1.1

Assuming you’ve got Dwoo installed, let’s get started with the basics. Dwoo assumes that a single Web page is made up of one or more independent templates. Each template contains both static HTML elements and template variables, which serve as placeholders for content. Dwoo works by injecting these placeholders with “real” data at run-time, thereby creating a final page that is suitable for display.

The values for the variable placeholders are set inside a controlling PHP script; this script may also perform other business-level functions, such as calculations, database queries, or XML processing. The separation between the PHP business logic and the HTML page template means that changes to the visual appearance of the page can be accomplished entirely by an interface designer, without a PHP developer’s input or coordination.

This might sound complicated but it’s actually very simple. To see how this works, create a simple HTML page, as below, and save it as templates/knock.tpl in your working directory:

This is an HTML page template that contains two variables, $name and $punchline. Curly braces surround these variables; this tells Dwoo that they are template variables and must be replaced with actual values at run-time. Let’s see how that works:

There’s a fairly standard sequence to rendering a template using Dwoo:

1. Include the Dwoo autoloader script. This registers the Dwoo autoloader with PHP, so that Dwoo object definitions and plugin files are automatically found and loaded as needed.

2. Create an instance of the Dwoo object. This object serves as a central point for all communication with the Dwoo template engine in subsequent operations.

3. Load the page template file. This is done by creating an instance of the Dwoo_Template_File object, passing the file name and path to the Dwoo_Template_File object constructor. Dwoo will then find and load this template into memory.

4. Set values for template variables. With Dwoo, this is done simply by defining a new associative array, whose keys and values correspond to template variable names and content.

5. Render the template. This is accomplished by calling the Dwoo object’s output() method, passing it the template object and the data array. The output() method interpolates the content from the data array into the template object, generating and rendering the composite result.

Here’s what the result looks like:

An alternative here is to use the get() method instead of the output() method. This retrieves the interpolated version of the template and assigns it to a variable instead of sending it directly to the browser. This is handy if you’re working with complex template trees or simply want to perform further processing on the output before displaying it. You’ll see an example of this method further along.

Right and Wrong

Dwoo supports the use of conditional tests within templates, via its “if” plugin. Here’s a simple example of a template that uses this plugin:

Depending on the value set for the decision variable within your PHP controller script, the template will display one of two possible messages. Here’s the controller script, which randomly sets the decision variable to either 1 or 0:

Here’s what the output will look like:

Notice that this script introduces a new object, the Dwoo_Data object. If you have a large number of template variables, using Dwoo_Data to store template variable values is often easier than using regular PHP associative arrays, as it comes with numerous methods to assign, retrieve, merge and clear template variables.

You can also use the “if” plugin to set up more complex conditional tests, via its support for if-elseif-else syntax. Here’s an example:

And here’s the revised PHP script and output:

Looping The Loop

Dwoo also supports loops, allowing you to repeat a particular segment of a template via its {loop} construct. To illustrate, consider the following template, which specifies a loop for a list item element:

To activate this loop, you must specify an array of values for the loop template variable in the PHP controller script. Dwoo will then automatically iterate over the array at render-time, repeatedly printing the loop segment with different content until the entire array has been processed. Here’s the PHP script:

Here’s what the output looks like:

Notice also that this template make use of a Dwoo plugin, “escape”, which takes care of automatically escaping output before printing it. It’s a good idea to wrap all output in this method call to reduce your vulnerability to XSS attacks. By default, the “escape” plugin escapes output using HTML entity encoding but it’s quite easy to alter this to use other formats as well.

You can also use Dwoo’s {foreach} construct to iterate through indexed and associative arrays, in a similar manner to that of PHP’s foreach() loop. Consider the following revision of the previous template, which illustrates:

In this case, $items is an indexed array, which is populated from within the PHP page controller. On each iteration, the current element of the array is assigned to the local loop variable $item. Here’s the PHP script:

If you’re using an associative array, the procedure is similar, except that you need to specify local “key” and “value” variables within the {foreach} block inside the template. Here’s how:

And here’s the PHP script that activates and populates this template:

Here’s the output:

Getting Booked

The ability to use loops inside template comes in particularly handy when you need to integrate the results of a database query into your output template. To illustrate, consider the following template for a two-column table:

Here’s the corresponding PHP script, which retrieves a list of countries and languages from a MySQL database, drops them into an array, and uses that array to populate the template above:

Here’s a sample of the output:

Happy Holidays

One of the nicer things about Dwoo is that it allows you to merge templates scattered across different files. If you have a large project to manage, this makes it possible to split commonly-used pieces of the user interface into separate files and (re)use them wherever needed.

To better understand this, consider the following cutaway of a Web page:

Now, assume for a moment that the header and footer are stored as two separate templates, as shown below:

Dwoo comes with an “include” plugin that can automatically include one or more templates files in another main template. So, for example, the template for the content area could import the header and footer templates via this plugin. Here’s how:

This arrangement makes it easy to modify each template independently of the others, making it possible to alter, say, just the top bar or the content layout.

You can now use a PHP script to assign variables to all of the template variables and render the composite output:

Here’s the output:

Another approach to accomplish the same result is to create template variables representing the header and footer, and assign rendered HTML content to these variables at run-time. To do this, you’d need to adjust the template for the content area to use template variables, instead of the “include” plugin, for the header and footer, as shown below:

To render the complete page, the PHP controller script must first render the header and footer templates, capture the result, interpolate this result into the main template and then render the complete page. This two-step process is accomplished with Dwoo’s get() function, which makes it possible to capture the interpolated result of the header and footer templates in PHP variables, and then assign them back to the main template. Here’s the code:

String Theory

Dwoo includes a full-featured plugin system that allows developers to add their own functionality to the template engine. A number of plugins are included as part of the source distribution; these provide ready made functionality that can be effectively used by designers and developers.

You’ve already seen the “escape” plugin in action in a previous example. It allows you to sanitize potentially-harmful input, by replacing special characters with HTML entities. However, it can often be tedious to apply this plugin to individual template variables and so, Dwoo offers an “auto_escape” plugin, which can be used to automatically escape an entire block of content. Here’s an example of it in use:

Here’s a PHP script that demonstrates it in use:

And here’s what the output looks like:

In the same vein, Dwoo also comes with a “strip_tags” plugin, which works much like PHP’s strip_tags() function, automatically stripping out all the code from a string. Here’s an example of how it can be used in a template:

Here’s a script that attempts to interpolate HTML code into the template:

Here’s what the output looks like:

Dwoo offers a number of plugins for string wrapping, indentation and truncation. These plugins, unsurprisingly called “wordwrap”, “indent” and “truncate”, can come in very handy when dealing with large blocks of content. Here’s a template that demonstrates them in use:

Here’s a PHP script that sets the template variable to a long string of text, to demonstrate how these plugins work:

And here’s the output:

When it comes to formatting dates and times, Dwoo offers the “date_format” plugin, which makes it easy to format dates and times as per local conventions. This plugin takes two arguments: the date to be formatted, either as a human-readable date string or a UNIX timestamp; and a format string that specifies how the output should appear. In case you’re wondering, Dwoo makes use of strftime() format specifiers.

Here’s an example:

Here’s the corresponding PHP script:

And here’s what the output looks like:

You’ll find a complete list of Dwoo plugins here.

And that’s about all we have time for at the moment. But this is just the tip of the iceberg, and in the second part of this article, I’ll look at some of the more advanced features available in Dwoo, including such goodies as template inheritance, user-defined plugins and filters, and framework integration. Come back soon for that…and until then, happy coding!

Copyright Melonfire, 2010. All rights reserved.