Building a Template

Tutorials / Templates

What are XT templates?

What does XT stand for?

XT stands for XML Templates, because XT templates are simply XML documents which are a combination of XHTML and specialized XML tags. XT is the template language and rendering engine used by Sitellite to generate web pages for visitors.

What does XT do?

Sitellite uses the XT template engine to compile the different components of the web site user interface together for the web site visitors, including the content, the graphic design, and any programming code required to render a given web page.

What is content in a CMS?

Content means any piece of information on the site that conveys particular meaning (ie. the specific subject matter of a page), in contrast to the graphic design, which provides general or relational meaning (ie. web site navigation) and brand reinforcement.

Content types

In Sitellite, there can be any number of content types. Typically, these will include:

• Web Pages
• Web Files (ie. PDFs, Word documents, etc.)
• News Stories
• Event Listings
• Sidebars (ie. lead-ins to other content types)

Template language

XT templates are ordinary XHTML documents with the addition of XT-specific tags that are replaced with actual content by the template engine.

Simple server-side templating language

The need for XT is that XHTML on its own doesn't have the ability to talk to external sources, such as the Sitellite content repository, to retrieve content. So with XHTML, every page has to have the content completely mixed in with the design, or else you have to use some sort of intermediate processor to put the two together on-the-fly.

Traditionally this was done using programming languages such as Perl, Java, or PHP, however these are far too complicated and usually only result in mixing the design with the programming code instead of the content, which is still a problem.

To solve this problem, we created XT, an intermediate language which is much closer to standard XHTML and therefore less complex than a full-blown programming language, but still powerful enough to solve the problem of joining the content with the graphic design of a web site.

Separation of content vs. templates

The traditional method of simply storing each page in HTML format breaks down quickly because the content writers need to either bother themselves with HTML, or need to rely on the graphic designers to actually apply the content changes. This adds an unnecessary step to each and every content change made to a web site.

So the benefit of using a template language such as XT is that by storing your web site content separately from your web site graphic design, you make it possible for the people responsible for each of the two to manage their part themselves.

Where are the templates located?

XT templates live in the "inc/html" sub-folder in any Sitellite installation.

Template sets

Templates are organized into multiple "sets", which typically contain completely separate designs. In this way, the Sitellite CMS user interface can use the same template organization as the rest of the web site, but still have its own graphic design. You can have as many designs for as many applications as you want running on top of the Sitellite platform.

The Template Naming Convention

Inside a template set, templates are stored as individual ".tpl" files that contain the XHTML and XT markup. A single template set can have multiple templates within it, which are organized according to output mode and by template name. The name of the template file is made of three parts: the output mode, the template name, and the tpl extension. For example, the default html template is named html.default.tpl .

Output modes

Output modes allow you to offer different output formats on a web site, instead of just XHTML. This way, you can accommodate different types of visitors as new technologies become available, such as cell phones and PDAs. You can also provide alternative file formats such as PDF output for your web site using output modes. A chapter in this lesson covers output modes more in details.

Multiple templates

Even within the same output mode (ie. XHTML), you may still want some pages to look different than others. For example, your main index page might have more branding and imagery and less content than inside pages, and some inside pages may require more width than others. Sitellite allows you to do this as part of the standard template naming convention.

Templates and CSS

Any good design nowadays contains more than just XHTML, but rather a design consists of two distinct parts. The first, the XHTML, is meant to describe the document moreso than to control the display of it. The second, the CSS, is meant to apply style to the different markup tags in the markup document. In this way, you have even more control over your design, and more meaningful markup (ie. metadata) about your documents as well.

In Sitellite, CSS files live in the template set folders alongside templates. They are considered of equal importance to a complete web site graphic design.

In fact, because XT templates must be valid XML (ie. XHTML instead of HTML), Sitellite actually encourages additional standards compliance that are otherwise not required of most CMS software.

XHTML transitional

XHTML is the newest version of the HTML markup language. The reason for the added "X" is because XHTML is HTML with a few new added rules that allow it to be XML compliant.

XML compliance allows HTML documents to better interoperate with new technologies, as well as other XML-based markup languages, such as Scalable Vector Graphics (SVG), MathML, and XT.

By requiring XHTML compliance in Sitellite's templates, we were able to create the XT template language using only a standard XML parser, which makes template parsing much more stable and predictable.

Directory Layout

The main design templates live in the inc/html folder of your Sitellite installation.  Each template set (akin to a theme) lives in a subfolder below inc/html.  Each theme has at least three things in it: an html.default.tpl file containing the default template to use for that set, a site.css file containing the styles for that template set, and a "pix" folder for storing related graphics.

Sitellite ships with two built-in template sets, which we recommend you add to instead of modifying: "default", and "admin".  The "default" set contains the look of the example web site installed with Sitellite, and the "admin" set contains the design of Sitellite's administrative user interface.  These can be a valuable resource in terms of a working example of a template set.

inc/html/
    default/
        html.default.tpl
        site.css
        pix/
            spacer.gif
    admin/
        html.default.tpl
        site.css
        pix/
            spacer.gif

Naming Scheme

Where Sitellite's template system gets interesting is in the ability to specify alternate templates within a set.  This is done in one of two ways:

1. Via the "mode" parameter.

2. Via the page_template() function or "template" page attribute.

The "mode", which defaults to "html", affects the first part of the template name, and is optionally specified via the request URL (ie. ?mode=html).  This allows you to provide multiple subsets of a template set based on the mode (aka. content type) that the visitor wants.  In this way, you could offer a web site in both HTML format (the default), and WAP format for cell phones, to name one potential use.

The second part of the template name is considered its actual name (the mode could be called a prefix if you like, and ".tpl" is simply a suffix that tells you the file is a template file).  The actual name corresponds either to the "template" attribute of the page object (accessible under the "Properties" tab in the page editor, or via the page_template() function inside boxes and actions), to the template attribute of a parent page that is marked as a section root (also under the "Properties" tab), or the name specified in the "default_template" setting in inc/conf/config.ini.php (which you should leave as "default").

This allows you to specify additional templates in the same set that alter the look of specific pages, or of entire sections of your web site.

With all of these naming options, Sitellite's template system offers undoubtedly the most flexible and advanced template selection structure available in any PHP-based system today.

Custom Template Sets

New template sets are installed simply by dropping them into the inc/html folder.  To change the default set used by your web site, simply change the "default_template_set" value in inc/conf/config.ini.php to the name of the set you want to be the default.

You can also install additional sets and use them as themes for Sitellite-based apps, which is exactly what we do with the Sitellite UI itself.  To do this, simply specify the template set name in your app's access.php files, like this:

 sitellite_template_set = myTemplateSet

In addition to being able to edit XT templates directly using any text editor and a browser, or an HTML design tool such as Dreamweaver, you can also edit them directly in Sitellite using the SiteTemplate app. You'll find SiteTemplate under the Control Panel > Tools menu.

Permissions

In order for SiteTemplate to be able to modify your templates, make sure you have your folder permissions set correctly. This is usually done in the Sitellite installation process, but some site administrators skip certain permissions or change them afterwards.

The "inc/html" folder and sub-folders need to have their permissions set to allow the web server to write to them, usually 0777.

SiteTemplate benefits

The benefits of using SiteTemplate instead of an external editor lie mainly in its integration with standards verification services. SiteTemplate has the ability to validate your XML and will require valid XML before it will save your changes, so you never break your site with a template change. SiteTemplate also validates against the following standards at the click of a button:

• XHTML compliance
• CSS compliance
• Web Accessibility Initiative (WAI) compliance
• Section 508 Accessibility compliance

SiteTemplate: Choose a Template

SiteTemplate: Template Set

SiteTemplate: Template Editor

If you click on a template name, it opens the template editor. This is a standard text editor, similar to Xed editor used elsewhere in Sitellite, but including special functions to help you building your templates.

To begin using the SiteTemplate XT template editor, first open a web browser and log into your Sitellite account on your web site. Next, click on the "Control Panel" option in the Sitellite top bar. From the Control Panel view, select "SiteTemplate" under the "Tools" pane in the top right of the page.

This will bring you to the first screen of the SiteTemplate editor, where you can choose the template set that you would like to modify. When you select a template set, you will see a list of templates, CSS files, and images belonging to that template set.

For the purposes of our examples, let's click the "New Template Set" link and create our own individual template set. You can use your name for the name of your template set. Once you've finished it will take you to your new template set. From here, click on the "HTML > Default" template.

The template editor screen

When you click on a template within a set, you are brought to the template editor screen. This screen contains several features, which include:

The default XT template

Inserting page elements

From the template editor screen, we can insert any markup we want into the template, as long as it is XML compliant.

Exercice 1

<html>
	<head>
		<title>Window Title</title>
	</head>
	<body>
		<h1>Page Title</h1>
		<p>Page Content</p>
	</body>
</html>

<html>
	<head>
		<title xt:content="head_title">Window Title</title>
	</head>
	<body>
		<h1 xt:content="title">Page Title</h1>
		<span xt:replace="body">
		<p>Page Content</p>
		</span>
	</body>
</html>

Click the "Preview" button again to see your new changes. You should see your original page title, window title, and page content replaced with sample data from the template previewer.

Here we have introduced the main two XT commands, which act as attributes attached to ordinary XHTML tags. These are:

XT expressions

The following is a list of some of the main web page properties that can be inserted into your templates:

Exercise 2: Using different expressions

Try replacing the title with another field in your template, or adding new tags that reference additional fields.

Substitution

<xt:tpl>
    <xt:var name="title" />
</xt:tpl>

<xt:tpl>
    <xt:var name="title" /><br />
    <xt:var name="object/title" /><br />
    <xt:var name="path: object/title" /><br />
    <xt:var name="php: object.title" /><br />
</xt:tpl>

<xt:tpl>
    <span xt:replace="title">This is a fake title</span>
</xt:tpl>

http://www.yourWebSite.com/inc/html/test/html.default.tpl

<xt:tpl>
    <a href="${site/url}">Phone home</a>
</xt:tpl>

<xt:tpl>
    <a
        href="http://www.yourWebSite.com/"
        xt:attributes="href site/url"
    >Phone home</a>
</xt:tpl>

<xt:tpl>
    <a
        href="${site/url}"
        xt:content="site/url"
    >http://www.yourWebSite.com/</a>
</xt:tpl>

Inserting boxes

• Latest headlines
• Upcoming events
• Any web site navigation

Boxes can be embedded into XT templates by using the "xt:box" tag. The syntax for a box is the name of the app that the box belongs to, ie. "news", followed by a forward-slash (/), followed by the name or path to the box. Here are a few examples:

• <xt:box name="news/sidebar"> <xt:box>
• <xt:box name="sitellite/nav/breadcrumb"> <xt:box>
• <xt:box name="sitetracker/bug"> <xt:box>

Exercise 3: Calling boxes

<xt:box name="sitellite/nav/breadcrumb">
	<p>
		<a href="#">Home</a> / <a href="#">Courses</a> / XT Templates
	</p>
</xt:box>

Advanced XT expressions

In addition to the above expressions that simply called aspects of the web page object, there are several different types of expressions. These expressions can be used and combined with the various XT tags to create some really powerful templating features.

The three types of expressions are as follows:

Understanding expressions is the key to understanding how all of the advanced XT features work.

Path expressions

A path expression looks exactly like how we named boxes in the "xt:box" tag. Some examples include:

• object/id
• site/domain
• cgi/page
• session/username

In each case, the path starts with the object name and ends with some property of that object, separated by a forward-slash. Each of those examples are real paths, referring to objects in the Sitellite CMS by each of those names.

The "object" object is a special case though. The "object" object is the default object being acted upon by the XT template, which in the case of a web page is the web page object itself. So when we said:

 <h1 xt:content="title">Page Title</h1>

we were actually saying:

 <h1 xt:content="object/title">Page Title</h1>

which, if you remember that paths start with "path: " so that XT knows for sure what type of expression they are, we are actually saying:

 <h1 xt:content="path: object/title">Page Title</h1>

But since "object" is the default, and since the default expression type is a path, we can shorten it and keep it simpler and more readable.

String expressions

String expressions are very simple, and on the surface don't appear very powerful or even all that useful, but they can come in quite handy for the simple fact that you can include in them what we call "sub expressions". I'll illustrate this with an example:

<title xt:content="string: Simian Systems - ${head_title}"> </title>

Using the "${sub-expression}" syntax, we can actually embed a path expression into the middle of a string expression, allowing us to combine the two to create content that is part static and part dynamic.

PHP expressions

Sometimes we need to refer to objects in ways other than by simply referencing their properties. In these cases, we need something more powerful than a path expression, so we use a PHP expression.

PHP expressions actually use a shorthand for the full PHP programming language syntax, which helps make them simpler and more convenient for inclusion in XT templates.

An example of a PHP expression is:

 <h1 xt:content="title" 	xt:condition="php: not empty (object.title)"> 		Page Title </h1>

Now that we've looked at the raw expressions themselves, let's put them to use.

Simple loops

<ul>
	<xt:loop through="item php: range (1, 10)">
		<li xt:content="loop/item/value">1</li>
	</xt:loop>
</ul>

<ul>
	<li xt:loop="item php: range (1, 10)">
		<span xt:replace="loop/item/value">1</span>
	</li>
</ul>

<xt:tpl>
    <table border="2">
        <xt:loop through="lang intl/languages">
            <tr>
                <td xt:content="loop/lang/index">en</td>
                <td xt:content="loop/lang/name">English</td>
            </tr>
        </xt:loop>
    </table>
</xt:tpl>

Conditional rendering

<h1 xt:content="title"
	xt:condition="php: not empty (object.title)">
		Page Title
</h1>

<xt:condition>
	<xt:if expr="php: session_valid ()">
		<p>Welcome,
			<xt:var name="session/firstname" />,
			<xt:var name="session/lastname" />
		</p>
	</xt:if>
	<xt:else>
		<form action="/sitemember-app" method="post">
			User: <input type="text" name="username" /><br />
			Pass: <input type="password" name="password" /><br />
			<input type="submit" value="Enter" />
		</form>
	</xt:else>
</xt:condition>

Multi-lingual text

<xt:intl>Text to translate</xt:intl>

Changing attributes

<p
	align="left"
	xt:attributes="align intl/align">
	Some text here
</p>

<p align="${intl/align}">Some text here</p>

Outputting HTML entities

 <ch:nbsp />

Full list of HTML character entities

• Full list of HTML character entities

xmlchar library

• xmlchar library

Includes

<xt:tpl>
    <xt:inc name="footer.html" type="plain" />
</xt:tpl>

<xt:tpl>
    <xt:inc name="footer.html" type="plain">
        <p>
            This is some temporary text that will be replaced
            by the file footer.html when this template is
            rendered in Sitellite.
        </p>
    </xt:inc>
</xt:tpl>

<xt:tpl>
    <ul>
        <xt:inc
            name="http://slashdot.org/index.rss"
            type="xml"
            item="/rdf:RDF/item">
            <li>
                <a href="${xml/link}" xt:content="xml/title">Title</a>
                <span xt:replace="xml/description">Description</span>
            </li>
        </xt:inc>
    </ul>
</xt:tpl>

<xt:tpl>

    <xt:cache scope="application" duration="3600">

    <ul>
        <xt:inc
            name="http://slashdot.org/index.rss"
            type="xml"
            item="/rdf:RDF/item">
            <li>
                <a href="${xml/link}" xt:content="xml/title">Title</a>
                <span xt:replace="xml/description">Description</span>
            </li>
        </xt:inc>
    </ul>

    </xt:cache>

</xt:tpl>