You are here: Home > Documentation > tutorial > Customizing the Web Lite Look and Feel > Customizing templates

Previous: Tour of Web Lite's Core Templates	Up to Contents	Next: Extending Templates

Customizing the Web Lite Look and Feel

Jump:

The Xataface includes some powerful templating tools that give the developer the power to modify any part of the interface easily.

Customizing templates

Xataface provides two different methods of template customization: Override, and Block insertion.

Customizing the look and feel of a Xataface application generally entails changing certain portions of the existing templates. While it may be tempting to just go into the Dataface/templates directory and start making changes, there is a much better way. The previous section hinted at the ability to override existing templates by simply placing a template of the same name into your application's 'templates' directory. We will refer to this as "overriding" templates.

Alternatively, Xataface's templates contain several insertion points called "blocks" where you insert your custom content using methods of your delegate classes.

Overriding Templates

Any of Xataface's core templates can be overridden by adding a template of the same name to your application's 'templates' directory. For example, suppose we want to change the logo that appears in the upper left of every page of your Xataface application. The template responsible for this is the 'Dataface_Logo.html' template. So we will copy the Dataface_Logo.html file from the Dataface/templates directory to your application's templates directory, and modify it as follows:

<h1>My header - instead of a logo</h1>

Now, load up your application in your web browser and you will see that the Xataface logo in the upper left has been replaced by some heading text:

This technique can be used to override any of the templates in Xataface to suit your application's needs.

Custom Blocks

Overriding templates may be appropriate in some situations, but it may be overkill if you just need to add a little bit of content to a section of the template. It would be kind of a waste to have to override an entire template because you want to add a link somewhere. Luckily, Xataface allows you to easily insert content into a number of places in its templates by implementing appropriately named methods in the delegate class. If you look at any of the Xataface core templates, you will notice a number of {block} tags. Consider the following snippet from the 'Dataface_Main_Template.html' template:

<body {block name="body_atts"}>
	{block name="before_body"}
	{define_slot name="html_body"}<!-- Replace the entire HTML Body with the "html_body" slot -->
	<div id="top-section">
		{block name="before_header"}
		{define_slot name="global_header"}{include file="global_header.html"}{/define_slot}
		{block name="after_header"}

This is the beginning of the <body> tag that is used in nearly all pages of a Xataface application. Notice the {block} tags. In particular, right now, let's consider the tag:

{block name="before_body"}

What this tag does is call a method named "block__before_body" in the delegate class of the current table if it exists, or the block__before_body() method in the application's delegate class. This means that you can add content to the page where the {block} tag exists by simply implementing a block__before_body() method which outputs some content.

Example: Inserting content into the "before_body" block

The 'before_body' block occurs before anything else on the page. Let's insert some content there:

<?
class tables_departments {
    function block__before_body(){
        echo "here is some text";
    }
}
?>

The above is a simple delegate class for the 'departments' table. Now if we view the departments table in our application it will look like:

Notice that the contents of our 'block__before_body()' method have been printed at the top of the page before anything else. Note also that this block will only be filled in the 'departments' table because we defined the method in the 'departments' table delegate class. If we had defined it in the application's delegate class, then it would appear on every page of the application.

How do you know which blocks are available?

So you know that you need to insert some content into your application's display at some point. But how do you know which block is the right block to fill? Xataface's debug mode comes in handy for this. If you add "debug=1" to the beginning of your conf.ini file, then Xataface will output some helper text on each page load to indicate where each block is located. The conf.ini file will begin as follows:

debug=1

[_database]
...

i.e. it comes before the first [_database] section. Then your output will look something like this:

Notice how the text "Block ..." is printed all over the page. These are markers to show where the blocks are located, and are available to be filled.

Previous: Tour of Web Lite's Core Templates	Up to Contents	Next: Extending Templates

Pages