Current Record: xataface_templates #23

Xataface Templates Table of Contents Xataface Templates Cascading Templates Useful Smarty Tags introduced by Xataface Xataface Templat...

Current Record: xataface_templates #23

Xataface Templates Table of Contents Xataface Templates Cascading Templates Useful Smarty Tags introduced by Xataface Xataface Templat...

xataface_templates

[Permalink]

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.

Name Description Version
use_macro Include another template with the option to override certain sections. 0.6
define_slot Marks a section that can be overridden by other templates that include this one via the use_macro tag. 0.6
fill_slot Overrides content in a template that has been included via the use_macro tag. 0.6
block Marks an insertion point where content can be inserted by delegate classes and modules. 0.6
load_record Loads a Dataface_Record object from the database to be used in the template. 0.6
group Groups an array of records together based on a field value. 0.6
img Displays a thumbnail of an image. 0.6
actions Loads an associative array of actions defined in the actions.ini file, based on certain criteria. 0.6
actions_menu Displays a menu of actions based on certain criteria. 0.6
record_actions A specialization of the actions_menu tag. This displays a menu of actions only in the record_actions category. 0.6
record_tabs A specialization of the actions_menu tag. This displays a menu of actions only in the record_tabs category. 0.6
result_controller Displays the paging controls for the current table's records. Use this for any listing of records. 0.6
result_list Displays the result list (from the list tab) for the current request. 0.6
related_list Displays the related records list for the current request. 0.6
bread_crumbs Displays the bread crumbs for the current request. 0.6
search_form Displays the find form for the current table. 0.6
language_selector Displays a menu to select the user's preferred language. 0.6
next_link Displays a link to the next XXX records. 0.6
prev_link Displays a link to the previous XXX records. 0.6
jump_menu Displays the select list of the records found in this found-set so that the user can jump directly to any record. 0.6
limit_field Displays a text field for the user to select the number of records to display per page. 0.6
result_index Displays the index of pages (1 to XXX) for this query. 0.6
summary_list Displays a list of records in the current found set using a summary format rather than the regular table format. 0.6
sort_controller Displays a control to sort the results on any column. 0.6
glance_list Displays a simple, brief list of records matching certain criteria. 0.6
record_view Loads structured data for a record as required for the view tab. 0.6
feed Generates a link to an RSS feed based on certain criteria. 0.6
translate Display a section of text in the user's selected language. (i18n). 0.6
if_allowed The contents of this block are shown only if the user has certain permissions. 0.6
editable Make a section of the page editable using AJAX. 0.6
abs Convert a URL into an absolute URL. 0.6

Useful Template Variables

Xataface makes certain variables available to every template:

Name Description Version
$ENV.REQUEST Reference to the $_REQUEST array (HTTP Request parameters, both GET and POST) 0.6
$ENV.SESSION Reference to the $_SESSION array (the session variables) 0.6
$ENV.DATAFACE_PATH The file system path to the Xataface directory (i.e. the directory containing all of the Xataface files such as dataface-public-api.php). 0.6
$ENV.DATAFACE_URL The URL to the Xataface directory. 0.6
$ENV.DATAFACE_SITE_PATH The file system path to your application directory. (i.e. the directory containing your conf.ini and index.php files). 0.6
$ENV.DATAFACE_SITE_URL The URL to your application directory. 0.6
$ENV.DATAFACE_SITE_HREF The URL to your application's script. This differs from the $ENV.DATAFACE_SITE_URL variable in that this also includes the script name. 0.6
$ENV.SCRIPT_NAME Same as $ENV.DATAFACE_SITE_HREF 0.6
$ENV.APPLICATION A reference to the application's conf array (i.e. the parsed contents of the conf.ini file). 0.6
$ENV.APPLICATION_OBJECT A reference to the Dataface_Application object for the application. 0.6
$ENV.SERVER A reference to the $_SERVER array. 0.6
$ENV.QUERY A reference to the current query (i.e. Dataface_Application::getInstance()->getQuery()) 0.6
$ENV.action The name of the current action as specified by the -action REQUEST parameter. 0.6
$ENV.table The name of the current table as specified by the -table REQUEST parameter. 0.6
$ENV.table_object A reference to the current table. 0.6
$ENV.relationship The name of the current relationship as specified by the -relationship REQUEST parameter. 0.6
$ENV.limit The value of the -limit REQUEST parameter. This is the number of records to show per page. 0.6
$ENV.start The value of the -start REQUEST parmeter. This is the starting point in the result set which is currently being displayed. 0.6
$ENV.resultSet A reference to the Dataface_QueryTool object for this result set. 0.6
$ENV.record A reference to the Dataface_Record object that is matched by the current query. 0.6
$ENV.mode The name of the current mode. e.g. find, list, browse 0.6
$ENV.language The 2-digit ISO language code that is currently selected as the user's preferred language. 0.6
$ENV.prefs A reference to the preferences array ($conf['_prefs']) 0.6
$ENV.search The value of the current full-text search (i.e. the search that was entered into the upper right search field. 0.6

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:

blog comments powered by Disqus
Powered by Xataface
(c) 2005-2024 All rights reserved