This section digs directly into the PHP code and components behind Xataface's templating functions.  It is useful to know a little bit about the architecture but not mandatory.  You may skip to the next section if you are looking for concrete examples on how to customize your Xataface application.

All of the heavy lifting for templates is handled by the Dataface_SkinTool class which extends Smarty, as portrayed in the following UML diagram:

Using the SkinTool

Let's display the 'Foo.html' template using the SkinTool in PHP:

import('Dataface/SkinTool.php');
$skinTool =& Dataface_SkinTool::getInstance();  // The =& is important to obtain reference to skin tool instance.
$skinTool->display(array(), 'Foo.html'); // Actually displays the Foo.html template

Xataface provides a public API of functions that are short-cuts to the various classes and objects in the framework.  One of these functions is: df_display() which will also display a template using the SkinTool. Using df_display() we can compress the example above into a single line of code:

df_display(array(), 'Foo.html');

Where do you put your templates?

The SkinTool will first look in the 'templates' directory of your application to see if it can find a template by the specified name.  If it does not find one, it will look in the Dataface/templates directory of your Xataface installation.

As you will see, this arrangement makes it easy to override existing Xataface templates.  All you have to do is place a template of the same name in your application's templates directory, and the SkinTool will use that template instead of the default one.

Registering Skins

What if you want to add another templates directory (in addition to your application's templates directory) so that you can, in effect, have different skins for your application.  The Dataface_SkinTool implements a method called register_skin() that will register another directory and add it to the beginning of the search path so that the SkinTool will check that directory for a template before checking your application's template directory.

Next..

Now that you have seen how Xataface is working under the covers, it is time to take a look at its templates, how they are related, and what they do.