Most of the Xataface look and feel is the result of Smarty templates and CSS style sheets. These can be overridden and customized very easily.
Xataface uses the Smarty template engine for its templates (which accounts for most of the user interface). All of its template files are located in the Dataface/templates directory. The compiled templates are located in the Dataface/templates_c directory (both in the Xataface installation directory).
Before going and trying to modify the templates directly, be aware that there is a better way to customize the templates.
Overriding the default templates with your own templates
Follow these steps to override the default templates with your own templates:
- Add directories named 'templates' and 'templates_c' to your
application directory. The 'templates' directory is where you can place
your custom templates. The 'templates_c' directory is where
Smarty will place the compiled templates.
- Make the 'templates_c' directory writable by the web server (e.g., chmod 777 templates_c).
- Copy the template that you wish to override from the Dataface/templates folder into your custom templates directory.
- Make changes to the template in your custom templates
folder. These changes will automatically override the default
template. If you make a mistake and want to go back to square
one, you can just delete your custom template and your application will
again use the default template.
Example 1: Overriding the Dataface_TableView.html template
There are many templates in the Dataface/templates directory. So
many that you may not know where to start. One good place to
start is at the 'Dataface_TableView.html' template. This is the
global template that houses your application. All other templates
are included from this one. Let's override this template.
- Navigate to the Dataface/templates directory and take a look at what's there:
Dataface_Quickform_group.html
Dataface_Application_Menu.html Dataface_Quickform_groupelement.html
Dataface_DeleteForm.html Dataface_RecordGrid.html
Dataface_Fineprint.html Dataface_TableView.html
Dataface_Logo.html Dataface_TableView_Error.html
Dataface_NavMenu.html Dataface_TableView_menus.html
Dataface_QuickForm_element.html Dataface_TableView_tabs.html
Here is a brief description of what these templates are:
- Dataface_Application_Menu.html : A blank template that can be overridden to add a menu to the left column of the application.
- Dataface_DeleteForm.html : Template for the DeleteRecordForm (when records are being deleted)
- Dataface_Findprint.html : The copyright information that appears at the bottom of the screen in your Xataface app.
- Dataface_Logo.html : The logo in the top left of the application.
- Dataface_NavMenu.html : The navigation menu with the list of tables on the left.
- Dataface_QuickForm_element.html : An element of a form to edit records.
- Dataface_QuickForm_group.html : When multiple elements of a form are grouped together they are wrapped in this template.
- Dataface_QuickForm_groupelement.html : Template for grouped elements in a form.
- Dataface_RecordGrid.html : A sortable table (grid) for displaying records in grid format.
- Dataface_TableView.html : The main template that houses the entire application.
- Dataface_TableView_Error.html : template for displaying error messages.
- Dataface_TableView_menus.html : The pull-down menu for adding new records, deleting records, etc..
- Dataface_TableView_tabs.html : The tabs that appear at the top of the screen (e.g., list, details, find, etc...).
- Since we are going to be customizing the main template
(Dataface_TableView.html), we will copy it to our custom templates
directory (in our application folder).
- Make whatever changes you want. Here is the first bit of the template, to get an idea of what it looks like:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>{$title}</title>
<link rel="stylesheet" type="text/css" href="{$ENV.DATAFACE_URL}/plone.css"/>
<!-- Common Plone ECMAScripts -->
<!-- Pull-down ECMAScript menu, only active if logged in -->
<script type="text/javascript"
src="{$ENV.DATAFACE_URL}/plone_menu.js">
</script>
<!-- Define dynamic server-side variables for javascripts in this one -->
<script type="text/javascript"
src="{$ENV.DATAFACE_URL}/plone_javascript_variables.js.php">
</script>
<script type="text/javascript"
src="{$ENV.DATAFACE_URL}/plone_javascripts.js">
</script>
</head>
<body>
<table width="100%" border="0" cellpadding="5">
<tr>
<td width="150" valign="top">
<div class="visualPadding"/>
<div style="text-align:center; margin-bottom: 3em;">
{$logo}
</div
You may have noticed some variables that seem to magically be
appearing in this template (e.g. $ENV.DATAFACE_URL). Xataface
actually uses a class called Dataface_SkinTool which extends Smarty
with a few useful features like custom functions and tags to access
data more efficiently. For now we will just mention the $ENV
array that it makes available to you in your template. The $ENV
array contains environment information about your application. In
particular, it contains the following information:
- $ENV['REQUEST'] : A reference to the PHP $_REQUEST array which
contains all of the GET and POST variables passed to the application.
- $ENV['SESSION'] : A reference to the PHP $_SESSION array which contains any session data that your application may have.
- $ENV['DATAFACE_PATH'] : The path to the Xataface installation directory.
- $ENV['DATAFACE_URL'] : The URL to the Xataface installation directory.
- $ENV['DATAFACE_SITE_PATH'] : The path to your application directory.
- $ENV['DATAFACE_SITE_URL'] : The URL to your application directory. (e.g. http://yourdomain.com/path/to/app)
- $ENV['SCRIPT_NAME'] : The URL to your application including the script. (e.g., http://yourdomain.com/path/to/app/index.php)
- $ENV['APPLICATION'] : A reference to the application
configuration array. (anything you stored in the confi.ini file
for your application).
- $ENV['APPLICATION_OBJECT'] : A reference to the Dataface_Application object that is the core of your application.
- $ENV['SERVER'] : A reference to the PHP $_SERVER array that contains all information about the current PHP environment.
