You are here: Home > Documentation > tutorial > Getting Started with Xataface > Changing the Look and Feel

Previous: Permissions	Up to Contents	Next: Actions I: The Basics

Getting Started with Xataface

Jump:

Web Lite is a simple framework for developing data-driven web applications in PHP and MySQL. This tutorial will show you how to get a dataface powered web application running in under 20 minutes.

Changing the Look and Feel

Change the way your application looks by adding custom headers, footers, and sections, and by overriding the default templates with your own custom templates.

A generic Xataface application provides a reasonably good look and feel for a lot of applications. However, most applications still require some customizations. Most applications will want to have its own logo displayed at the top (instead of the Xataface logo), and quite often a custom footer is required also. Xataface allows for this form of customization as well as many other fine-grained modifications to the user interface via custom templates and delegate classes.

Before we begin

Most of your customizations will necessitate the use of custom templates. For this our application will need a 'templates' directory to store the templates, and a 'templates_c' directory to store the compiled templates (since Smarty template engine is used for processing the templates, and it needs a directory to store the compiled versions). So, before we begin our customizations, we need to make sure that these directories exist, and that the 'templates_c' directory is writable by the web server (e.g. chmod 0777).

Our application's directory structure should resemble the following:

Although, please disregard the 'install' directory and the 'README.txt' file. They have been added to store extra information about this tutorial. The crucial additions are the 'templates' and 'templates_c' directories.

Xataface templates

Xataface handles all of its look and feel using Smarty templates. They are all stored in the Dataface/templates directory. A quick glance at the contents of this directory will give you an idea of what templates are available. Some templates display a whole page, while others simply show a section of a page. Some of the more notable templates include:

Dataface_Main_Template.html - The main template used to render all pages in the application.
Dataface_Logo.html - The logo that appears in the upper left corner of the application.
Dataface_Application_Menu.html - A placeholder to add a custom menu to the left column of the application.
head_slot.html - A placeholder to add contents to the <head> section of each page.
left_slot.html - A placeholder to add contents to the left column of the application (almost the same as Dataface_Application_Menu.html ; use either, or both).
global_header.html - A placeholder to add contents to be displayed before all other contents in the <body>. Allows you to add a full custom header.
global_footer.html - A placeholder to add contents to be displayed after all other contents in the <body>. Allows you to add a full custom footer.

For a more thorough treatment of Xataface's core templates, see "Tour of Xataface's Core templates" in the Xataface Customization tutorial.

Overriding templates

To change the contents of any given template in the Dataface/templates directory, all we have to is copy the template into our application's 'templates' directory, and make the desired changes. The new template will be used instead of the default template. In general, to override a given template, just add a template of the same name to the application's 'templates' directory.

Example 1: Changing the logo

The Xataface logo is nice, but our application should probably have a custom logo that says "Faculty of Widgetry" or something to that effect. We will do this by completing the following steps:

Create a new logo and save it as a jpg, gif, or png file.
Add a directory named images to our application's directory. (Note: this is optional. There is no significance to the name images. I simply create this directory because I want a place to store my site's images so that it is clean and logical).
Save the new logo in the images directory. (In this case we will save the image as 'fow_logo.gif').
Copy the Dataface_Logo.html template from the Dataface/templates directory into your application's templates directory.
Change the new Dataface_Logo.html template so that it displays our new logo.
The original template contains:
```
<img src="{$ENV.DATAFACE_URL}/images/logo-small.jpg" 
  alt="Xataface"/>
```
Change it to:
```
<img src="{$ENV.DATAFACE_SITE_URL}/images/fow_logo.gif" 
alt="Faculty of Widgetry"/>
```
Notice the {$ENV.DATAFACE_SITE_URL} tag. This is a smarty tag that displays a Xataface environment variable. The {$ENV.DATAFACE_SITE_URL} variable will render the URL Path to the application. Since we saved our new logo a 'fow_logo.gif' in the images directory of our application, this change will result in our new logo being displayed.

Now we can load the application in a web browser and see our new logo in place of the old Xataface logo.

Inserting content into blocks and slots

The above example, where we overrode the Dataface_Logo.html template, works well only in a select few situations. Most of the time we don't want to override an entire template. We just want to add some content to it or change it a little bit. Most of Xataface's templates contain placeholders called "blocks" and "slots" for you to be able to add your own content. As an example, let's look at some of the source for the Dataface_Main_Template.html template

<table width="100%" border="0" cellpadding="5" id="main_table">
<tr>
<td valign="top" id="left_column">
    {block name="before_left_column"}
    {define_slot name="left_column"}
        {if !$ENV.prefs.horizontal_tables_menu and $ENV.prefs.show_tables_menu}
            {block name="before_nav_menu"}
            {include file="Dataface_NavMenu.html"}
            {block name="after_nav_menu"}
        {/if}
        {block name="before_application_menu"}
        {define_slot name="application_menu"}
            {include file="Dataface_Application_Menu.html"}
        {/define_slot}
        {block name="after_application_menu"}
    {/define_slot}
    {block name="after_left_column"}
</td>

This is the little bit of markup that produces the left column of the main table in the Xataface application. The content inside the curly braces are template markup tags that have meaning. Take special notice of the {block} and {define_slot} tags. These allow you to add your own content to this template via your delegate classes. A {block} tag will display custom content provided by your delegate classes. The {define_slot} tag will show your custom content, if it is available - OR - it will display the contents that lie between the {define_slot} and {/define_slot} tags.

Example: Adding a side-bar to show the courses for the current program

Let's say we want to add a side bar so that when we view a Program record, we can easily see the courses in that program. We will do this by "inserting" content into the "before_left_column" block in the main template shown above. We need to add a delegate class to the 'Program' table in order to make this happen, so we create the file tables/Program/Program.php with the following content:

<?php
class tables_Program {

    /**
     * Inserts content at beginning of left column of application.
     * i.e. replaces {block name="before_left_column"} tag.
     */
    function block__before_left_column(){
    
        echo "<div id=\"courses-sidebar\">
            <h4>Courses in this program</h4>";
        
        // Obtain reference to current Program record
        $app =& Dataface_Application::getInstance();
        $programRecord =& $app->getRecord();
        
        //Make sure that there is a program record currently selected.
        // (e.g. we may be in list mode or there may be no
        // Program records in the found set.
        if ( !isset($programRecord) ) return false;
        
        // Now we show the courses in this program
        echo "<ul>";
        foreach ( $programRecord->getRelatedRecordObjects('Courses') as $course){
            echo "<li>".$course->val('CourseTitle')."</li>";
        }
        echo "</ul>
        </div>";
        
    }
}

?>

Note that it is not good form to embed HTML inside echo statements as we did in this example. A much more elegant solution would involve the creation of a template that is called from the block__before_left_column() method.

So to insert content into the {block name="before_left_column"} tag, we just implement a method named "block__before_left_column". in general. The above example makes use of the Xataface API. You can look up any class or function call using the API docs at http://dataface.weblite.ca.

Now we can load our application, and select the "Program" tab to view one of our "Program" records - and notice our new side bar:

Also notice that this sidebar only appears in the "Program" table (If you click the "Course" tab, this sidebar will disappear). This is because we defined the method in the "Program" table delegate class.

Source files download

Download the source files for the Faculty of Widgetry Application

(Note: These sources are out of date, and include PHP short open tags. You will likely need to change all PHP open tags from "<?" to "<?php")

From here...

This section has given you just a brief glimpse of the Xataface's templating capabilities. The rabbit hole goes much deeper, however. For a more in-depth exploration of the subject, please refer to the following pieces of documentation:

Customizing the Xataface Look and feel (Tutorial)
Dataface_SkinTool (API Docs)
Xataface Template List (API Docs)

Previous: Permissions	Up to Contents	Next: Actions I: The Basics

Pages