Sitellite Design Templates

Please subscribe to chat.
Older messages can be viewed in the chat archive.

Chapter 4: Building a XT template

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 template name and output mode listed at the top
The template data itself in a large text area
A toolbar for inserting frequently used XT tags
The Save, Preview, and Cancel buttons
A validation service selector

The default XT template

Looking at any XT template, you can immediately see that it is simply a mixture of XHTML and XT tags. The XT tags are just like the other XHTML tags except that their names all begin with "xt:". This helps keep them distinct for both ourselves as well as the XT template rendering engine.

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

Click on "Cancel" button to return to the main page of the template editor. Create a new XT template named "test" and enter into it the following XHTML markup:

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

Click the "Preview" button to see your template. Next, add the following XT tags:

<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:content	Replaces the contents of the XHTML tag with the specified XT expression.
xt:replace	Replaces the entire XHTML tag with the specified XT expression.

XT expressions

XT expressions are the values placed inside the XT tags. These are what allow you to refer to the page elements such as title, description, and body.

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

id	Page ID
title	Page title
nav_title	Page title as used in the web site navigation
head_title	Page title as used in the top bar of the browser window
below_page	The page that the current page is a child of in the web site hierarchy
is_section	Whether the page is a section index or not. The properties of a section index, such as the template it uses, are inherited by pages the underneath it
template	Which template name is being used for this page
include	Whether this page is included in the web site navigation or not
keywords	The keywords that have been assigned to the current page
description	A description of the current page (ie. for the meta tags)
body	The body of the page
toc	A table of contents linking to the headers within the body of the current page. This is useful for providing additional navigation within longer pages

Exercise 2: Using different expressions

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

Substitution

The key feature of all template languages is called "substitution". This is the process whereby the template engine replaces special "tags" throughout a given template with actual data. The tags are like pointers that refer to parts of the data sent to the template. This data can be an array, an object, or any other data type. In XT, there are specific data objects we'll be using. Having the full list of these can help in keeping your requisite knowledge of XT a finite amount.

Let's look at the most basic substitution in XT:

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

If you make this your entire main XT template (named html.default.tpl in your inc/html/test folder), choose 'test' as the default temlate set (in Control Panel > Admin > Site Settings > Default Temlate Set), and you go to http://www.yourWebSite.com/index, you will see the title of the index page displayed alone on the screen. Not very exciting yet, but give it time.

Next, we're going to look at other names you can use to refer to the same data value. You can call these aliases -- or perhaps the one we just made is actually an alias of one of the ones just ahead, and it's the real one.

Add the following highlighted lines to your template, save it, and refresh your browser window.

<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>

You should now see your index page title displayed four times in a row. This illustrates a few aspects of XTE, the XT Expression language, right off the bat. First is that you can access properties of the default object, named "object", without having to specify the object explicitly. Second is that XTE has at least two modes of interpretation (three in total actually), being "path" and "php", the default of which obviously being "path". Third is that in the php mode, it's not actually syntactically correct PHP code you're writing. This php syntax is called PHP Shorthand, which allows you to get away with leaving out the dollar signs, property/method arrows, quotes, and operator symbols, leaving you with a more readable code-like syntax. This helps avoid the need to refer to objects like this: $object->someValue. The literal "greater than" entity is enough to give me nightmares at least. The PHP Shorthand notation is documented into the XT Reference chapter of this lesson.

Next, let's look at a few more ways of substituting values.

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

Rendering this template in Sitellite will show you the same thing as the first example we did, but if you look at it, there's new text in place that must be there for some reason. Try viewing our template in the browser directly, by going to the following link:

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

You should see the string "This is a fake title" where you were seeing the index page title moments ago. View the source of the template, just to see that it in fact hasn't been rendered. This is how Sitellite enables previewability during the design process.

Now let's look at a few more ways of writing XT tags that will be substituted for data. Add the following to your template:

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

When rendered in Sitellite, you will see a link that points to your web site. When previewed outside of it, of course, you will see a link pointing to the literal string "${site/url}". The ${} syntax allows you to specify paths inside attributes of any ordinary tag. An alternate way of specifying the same thing as the link above, without compromising previewability of the link, is as follows:

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

The xt:attributes attribute essentially allows you to assign tag values to attribute names. Nothing fancy. A variation on the xt:replace attribute we saw above is the xt:content attribute, which only replaces the contents of the tag, not the whole tag itself, with the specified data. For example:

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

Inserting boxes

"Box" is a term used in Sitellite to refer to an individual PHP script written using the Sitellite framework. They are called boxes because they are used to output some sort of dynamic functionality that is to be displayed for a web site visitor somewhere on the web site. Examples of boxes include:

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

Try adding the above box calls to your template and previewing the results.

You can also add sample data between the box tags to imitate the box's output when viewing the template itself directly in a browser (ie. outside of the XT rendering engine). For example:

<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:

path	Path expressions are a simplified way of referring to the contents of objects in the XT object register. Path expressions start with the optional prefix "path: " followed by the name of the object, followed by the name of a property of that object.
string	String expressions are used to output literal text, called "strings". A string expression starts with the prefix "string: " followed by any string of text.
php	A PHP expression starts with the prefix "php: " followed by the PHP expression.

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.

Exercise 4: Combining path and string expressions

Experiment with different paths and strings to create new combinations. Try making one that welcomes a user by name.

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>

Exercise 5: Using PHP expressions

Experiment with different PHP functions that you know of, or look more up at http://www.php.net/, to come up with new possible uses for PHP expressions. Try outputting a PHP expression displaying the current date and time.

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

Simple loops

Loops in XT are used to output repeated blocks of the template, such as lists and tables. A loop uses the following syntax:

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

Or alternately, in some cases you can use the more concise syntax:

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

The addition of the "/value" should appear peculiar. The reason for this is that a loop object in XT contains more than simply the value of the current loop item. These additional attributes are referred to by name, as is any other property of an object, and they are:

Attribute	Description
index	The actual index key of the loop item. In cases where you would be looping through named key/value pairs, index would contain the name.
number	The numeric index of the loop item, starting at 1 and increasing by 1 each time.
length	The number of items in the loop.
start	Whether the current item is the first or not.
end	Whether the current item is the last or not.
value	The loop value in cases where the items being looped through are not objects or arrays. This would be the opposite of index in such cases.
even	Whether the index value (not the number) is even or not.
odd	Whether the index value (not the number) is odd or not.

Now let's look at a more complex example. Here you can see where the power of XT's looping constructs can come into play, allowing for the ability to easily loop through and utilize complex data structures.

<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

Let's start by revisiting one of the examples from above that used the "xt:condition" tag attribute.

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

What happens here is that the condition tag is checked and only if it is determined to be true does the tag and anything inside of it display. Otherwise, the tag is erased from the template during the output phase. You can also do more complex conditional rendering, such as displaying one thing in one case and something else in another. The following example shows a login form for anonymous visitors, but a welcome message for those who are logged in.

<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="/index/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>

Let's break it down into pieces to see how XT understands it. First, there are <xt:condition></xt:condition> wrapper tags around the entire condition. Full XT conditions require these tags to group a set of <xt:if> <xt:elseif> and <xt:else> tags together to provide multi-condition capabilities. This makes XT very nearly a complete programming language in its own right, together with loops and variables.

Next, we have the <xt:if></xt:if> tag with an expr="" attribute. This attribute calls the Sitellite function session_valid() to determine whether the user is logged in at all or whether they are browsing anonymously. If they are logged in, everything between those tags is shown and the condition exits. When a condition evaluates to true, the entire condition exits, skipping any subsequent or tags below.

The <xt:else> condition would be shown only when none of the above conditions are met. This is essentially a fallback action (ie. "if all else fails, do this"). <xt:else> is optional, in which case often the xt:condition attribute would be a better solution. What the <xt:else> does here is display a form for the anonymous user to log in if they'd like.

Previewing this outside of Sitellite (ie. directly through the browser) will show you the output of all of the conditions. In this way, you can preview the results of each without having to test each condition, visually. Of course, functionally you always want to test each possible condition to ensure that it works as you'd expect.

Multi-lingual text

You can translate any text in a template automatically using Sitellite's translation builder and the following tag syntax:

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

Changing attributes

In addition to changing the contents of a tag, you can also change specific attributes of it using the following two methods:

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

Or even simply:

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

Outputting HTML entities

If you've inserted a   or any other HTML entity into your XT templates, you've discovered that it results in a nice "Illegal entity" error. This is because XT templates are XML documents, not HTML documents, and XML parsers know nothing about the special entities, such as  , defined in the HTML specification.

In XT, to insert a non-breaking space into a template, you can say:

 <ch:nbsp />

XT will translate this into an ordinary   in the final web page output. You can use this syntax for any other HTML entity. For example: <ch:copy />, <ch:eacute />.

Exercise 6: Using special characters

Try adding these special character tags to your template to see how they work. Experiment with different entities that you know, or look new ones up here:

Full list of HTML character entities

xmlchar library

Includes

While boxes are the preferred method of inclusion in Sitellite, as they adhere to Sitellite's automatic access control and configuration facilities, I will still document includes here as well, since they can present an elegant, simple, and often powerful solution to certain problems.

First, let's look at the most basic file inclusion:

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

This will include the file footer.html into your template, treating it as a literal inclusion (ie. not performing any transformation on it at all). As you can see, the lack of transformation is due to the type="plain" attribute. The default inclusion type (ie. when no type is specified at all) will treat the included file as an XT template itself, and transform it prior to inserting it into the current template. Next, let's look at the real potential includes possess in maintaining previewability.

<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>

As you can see, the ability to specify fake data, including XHTML tags, is a powerful feature of the XT template system. Finally, before moving on to boxes, let's take the include facilities to a new level, and include content from another web site. But even better, let's include headlines from another web site, pulled from an RSS file.

<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>

Pretty cool, eh? However, please beware that while this capability looks really cool, it is not a complete example yet. To be respectful of other web sites, you should always cache RSS feeds locally and only request them periodically -- otherwise for each visitor to your site, there's another retrieval of the file from their site. To finish this example then, you'll want to add the following to the template:

<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>

Chapter 5: Using Output Modes »

Username:
Password:
	Forgot your password?

Member Login