XsltCMS :: how to create templates

How to create templates for XsltCMS

Abstract

Template allows you to mix some HTML code (aspect of your website) with data (content of your website). You, as the administrator, have to build this template or these templates.

Create one or some XSL files in the yourwebsite/create/ website/templates/ folder
Use them by configuring writers in yourwebsite/create/ website/config.xml

1. How does it work ?

XSL means "XML Stylesheet Language" (in XSLT, T stands for "Transformation").

You can create some XSL files in the folder yourwebsite/create/website/templates/. Generally, each one is corresponding to a writer (in yourwebsite/create/ website/config.xml) belonging to a type of item.

Example : there are "pages" and "directories" in your website. You will probably build this files : page.xsl and directory.xsl.

In these XSL files will appear the layout of your documents, and some tags to find and show properties of your items.

Each time a item is saved, it is done in yourwebsite/create/ website/data/current.xml. This file contains all the data of your website.

Then each writer for the type of your item, if any exists, is used (see how to install and administrate).

The XSL template and current.xml will be mixed to generate a file (for example, a HTML file), that will belong to the public part of your website.

2. Summary of XSLT

You should read this while having a .XSL file from one of the demo site open in front of you. Open also yourwebsite/create/ website/data/current.xml. You should know how XML works.

A .XSL file is a .XML file ; the first line contains usual declarations (version, encoding).

The main tag is a stylesheet tag, belonging to this namespace : http://www.w3.org/ 1999/XSL/Transform. The usual method is to associate a prefix (xsl) with this namespace, and then use it everywhere (xsl:stylesheet, xsl:template, ...).

Then you could use an output tag , indicating that you want some special content wrote into the final document (used for HTML generation, see samples in demo templates).

Some param tags can be wrote after that (see below - "Special parameters").

Then, at last, appears the main tags : template

2.1 Template tags

Each template tag is describing a "template". A template is a part of the final output, with some slots to be filled with source data (see value-of tag below).

The content of this template will be copied in the final document 0, 1 or more times.

It can contain an attribute match indicating in which case this template will be applied. The value of this attribute use XPath (see below).

2.2 XPath

XPath is a language associated with XML. It permit to indicate/search an information in a XML document.

It is a single string, begining with :

/ : searching from the root of the document
// : searching from anywhere
something else : searching from the current position

Then follows a serie of element names, separated with /. For example /items/item/property will search each property elements inside item elements inside items elements, from the root of the document.

The final word can be an element, as above, or an attribute. Attribute names are prefixed with @ (e.g. //item/@name).

You can also put filter, to select data, in [ ]. /items/item[@id=1] will return the item with the id "1".

There are other possibilities in XPath, see tutorials belows.

2.3 Apply-template tag

This tag will permit to apply again all the templates of the document. They are taken from top to bottom until one corresponding with the current data is found (using match attribute for that, see above).

This tag can contain a select attribute, in XPath, indicating in which element the search of a template should be applied.

You can consider that at the start of the XSL transformation of the document, is implicitly applied, starting the processing.

2.4 Value-of tag

This is the tag writing content of the document into the output. It contain an XPath select attribute in order to indicate what to write.

It can contains a disable-output-escaping="yes" attribute. If not, tags inside the source (e.g. HTML data in items) will be escaped (transformed to make them appear).

2.5 Sample

Here is a simple sample,that will create a text file with all the ids of your website items :

‹?xml version = "1.0" encoding = "utf8"?›
‹xsl:stylesheet version = "1.0" xmlns:xsl = "http://www.w3.org/1999/ XSL/Transform"›
‹xsl:template match = "/items"›The ids : ‹/xsl:apply-templates select = "item"›‹/xsl:template›
‹xsl:template match = "item"› , ‹/xsl:value-of select = "@id"›‹/xsl:template›
‹/xsl:stylesheet>

2.5 If tag

Things between ‹xsl:if test=".."> and ‹/xsl:if› are used if the condition in the test attribute is resolved to true.

This condition can contains usual comparators. E.g. ‹xsl:if test="@id=3">ok‹/xsl:if› will write "ok" if the id attribute of the current element as a value of 3.

2.6 Include/import tag

Including a template inside another one is possible using ‹xsl:include href="..">. Then every templates defined in included template are available in the other one.

This is often done in examples to include "nl2br.inc.xsl" (transforming line feeds from "text" property into ‹br />.

2.7 More tags

There are some more tags available in XSL, to do loops (instead of apply-templates), copies, sorting, etc.

3. Special parameters

3.1 XSL param tags

You can use some ‹xsl:param name="..."> tags to indicate that you will use some of the parameters put before into memory by XsltCMS :

id : id of the current item ; you will use it, as it is the only solution to know what is the current item processed
title : title (generated using configuration) of the current item
filename : filename of the current file generated
date : date now (in your language)
time : time now (in your language)
datetime : date and time now (in your language)
server_name : current name of the server (without http://)
server_addr : current ip address of the server (without http://)

You can then use this param anywhere using {...}.

For example put ‹xsl:param name="date"/› in the begining, then {date} inside a template.

3.2 Preprocessing

A transparent preprocessing is done on data (current.xml) before used with your templates. Is added :

filename attribute in ‹item› : filename of this item when processed with its first writer (if it exists).

3.3 About "hidden"

Content can be hidden (checkbox "hidden" in item edition).

This should be used in your template. Here is a sample code from minimal demo :

‹xsl:template match = "item[@type='Page']" mode = "menu" >
‹xsl:if test = "@hidden != 'true'">
‹a>
‹xsl:attribute name = "href" >‹/xsl:attribute >
‹xsl:value-of select = "property[@name = 'Title']" />
‹/a> ‹br />
‹/xsl:if>
‹/xsl:template >

4. Dynamic pages (blog, forum...)

It is possible to make some page that can be modified by visitors (e.g. comments at the end of an article).

Only creation of data is possible.

You must create a datatype corresponding to the data that can be added. Then, in some page, build a HTML form that will be able to imply the creation of item :

the create/ section must be present and working on the webserver
action attribute of the ‹form> must lead to create/
there must be a hidden input with name "action" and value "dynamic.send"
there must be a hidden input with name "type" and value your item type created
there must be a hidden input with name "parent_id" and value the location for the new item
there must be a hidden input with name "redirect_url" and value the URL reached by this form
there can be a hidden input with name "hidden" and value "no" specifying that the item must not be created hidden
there must be some input corresponding to the properties of your new item

Here is an example that you can put into a template, corresponding to a item with type "Comment" :

‹form action = "create/" method = "post">
‹h3>Add your comments‹/h3>
‹input type = "hidden" name = "action" value="dynamic.send" />
‹input type = "hidden" name = "parent_id" >‹xsl:attribute name = "value">‹xsl:value-of select = "@id" />‹/xsl:attribute >‹/input>
‹input type = "hidden" name = "redirect_url" >‹xsl:attribute name = "value"> ../‹xsl:value-of select = "substring-after( @filename, 'pages/')" />‹/xsl:attribute >‹/input>
‹input type = "hidden" name = "type" value = "Comment" />
‹p>Title : ‹input name = "Title" />‹/p>
‹p>Text : ‹textarea name = "Text">‹/textarea>‹/p>
‹p>‹input type = "submit" />‹/p>
‹/form>

5. More

You can find a lot of tutorials about XML, XPath, XSLT everywhere :

You should edit your XSLT with a helpful editor. There are plenty of them, free or not.

About this document

Document base url : http://xsltcms.org/ how_to_create_template.html

Version : 070825

Author : Askywhale