-
Notifications
You must be signed in to change notification settings - Fork 57
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
You may also have subdirectories within these templates directories.
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.
In addition to the standard set of Smarty tags, Xataface templates provide some of its own.
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
You may also have subdirectories within these templates directories.
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.
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 |
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 |
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.
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.
- Add a plugins directory to your application directory. i.e. path/to/app/plugins
- Add a file inside this plugins directory called function.eightball.php with the following content:
<?php
- 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.
- 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).
- Add a file inside your templates directory called testing.html with the following content:
The eight ball says {eightball}
- 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(){
- 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:
- Changing the Look & Feel of Xataface (From the Getting Started Tutorial)
- Cusomizing the Xataface Look & Feel Tutorial