xataface_templates

Xataface Templates

Xataface uses the Smarty Template Engine to power all of its templates. Templates are stored in the one of the following locations:

• %XATAFACE_ROOT%/Dataface/templates
• %SITE_ROOT%/templates

Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application.

You may also have subdirectories within these templates directories.

Cascading Templates

Xataface uses a simple cascading technique for deciding which template to use. If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory. In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory.

The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...). Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired.

Useful Smarty Tags introduced by Xataface

In addition to the standard set of Smarty tags, Xataface templates provide some of its own.

Xataface Templates

Xataface uses the Smarty Template Engine to power all of its templates. Templates are stored in the one of the following locations:

• %XATAFACE_ROOT%/Dataface/templates
• %SITE_ROOT%/templates

Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application.

You may also have subdirectories within these templates directories.

Cascading Templates

Xataface uses a simple cascading technique for deciding which template to use. If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory. In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory.

The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...). Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired.

Useful Smarty Tags introduced by Xataface

In addition to the standard set of Smarty tags, Xataface templates provide some of its own.

Useful Template Variables

Xataface makes certain variables available to every template:

Smarty Plugins

One of the most powerful features of Smarty is its pluggable architecture. You can easily add your own custom plugins to a registered "plugins" directory to add functions, modifiers, blocks, and other features to your templates.

Prior to Xataface 2.0, you Smarty plugins could only be placed in the lib/Smarty/plugins directory of the Xataface distribution folder. This is not very conducive to Xataface updates, though. In general it is best practice to not change anything inside the xataface directory. Most other configuration and extensions can be handled by making changes to your application's directory which override corresponding functionality in Xataface.

As of Xataface 2.0, you can create a directory named plugins to your application directory, Smarty knows to look in this directory for plugins.

For versions of Xataface prior to 2.0, you can make a small modification to the SkinTool to also add support as desribed in this post.

Example Plugin

The following is an example Smarty plugin adapted from this page but modified slightly to work in Xataface. It is a simple "eightball" plugin that adds a tag {eightball} to Xataface that you can use in any of your templates. Whenever this tag is rendered it outputs one of a set of predefined strings randomly.

1. Add a plugins directory to your application directory. i.e. path/to/app/plugins
2. Add a file inside this plugins directory called function.eightball.php with the following content:

   <?php
   /*
    * Smarty plugin
    * -------------------------------------------------------------
    * File:     function.eightball.php
    * Type:     function
    * Name:     eightball
    * Purpose:  outputs a random magic answer
    * -------------------------------------------------------------
    */
   function smarty_function_eightball($params, Dataface_SkinTool $template)
   {
       $answers = array('Yes',
                        'No',
                        'No way',
                        'Outlook not so good',
                        'Ask again soon',
                        'Maybe in your reality');
   
       $result = array_rand($answers);
       return $answers[$result];
   }

3. If you compare this function to the original example in the smarty tutorial you'll notice that the 2nd parameter has been changed to type Dataface_SkinTool from Smarty_Internal_Template. If you don't make this change, you will get a fatal error when you try to use the tag. This function defines an {eightball} tag that can be added to any Smarty template in Xataface.
4. Next we'll create a template that uses this tag. If your application doesn't have a templates directory, create one now (i.e. path/to/app/templates).
5. Add a file inside your templates directory called testing.html with the following content:

   The eight ball says {eightball}

6. Now we need to display this template somewhere in our interface. In this case, we'll choose the before_record_content block. (This will render the template before the main section of the view tab). Add the following method to your Application_Delegate_Class:

   function block__before_record_content(){
       df_display(array(), 'testing.html');
   }

7. Now if you load your application in a web browser and navigate to the details view for a record, you should see something like the following:

See also:

• Changing the Look & Feel of Xataface (From the Getting Started Tutorial)
• Cusomizing the Xataface Look & Feel Tutorial