N2F Yverdon Basics: Part 3 - The Template Engine
Part 2 of the series introduces us to the layout of N2F Yverdon module. In this part of the series, I’ll be showing you the basics of the dynamic template extension built for our template system. Our template system, while not required for use of Yverdon, is a fast and simple solution to the problem of separating the presentation and business layers of an application. In plain English, we just mean to say we’re offering a way to separate the code you write from the way it’s displayed.
Template Extensions
N2F Yverdon utilizes a system of extensions for expanding the capabilities of the framework. When building the template engine, we realized that there was a lot of value in being able to change how the template system worked in certain situations. As a result we decided to leverage the extension system for our template engine. First v0.1, we have created the first of these template extensions, called the Dynamic extension. That is the flavor of template we will be using in this entry.
Directory Structure
One of the first things to know about how dynamic templates work is the directory structure you must use for storing your templates. We opted to organize templates by skins inside of each module. The name for the skin Yverdon comes configured to use is simply, ‘default’. If you are inside of an ‘aboutme’ module, your template directories will look as such:
/home/someuser/public_html/modules/aboutme/tpl /home/someuser/public_html/modules/aboutme/tpl/default
You can create however many skins you like, but we’re not going to get into using different skins in this post.
The Template File
The system expects templates to have a .tpl extension on them, but beyond that naming the extension is up to your wildest dreams and desires. As a habit, the N2F Yverdon staff almost always uses index.tpl as the base template for a module. We’re going to create three files for this post:
/home/someuser/public_html/modules/aboutme/tpl/default/index.tpl /home/someuser/public_html/modules/aboutme/tpl/default/header.tpl /home/someuser/public_html/modules/aboutme/tpl/default/footer.tpl
We’ll put the following code into the header.tpl file:
<html> <head> <title>My Page</title> </head> <body>
The following code into the index.tpl file:
This is the body of my page.
And the following code into the footer.tpl file:
</body> </html>
Once all the files are saved, we’ll move onto creating one of the nice features of the dynamic template extension.
Aliases Are Short For Something
With a dynamic template, we found the need to include blocks of HTML here and there across multiple pages and modules. To solve this common problem, we created the alias system. There are lots of different terms and ways of explaining this part of the extension, but the basic idea remains the same. All this does is allow you to break pieces of your markup (HTML/XHTML/CSS) into separate .tpl files and use it across the rest of your Yverdon installation. To define aliases, you will create a page.php file similar to this:
<?php
// Pull the global n2f object
global $n2f;
// Define our header and footer aliases
n2f_template_dynamic::addAlias('header', 'header', 'aboutme', './modules', 'default');
n2f_template_dynamic::addAlias('footer', 'footer', 'aboutme', './modules', 'default');
?>
All aliases are currently defined using the n2f_template_dynamic::addAlias() method. You can view the method signature here, but the quick and dirty is that the first argument is the text to match in templates for this alias, the second argument is the name of the .tpl file to pull from, the third is the module the .tpl file comes from, the fourth is the base path (you won’t need to change that normally) and the final argument is the skin where the alias resides.
To use a defined alias, you must put the text in between the <% and %> tags. We’ll put these two to use inside of our index.tpl file, making it now look like this:
<%header%> This is the body of my page. <%footer%>
Bringing It All Together
Finally, we get to use our template. Because of the aliases we made, we only need to display one template. Anytime you wish to display a template, you must create a new n2f_template object. I’ll add the code to our page.php file first, and explain after:
<?php
// Pull the global n2f object
global $n2f;
// Define our header and footer aliases
n2f_template_dynamic::addAlias('header', 'header', 'aboutme', './modules', 'default');
n2f_template_dynamic::addAlias('footer', 'footer', 'aboutme', './modules', 'default');
// Create the template object
$tpl = new n2f_template($n2f, 'dynamic');
// Set the module and file to use
$tpl->setModule('aboutme');
$tpl->setFile('index');
// Render and display the template
$tpl->render();
echo($tpl->fetch());
?>
An n2f_template object can be initialized several different ways, but the way used here offers the global $n2f object as the first argument (this helps with default configuration) and the string ‘dynamic’ as the second argument to tell the n2f_template object that it is to use the dynamic template extension. The n2f_template::setModule() and n2f_template::setFile() methods are fairly self-explanatory. The n2f_template::render() method prepares the template for being displayed. This is where the work is done to pull the <%header%> and <%footer%> aliases into the template. The n2f_template::fetch() method does little more than return the string produced by the template, which we immediately echo to the browser.
When you load up your browser to the aboutme module (http://www.mysite.com/?nmod=aboutme), the template system will produce the following markup from your work:
<html> <head> <title>My Page</title> </head> <body> This is the body of my page. </body> </html>
Summary
That’s it! There are many more things you can do with the template engine, and we’re still working on building the proper documentation for you to get into the nitty-gritty of the system. On top of that, we have at least one other template extension planned for release with Yverdon v0.2. If you have any problems, feel free to drop by IRC or on our forums so we can give you a hand. Part 3 of the series will be about using our MySQLi database extension, so be sure to stay tuned!
- Andrew