Chapter 8: XT Template Reference

This tag loads a Sitellite box. In a box tag, the name, which is the only required attribute (the rest are all dependent on the parameters the box in question requires), refers to the name of the box, starting with the name of the app (see the inc/app folder for the list of available apps), and then with the path to the box itself. The additional attributes of the box call are passed to the box in an array called $parameters. So for example, in the above box call, the variable $parameters['position'] would contain the value "left".

<xt:box name="sitellite/sidebar" position="left" />

Defines a reusable template block. A block can be defined in an included template and still be used within the current template. Block parameters can be used using the block/param path.

<xt:block name="sidebar">
	<h2
		class="sidebar"
		xt:content="block/title"
	>Block title</h2>
	<p
		class="sidebar"
		xt:content="block/body"
	>Block body...</p>
	<p
		class="sidebar"
		align="right"
	>
	<a
		href="blocklink.html"
		xt:attrs="href block/link">
	<xt:intl>Learn more</xt:intl>
	</a>
	</p>
</xt:block>

Sitellite features partial-page caching with the <xt:cache> commands in your XT templates. The <xt:cache> tags offer unfortunately little performance improvement in most cases however, since XT still has to parse and loop through the tags between the <xt:cache and </xt:cache> either way. Essentially, this will only see performance improvements when you wrap these tags around content that requires that boost in performance. Another feature of <xt:cache> is the ability to cache a separate copy for each specific visitor, so that performance is boosted on subsequent page requests from the same visitor. This has the advantage of allowing content to be cacheable that still contains personalized data. In this case, if we didn't include the scope="session", the next visitor to that screen would see the previous visitor's name and profile information -- a big privacy faux pas!

<xt:cache>
  <xt:box name="sitellite/sidebar" position="left" />
</xt:cache>

<xt cache scope="session">
  <h2>Your profile, <xt:var name="session/firstname" />:</h2>
  <xt:box name="myapp/user/profile" />
</xt:cache>

The <xt:code> tag tells XT to wrap the enclosed content in the language identifiers of your choice (the default is PHP). The CDATA tags are in case you have any "illegal entities" in your source code (namely, < and &), as does the above example since it prints a <br /> tag.

<xt:code><![CDATA[

echo 'hello<br />';

]]></xt:code>

Comment tags in XT are stripped out. It allows you to have comments in your templates that are hidden from the final user output. However, this is a pretty moot point, since unless you turn it off via htaccess or your Apache configuration, users can access the source of your templates directly in the browser, and read these comments anyway. So don't put any passwords in there. Comments that you want remain in the final output of the template can be made using the following syntax. <xt:note> is an alias for <xt:comment>

<xt:comment>This is a comment.</xt:comment>
<xt:note>This is an other comment.</xt:note>

However, there's a problem with this approach: It's in clear violation of the preview capabilities of XT templates, since the comment text would be rendered as if it were web page content in the preview. To solve this, you can either insert a style="display: none" attribute into the comment tag itself, or if the browser you're using to preview the templates supports the following CSS trickery, you can include this rule in your CSS file:

xt\:comment, xt\:note {
	display: none;
}

Evaluates a complex conditional statement and returns the first expression to return true (or any value other than 0 and false), or the <xt:else> condition if all others do not succeed. This is a compount command, using the <xt:condition>, <xt:if>, <xt:elseif>, and <xt:else> tags. A shorthand for evaluating a single condition is to use the xt:condition attribute command, which evaluates only a single condition, and has no "else" clause either.

<xt:condition>
	<xt:if
		expr="php: foo == 'bar'">
		<p>foo is 'bar'</p>
	</xt:if>
	<xt:elseif
		expr="php: foo == 'asdf'">
		<p>foo is 'asdf'</p>
	</xt:elseif>
	<xt:else>
		<p>foo is unknown</p>
	</xt:else>
</xt:condition>

In addition to the comment tags, doctype declarations are stripped away during the XT template rendering. To compensate for this, we've added a special doctype tag, which can be used as follows. Make sure however that the <xt:doctype> tag begins on the first line of the document.

<xt:doctype
	root="html"
	access="public"
	name="-//W3C//DTD XHTML 1.0 Transitional//EN"
	uri="DTD/xhtml1-transitional.dtd"
/>

Executes an expression without returning the output it creates. Useful for setting complex values or multiple values at once.

<xt:exec
	value="php: a.val = b.val"
/>

This tag loads a Sitellite MailForm. In a form tag, the name, which is the only required attribute (the rest are all dependent on the parameters the form in question requires), refers to the name of the form, starting with the name of the app (see the inc/app folder for the list of available apps), and then with the path to the form itself.

<xt:form name="sitemember/register" />

Imports the specified package using the global $loader object, making that class available to the <xt:set-obj> command.

<xt:import pkg="saf.Date" ></xt>

Includes the specified file, which is processed depending on the type specified. The default type is 'xt', which processes the included file as a template. Additional types can be 'messy', which processes the file as a messy template, 'csv' which treats the file like a comma-separated values file. and uses the specified delimiter to split lines into table cells. Known delimiters are "comma", "tab", "colon", "semicolon", and "pipe", and other delimiters may be used by entering them in the delimiter attribute. Additionally, with the 'csv' type, a header attribute can be specified (set it to 'yes') to use the first line of the CSV file as a list of table column headers. If an include is of the type 'plain', it will not be evaluated at all. The last type is 'xml', which causes XT to treat the file as an XML document, parse it, and allow you to access a list of "item" values using XTE expressions. An item is a node in the XML document whose child nodes become its properties. The 'xml' type is unique in that it causes the markup contained within the inc tags to become the "sub" template used to display each item. Where in the XML document the items are to be found is determined either by the item attribute of the inc tag, which should contain an saf.XML.Doc.Query-compatible XPath expression. If this attribute is not present, XT assumes the items are all of the nodes below the root node of the XML document. New: 'simple' type has been added, which uses saf.Template.Simple to parse the included file. Name attribute value is also an expression now, with a default type of 'string'.

<xt:inc name="filename" ></xt>

<xt:inc name="filename">
	<p>
		Mockup text for
		previewing that will be
		replaced by the contents
		of the included file.
	</p>
</xt:inc>

<ul>
	<xt:inc name="sites.rss"
		type="xml"
		item="/rss/item">
	<li>
		<a href="#"
			xt:attributes="href xml/link"
			xt:content="xml/title">
				Title
		</a>
		<span
			xt:replace="xml/description">
				Description
		</span>
	</li>
	</xt:inc>
</ul>

Translates the enclosed text using the saf.I18n package and the global $intl object.

<xt:intl>Hello</xt:intl>

Loops through the specified list. Assigns each item to loop/i.

<xt:loop through="i php: range(1,25)">
	<p xt:content="loop/i/value">1</p>
</xt:loop>

Imports a global object into the XTE register, allowing it to be used in PHP expressions. The name attribute may also be a comma-separated list.

<xt:register name="page" />

Sets the value of object/foo to be the string "bar". The value attribute is an XTE expression with the default type string.

<xt:set name="foo" value="bar" />

Creates a new object in the XTE register. The new attribute is evaluated as a literal PHP string calling the class constructor and passing it the appropriate values.

<xt:set-obj	
	name="c"	
	new="Alt ('even', 'odd')"
/>

Calls a block and passes it a set of parameters. The mockup inside the tag is used for previewing when no Sitellite installation is available, allowing the template to still look as if the call to the block occurred. This same mockup inclusion can be done with the <xt:inc> tag as well, as shown in the example above.

<xt:show
	block="sidebar"
	title="Volunteers Wanted!"
	body="Come volunteer with
		us to help improve our
		project."
	link="/index/volunteer">
	<h3 class="sidebar">
		Block test</h3>
	<p class="sidebar">
		Block body...</p>
	<p align="right" class="sidebar">
	<a href="blocklink.html">
		Learn more
	</a>
	</p>
</xt:show>

The <xt:sql> command is a compound command using the <xt:sql>, <xt:bind>, <xt:sub>, and <xt:else> tags, which queries the database connection (the global $db object) with the specified query and returns the results formatted using the contents of the <xt:sub> tag like a block. The <xt:else> tag provides an alternate template block to display in case there are no results for the specified query. The <xt:bind> tags allow you to "bind" values to the query, which substitutes question marks in the query for the bound values. The query results are accessible in the through the "result" object path, and it's properties correspond to the list of columns returned by the query. Another powerful feature of this command is that you can automatically add paging capabilities to your query results (via the saf.Database.Pager package) just by adding the pager="yes" attribute to the <xt:sql> tag. Other pager-related attributes are limit, offsetvar, and totalquery. Limit defaults to 20, and offsetvar defaults to "offset" (accessible via cgi/offset) and the totalquery is used very seldom, only when a separate query can be used to find out the total number of results. Also note that the limit clause should be left out of the SQL query. In case of error, the message and information is accessible in the xt:else clause via result/error, result/err_sql, and result/err_bind/valuenumber.

<table
	<tr>
		<th>Last Name</th>
		<th>First Name</th>
		<th>Department</th>
	</tr>

	<xt:sql
		query="
			select * from employees
			where title = ?"
		pager="yes">

		<xt:bind value="cgi/title" ></xt>

		<xt:sub>
			<tr>
				<td
					xt:content="result/lastname">
						Smith
				</td>
				<td
					xt:content="result/firstname">
						Joe
				</td>
				<td
					xt:content="result/dept">
						Accounting
				</td>
			</tr>
		</xt:sub>

		<xt:else>
			<tr>
				<td colspan="3">
					No matches
				</td>
			</tr>
		</xt:else>

	</xt:sql>

</table>

These tags surround every XT template, helping to ensure that even if the contents of your template are not necessarily intended to be in XML format, it can still be valid XML.

<xt:tpl version="1.0"></xt:tpl>

Sets transformation directives which are used to transform the values of XTE paths who end in the specified name. The format of a transformation directive is the name of the tag, the type of transformation (as defined by the saf.Template.Transformation package), and the transformation call (if it's a func or function transformation). Multiple transformations are separated by a semicolon, and blank space for legibility is encouraged.

<xt:transform directives="
	foo, func, ucfirst (object.foo);
	bgcolor, alternate, even, odd
" />

Substitutes itself with the value of the XTE expression it names. The XTE expression has a default type of "path".

<xt:var name="xte path" ></xt>

This tag is used to insert the xml declaration at the beginning of the document. The attributes of this tag are the same as for the standard XML declaration itself, so there's nothing new to remember.

<xt:xmldecl version="1.0" encoding="utf-8" />

This creates an XML stylesheet declaration.

<xt:xmlstyle type="text/css" href="mystylesheet.css" />

Replaces the value of the current tag with the result of the given expression.

<p xt:content="cgi/foo">
	Temp value of foo
</p>

Replaces the entire tag with the result of the given expression.

<span xt:replace="cgi/foo">
	Temp value of foo
</span>

Replaces the specified attributes with the result of that expression. Multiple attributes may be separated by semicolons in the expression. An abbreviated command alias, xt:attrs, also exists.

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

Loop using the current tag as the wrapper for the loop. The expression syntax is the same as the full loop command. An alias xt:repeat also exists, so ZPT users will find XT even more familiar.

<table>
	<tr xt:loop="i php: range (1, 5)">
		<td xt:content="loop/i/number">1</td>
	</tr>
</table>

The ${expression} shorthand also allows you to include tags in other non-XT attributes. This is a shorthand for the xt:attributes example seen above, but comes at the sacrifice of previewability in some cases (ie. in this example, the path to the image will not resolve when previewing the template directly in a browser).

<img src="${site/prefix}/pix/foo.gif" />

In some XT tags, a value is being set that needs to be named. These include the <xt:loop> tag and the xt:attrs and xt:loop attributes. In these cases, the named value is prepended to the entire expression and separated from it by a space. As you can see, the value of each element of the expression "php: range ('a', 'z')" is assigned to the path loop/letter, since letter was specified in the initial assignment expression.

<xt:loop through="letter php: range ('a', 'z')">
	<p xt:content="loop/letter/value">a</p>
</xt:loop>

Conditions are evaluated like any other expression with a couple small differences. Instead of returning the value of the expression, a condition evaluates that value to be either true or false, and the body of that condition is either shown or not shown depending on that true or false value. A condition may also be negated using a "not" key word, which has the same syntax as an assignment name. For example:

<p xt:condition="php: true">
	This text will show because true always evaluates to true.
</p>

<p xt:condition="not php: true">
	This text will not show because it was negated with the "not" key word.
</p>

Each XTE expression has a default type associated with it that can be ommitted and XTE will automatically interpret the expression as beginning with that type. For example, the <xt:var name="xte path" ></xt> command has a default type of "path". Paths can also be abbreviated if they start with "object/", so the following are evaluated as equivalents:

<xt:var name="path: object/varname" ></xt>

<xt:var name="object/varname" ></xt>

<xt:var name="varname" ></xt>