Command Reference

<xt:tpl>

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

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

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

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

<xt:inc>

<xt:inc name="filename" />

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

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

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

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

<xt:register>

<xt:register name="page" />

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

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

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

<xt:set>

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

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

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

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

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

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

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

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

<xt:block>

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

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

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

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

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

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

<xt:condition>

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

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

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

The <xt:sql> command is a compount 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.

xt:content attribute

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

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

xt:replace attribute

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

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

xt:attributes attribute

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

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

xt:loop attribute

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

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.

Inline attribute expressions

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

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

Missing References: box, doctype, xmldecl, xmlstyle, form, cache, comment/note, code. For now, these are documented in other articles already.

Page 1: Design Goals
Page 2: A Complete Example
Page 3: Command Reference
Page 4: Troubleshooting

Home   More Templates Stories