Arbalo XSLT Framework

Overview and directory structure

Overview

Although all modern browsers understand XSLT stylesheets 1 , they are hardy ever used. This framework shall close the gap. Use it as a quarry to create your own XSLT stylesheets.

Motivation

Features

Build your own XSLT stylesheet

Examples

If this page is displayed as index.xml in the adress field of your browser, you are viewing an example of a presentation interpreted by the Arbalo framework. Click the right mouse button for seeing how much work it does for you!. If this page is displayed as index.html , however, you are viewing the compiled version. If you are looking into the source text you will find the generated sections, too.

The reference application of this framework is available interpreted 3 as well as compiled 4

Normally there is only one of both variants on the server, either the compiled or interpreted one.

Directory structure

Presentation Transformation
register.xml arbalo.xsl
index.xml
Doc1 .xml
Doc2 .xml
*.xml arbalo.css

In the directory of the presentation you find the document files  *.xml . They invoke arbalo.xsl which normally is located in the same directory. The navigation is generated from the table of content register.xml into the document files and the all-in-one document.

Each source document uses the CSS styles defined in arbalo.css . The link however is generated by XSLT stylesheet arbalo.xsl , which also uses the CSS styles.

Installation

Download

… and unpack arbalo.zip  into a directory arbalo .

How to start a presentation of your own

  1. Copy the content of this directory (how-to-do presentation) into a new one.
  2. Replace index.xml  by your own content.
  3. Use your index.xml  as a template for creating other pages of your own (e. g. myPage.xml ). In the page just created, change its name name="DC.Source" content=myPage.xml" 1
  4. Reference your pages in register.xml  using links like <a href="myPage">My Page</a> . The file must not  have an extension.
  5. Adapt arbalo.xsl, arbalo.css  .
  6. Delete remaining files of the how-to-do presentation.

Examples

More to this issue see in chapter Slide file .

Imprint, Disclaimer

Responsible author

Jürgen Regel , Hildesheim, May 2007 (release 1.0) / July 2011 (release 2.0)

Usage of the software and the documentation

The software may be used freely according to the GNU General Public License 1 . For explanation see [en] GNU General Public Licence .

Source document

Layout of  register.xml

The register file register.xml  has links to the XML source document files of the presentation in the directory where it belongs to. It assigns source documents ( *.xml ) to chapters. It defines the outline of the presentation. The headings of level 1 (common header of the presentation) and of level 2 (header of a source document file) are defined here. It also contains code of the XHTML head  section that is common to all source files.

register.xml has the following layout:

Processing instructions, name spaces, language

			
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="arbalo.xsl" type="text/xsl"?>
<html
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:a="http://sourceforge.net/projects/arbalo/"
	lang="en"
	a:filename="nameOfThisFile"
	…
 		     
		

lang=…  defines the language of the presentation, here en = English.

The attribute a:filename  is not necessary in the register file, but should have the value register.xml  if present.

			
  <head>
    <meta name="robots"
          content="index,follow" />
    <meta name="author"
          content="Jürgen Martin Regel" />
    <link rel="shortcut icon"
          href="favicon.ico" />
  </head>
 			
		

The head section head is used for the overall document and for each single document file. The other source document files *.xml  need not have a head section. If they have, their head  section is mixed with the common head section of register.xml .

body

			
	<body>
		<h1>Arbalo XSLT Framework</h1>
		<section class="overview">
			<h1>Overview and directory structure</h1>
			<a href="index"> Overview</a>
			<a href="Structure">Directory structure</a>
			…
		</section>
		<section class="document">
			<h1>Source document</h1>
			<a href="RegisterFile">Layout of <code>register.xml</code></a>
			<a href="DocumentFile">Layout of document file (e. g. <code>index.xml</code>)</a>
			…
		</section>
		…
	</body>
</html>
     		
		

The presentation is subdivided by nested chapters (we use the new XHTML tag section  for this purpose. Each section may contain subsections. A section should start whith a h1  heading. The body  may be regarded as a section at root level. Its h1  is used as the common header of the presentation.

The text of the link, that is everything between <a> and </a>   , is rendered as table of contents and as h2  heading of the particular document file.

If the URL is a simple filename without path and extension, it is recognized as an link to a document file of this presentation. The extension is inserted automatically by the XSLT style sheet during transformation depending on interpretation or compilation.

In order to see an example please follow the link register and have the source text displayed.

Layout of document file (e. g.  index.xml )

A source document file should contain navigation as little as possible. It should have the extension .xml and its name should not be equal to register.xml ). In each directory such a file named index.xml should exist.

This is its layout:

Processing instruction, name space, language

			
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="arbalo.xsl" type="text/xsl"?>
<html
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:a="http://sourceforge.net/projects/arbalo/"
	lang="en"
	a:filename="nameOfThisFile"
	…
 		     
		

The beginning of the file is the same as for RegisterFile .

The attribute a:filename="…"  holds the base file name of this source document file. Path and extension are allowed but ignored. Unfortunately this is necessary because it is not possible in XSLT 1.0 to address the name of the file being processed. Alternatively the file name may be specified in a meta tag according to Dublin-Core in head , see below. An SCM tool may insert the name of the sourcefile by keyword expansion.

<head>…</head>

The head section of the output document is mixed from the head section of the register file  and from that of the current document file, so it is optional.

The filename of the current file may be specified in a meta tag according to http://www.dublincore.org/  (instead of using a:filename ):

			
<head>
	<meta name="DC.Source"
		content="$Header: //depot/xxx/Arbalo2/docs/en/DocumentFile.xml#2 " />
</head>
			
		

The example shows how a SCM tool can insert the filename automatically for you.

Directives  that do not generate output immediately (like a:default ) should be placed here.

<body>…</body>

The body consists of plain XHTML and directives . In links to other document files of the same presentation the name extension .xml (in interpretation mode) or .html (in compilation mode) is omitted.

Directives

In the document source you can control the Arbalo framework by directives . They are tags of a separate namespace xmlns:a="http://sourceforge.net/projects/arbalo/" . As a convention, we use a:  as its prefix.

The directives are omitted in the output document.

a:include

By the a:include  directive an element of any XML file can be included into the document. After inclusion the templates are applied. The following attributes should be specified:

Parameter attribute Meaning
src URL (file name) of the file that contains the element to be inserted. If this parameter is missing, a a:default directive  is looked for and its parameter is used. If the attribute is missing in a:include   and a:default , the current file is used. By src=""  you can enforce to use the current file even if there is a a:default  directive.
refid Value of the attribute id  of the element to be included. If the attribute is missing, the complete document is included.
Example aFile.xml
<a:include src="anotherFile.xml" refid="anElement"/>
Example anotherFile.xml
<table id="anElement">…</table>

Example: From another document file of the presentation x.xml , a table with the id="x-table"  is to be inserted into the current document file y.xml .

The a:include  directive may be used to implement a feed reader: <a:include src="feed.atom"/> . There is a template matching <f:feed xmlns:f="http://www.w3.org/2005/Atom"> . A feeds is normally not embedded in the HTML source but is contained in a file of its own. Because the complete feed is to be included, the attribute refid  is omitted.

a:default

If multiple elements of the same soure document file are included by the a:include directive ,  is may be specified only once in an a:default  directive. Example: <a:default src="anotherFile.xml"/>

The attribute src of the a:include  directive overwrites the corresponding one of the a:default  directive. If it is empty but exists ( src="" ), the current file is used for inclusion.

a:ref

Using this directive footnotes 1 are created. Everything located between the tags <a:ref>…</a:ref>   is rendered at the location of the directive a:references . If it is missing, it is inserted automatically at the end of the document.

						
<html>
	…
	<body>
		…
		<p>
			See the reference application of this framework
			<a:ref>
				<a href="http://zocher-regel.gmxhome.de/ArbaloSchlacht/index.xml"/>
				Reference application
				<cite>Battle at  Arbalo</cite>
				. Use extension <code>.html</code> instead of <code>.xml</code>
				for the compiled version.
			</a:ref>.
		</p>
		…
		<h3>External links</h3>
		<a:references />
	</body>
</html>
					
					

Footnotes can be grouped Group 1 , by giving a:ref  an attribute group  with the name of the group. There should be a <a:references group="xxx"/>  for each group; see next paragraph.

a:references

<a:references/>  marks the place where the footnotes generated by a:ref  are rendered. If this directive is missing, the Arbalo framework will generate them when needed at the end of this document file.

Mulitple a:references  directives may exist in a slilde, which differ in the attribute group : <a:references group="xxx"/> <a:references group="yyy"/>

In this case the footnotes should contain one of the existing groups as attribute: <a:ref group="xxx">…</a:ref> <a:ref group="yyy">…</a:ref>

Coaction of a:ref, a:references, a:include

Even inside a footnote ( <a:ref><a:include …/>…</a:ref> ) the a:include directive can be used to avoid redundancy. As an example, you can a:include a link to a book from a bibliography into multiple footnotes pointing to different pages of the book.

a:bibliography

This directive may be placed in any source document file. It generates a list of all <cite>Author: Book</cite>  of all source document files named in register.xml .

a:counter

How this directive works, demonstrates this example:

		
<a:counter
	name="x" (opt)
	value="1" (opt)
	increment="1" (opt)
	count="true" (opt)
	diff="0" (opt)
	display="true" (opt)
/>
<table>
	<tr><td><a:counter value="1" increment="5"/></td></tr>
	<tr><td><a:counter/></td></tr>
	<tr><td><a:counter count="false"/></td></tr>
	<tr><td><a:counter count="false" diff="-3"/></td></tr>
</table>		
		
					
1
2
2
-1

If more than one counter is used in the same source document, they should be named.

a:sitemap

This directive may be placed into any source document file and generated a sitemap from the register.xml .

<a:sitemap/>

Arbalo XSLT Framework

Ungrouped footnotes

Grouped footnotes

Translation

Translation by translation server

If the stylesheet parameter  feat-translator   is switched on, a little form is generated   where a language of choice can be typed in.  After pushing the button the translation server  translates the source document automatically under following preconditions:

To choose your favorite web translator, you have to adapt the template translator  in arbalo.xsl .

Translation of generated phrases

The Arbalo processor recognizes the language of the document by the attributes lang, xml:lang  in the html-Element and tries to translate generated phrases (e. g. Next page ) ) into this language (e. g. Nächste Seite  in case of German). The template tranlate  of arbalo.xsl    acts as dictionary. Some languages ( de en fr la ) are supported yet. If needed, the template may be augmented to support additional languages. If the language is not supported, English is used as default.

Rules of thumb

  1. Use XHTML  . Only if HTML conforms to the stringent rules of XML it can be transformed by XSLT.
  2. Name extensions
    • *.xml  for XHTML sources. So the file is parsed as XML and not as HTML and an XSLT style sheet can be invoked from it.
    • *.html for XHTML output.
    • *.xsl  for XSLT style sheets.
    • *.css  für CSS style sheets.
  3. Unicode (UTF-8, UTF-16).  Using this encoding, there is no need for entities like &euro; or &#x20ac; and in the editor the texts look similar like in the browser.
    • Only use editors supporting UTF-8 or UTF-16.
    • Use fonts that can render as much Unicode letters as possible, e. g. specify in the CSS style sheet: font-family:Arial Unicode MS,Lucida Sans Unicode,sans-serif; But ensure that the font is available on the reader's computer.
  4. Format XML source document. A good XML editor formats your XML document so that it is readable. Characters should not be replaced by entities and the encoding should remain unchanged. But be careful when formatting XSLT.
  5. Test with at least two browsers. . The page must be rendered without errors in both browsers and look very similar.
  6. Short name space prefixes in the XSLT file.
    • Use no prefix for XHTML tags that are copied to the XHTML output.
    • Use prefix h  for XPATH expressions that reference XHTML of the source document. Example: <h1><s:value-of select="/h:html/h:head/h:title"/></h1>
    • To make XSLT more readable, use the short prefix s:  for XSLT commands. Another often used prefix is xsl: .
  7. If whitespace should be retained by formatting, use the non-breaking space   &#xa0; , which also may be entered by [ALT]+160  on the numeric keypad, if it looks different from normal space in the editor.

Adaption of XSLT

Features

You may modify the XSLT stylesheet arbalo.xsl by editing or importing it. In simple cases it is not necessary to override templates: Adapt the param s at its beginning instead.

If you do not want to modify arbalo.xsl , you can set the param s in a stylesheet of your own (e. g. my.xsl ) that import s arbalo.xsl :

			
<s:stylesheet xmlns:s="http://www.w3.org/1999/XSL/Transform">
	<s:import href="arbalo.xsl"/>
	<s:param name="feat-a-name-title" select="false()" />
</s:stylesheet>

		

my.xsl is invoked in your *.xml  files instead of arbalo.xsl  .

The value of a parameter should be an XPATH expression . In most instances it is a logical value B (e. g. "true()", "1"; "false()", "0", "$feat-1 and not($feat-2)"), an integer I , a string S or a node set N . 1

Parameters can be passed to a compiler like Xalan or Saxon. 2

On the next page the parameters are listed.

Parameters

Parameter types (legend)

Type Meaning
B Boolean, logical value true() false()
N Node, XML-element
I Integer -1 0 1 2 …
S Character string 'abc'

Parameters

Namespace xmlns:s="http://www.w3.org/1999/XSL/Transform" .

Name Type Meaning Example (= default)
css-stylesheet S Path and name of the CSS-stylesheet relatively to the directory of the presentation. If the parameter is omitted, a file named arbalo.css is expected there. <s:param name="css-stylesheet" select="'arbalo.css'" />
feat-a-name-title B Show the name of every anchor (target of a link) in a small window when the mouse is positioned over it. <s:param name="feat-a-name-title" select="true()" />
feat-generate-anchor-from-content B For every heading h3, h4, …  an anchor is generated automatically. If this feature has been switched on, the name of the anchor equals the heading or its title, if there is one. (Spaces have been replaced by _). Otherwise the name of the anchor is generated by the function generate-id . <s:param name="feat-generate-anchor-from-content" select="true()" />
feat-generator B Insert a meta statement into the HTML file that it has been generated by Arbalo. <s:param name="feat-generator" select="true()" />
feat-geo-bing-maps B From each Microformat Geo  generate a link to Bing Maps. <s:param name="feat-geo-bing-maps" select="true()" />
feat-geo-hack B From each Microformat Geo  generate a link to GeoHack. <s:param name="feat-geo-hack" select="true()" />
feat-geo-google-maps B From each Microformat Geo  generate a link to Google Maps. <s:param name="feat-geo-google-maps" select="true()" />
feat-geo-mapquest B From each Microformat Geo  generate a link to Map Quest. <s:param name="feat-geo-mapquest" select="true()" />
feat-geo-yahoo-maps B From each Microformat Geo  generated a link to Yahoo Maps. <s:param name="feat-geo-yahoo-maps" select="true()" />
feat-hreflang B Show the language of the page the link points to (value of attribute hreflang ). <s:param name="feat-hreflang" select="true()" />
feat-hreflang-autodetect B Try to determine the language of the target document (even if attribute hreflang  is missing). <s:param name="feat-hreflang-autodetect" select="true()" />
feat-img-alt-title B In element img  has no attribute title , generate one using the content of attribute alt . The title is shown in a small window, when the mouse is located over the image. <s:param name="feat-img-alt-title" select="true()" />
feat-link-img B Generate link from img clause to graphic file. <s:param name="feat-link-img" select="false()" />
feat-link-page-register B Generate link to all-in-one. <s:param name="feat-link-page-register" select="false()" />
feat-rel-tag B Generate a rel="tag"  for a Wikipedia keyword. <s:param name="feat-rel-tag" select="false()" />
feat-toc-chapters B Generate navigation area for chapters (document files) of the presentation. <s:param name="feat-toc-chapters" select="true()" />
feat-toc-local B Generate links to headings of the current document file at top and bottom. <s:param name="feat-toc-local" select="true()" />
feat-toc-tabs B Generate tabs for the main chapters of the presentation. <s:param name="feat-toc-tabs" select="true()" />
feat-translator B Generate a form to translate the document file into a language of choice, which is only possible if the presentation has been compiled (extension is html) and if the translation server can access it. <s:param name="feat-translate" select="true()" />
filename S The name of the source document. Necessary if the name is not extracted from <meta name="DC.Source" content="…/myPage.xml"]>]</code> </td> <td> <code> <![CDATA[ <s:param name="filename" select="''" /> <s:param name="feat-translate" select="true()" />
header S Name of a file that is inserted as head (for corporate identity, optional). <s:param name="header" select="''" />
log-err-level I Minimum error level for writing messages to the console, when the file is compiled. 0 = Debug, 1 = Info, 2 = Warn, 3 = Error. See Logging , too. <s:param name="log-err-level" select="1" />
log-out-level I Minimum error level for writing messages to the output HTML. 0 = Debug, 1 = Info, 2 = Warn, 3 = Error. See Logging , too. <s:param name="log-out-level" select="3" />
output-encoding S Encoding of the HTML output. UTF-8 is recommended. <s:param name="output-encoding" select="'UTF-8'" />
parent S Link to a superordinate directory. <s:param name="parent" select="'..'" />
refresh-seconds I If there is a link with id="refresh", then it will be invoked after the number of seconds given. <s:param name="refresh-seconds" select="5" />
register S Name of the register file (= Masterdocument) without path and name extension. <s:param name="register" select="'register'" />
replace-svg-object S Since some browsers do not support SVG, generating of SVG objects can be switched off. The SVG object element is replaced by its child element – normally a simple graphic. Values 'img', 'embed', 'iframe', 'object', 'kernel'. <s:param name="replace-svg-object" select="'kernel'" />
searchengine S URL of favored search machine. <s:param name="searchengine" select="'http://www.google.com/search'" />
serverbase S Path to the directory of the presentation on the HTTP-Server. <s:param name="serverbase" select="'http://home.arcor.de/juergen.regel/Arbalo/docs/de/'" />
target-ext S xml , when interpreted, else html . <s:param name="target-ext" select="'xml'" />

Logging

In order to assist you in developing XSLT code, the framework supports error logging which may be used in the XSLT stylesheet arbalo.xsl  itself or in stylesheets that import it.

Levels of error and info messages

Level number Level Meaning
0 debug Output for tracing of the program flow.
1 info Information (less detailed than debug).
2 warn Warnings (possible errors).
3 error Error.
4 fatal Fatal error, processing stops.

Whereto are the messages written?

Messages are output …

By stylesheet parameters log-err-level, log-out-level  the minimum error level is specified for messages to out  or err .

Example of calling

Here an example how to call the logging template:

						
<s:call-template name="log">
	<s:with-param name="msg">A warning message</s:with-param>
	<s:with-param name="level" select="2"/>
</s:call-template>
						
					

The template log  compares the value of the call parameter level  with the values of the stylesheet parameters log-err-level, log-out-level .

Call parameters of the logging template log

Call parameter Purpose Default value Meaning of this value
msg Message text Necessary parameter
level Error level of the message 3 Error

Tables of content

Headings

This directory contains links to all headings h3, h4, … of a document file.

Class (CSS) arbalo-toc-local
Parameter to enable this feature feat-toc-local

Chapters (slilde files)

Class (CSS) arbalo-toc-chapters
Parameter to enable this feature feat-toc-chapters

The directory of chapters lists HIER WARICH die Foliendateien der Präsentation. Wenn die Kapitel in Unterkapitel untergliedert sind (siehe Registerdatei ), können Teile ⊞ ausgeblendet oder ⊟ eingeblendet sein.

Tabs

The highest directory level may be rendered by tabs. You see the tabs of this presentation above. A tab and the files belonging to it may have a background-color of its own. Notice that a link to a document file (e. g. Overview ) has its background-color, too.

Class (CSS) arbalo-toc-tabs
Parameter to enable this feature feat-toc-tabs
Class (CSS) arbalo-toc-tabs
Parameter to enable this feature feat-toc-tabs

CSS stylesheet

The transformation program arbalo.xsl generates a link to a CSS stylesheet arbalo.css :

						
<head>			
	<link type="text/css" rel="stylesheet" href="arbalo.css" />
</head>	
						
					

You can name the CSS stylesheet using a parameter .

Classes beginning with arbalo- are generated by the transformation program into the output html:

			
/*
 * begin of classes generated by arbalo XSLT style sheet
 */

/*
 * table of contents for chapters
 */
div.arbalo-toc-chapters {
	background-color: beige;
	float: right;
	padding: 0.5em;
}

div.arbalo-toc-chapters p {
	margin-top: 1px;
	margin-bottom: 1px;
	text-indent: 0em;
}

div.arbalo-toc-chapters p.arbalo-current {
	border-width: thin;
	border-color: darkred;
	border-style: dotted;
}

div.arbalo-toc-chapters h2,h3,h4,h5,h6 {
	margin-bottom: 0em;
}

/*
 * table of contents for headings on this page
 */

div.arbalo-toc-local {
}

/*
 * table of contents for main chapters (rendered as tabs)
 */

table.arbalo-toc-tabs {
	background-color: transparent;
	border-style: none;
	margin-top: 1ex;
	width: 67%;
}

table.arbalo-toc-tabs td {
	padding: 0.5em;
	border-style: solid;
	border-width: thin;
}

table.arbalo-toc-tabs td.arbalo-current {
	border-bottom-style: none;
}

table.arbalo-toc-tabs td.arbalo-empty {
	border-style: none;
	border-bottom-style: solid;
	padding: 0.5em;
}

/* natural language indicator (en, de, fr, …) */
.arbalo-language {
	color: white;
	background-color: blue;
	font-family: monospace;
	margin-right: 0.3em;
}

/* e-mail address */ 
.arbalo-mail {
	background-color: lightsteelblue;
}

/* special symbol for links */
.arbalo-marker {
	width: 1em;
	margin-right: 0.3em;
}

/* link to subdirectory */
.arbalo-subdir {
	background-color: lightblue;
}

/*
 * end of classes generated by arbalo XSLT style sheet
 */
			
		

Microformat Geo

A geo microformat is a section of normed HTML containing coordinates that can be shown by an Internet map service. Here an example:

			
<div class="geo">
	Position of Hildesheim, Germany
	<abbr
		class="latitude"
		title="52.1671"
	>
		52° 10' 1.77" N
	</abbr>
	<abbr
		class="longitude"
		title="9.90924"
	>
		9° 54' 33.25" O
	</abbr>
</div>

		

Arbalo generates links to common map services in the internet from this:

Position of Hildesheim 52° 10' 1.77" N 9° 54' 33.25" O Bing Maps GeoHack Google Maps Mapquest Yahoo Maps

Click on the generated links GM (Google Maps), MQ (MapQuest) und YM (Yahoo-Maps) to see the place on a map.

This feature is enabled by the parameters feat-geo-google-maps, feat-geo-yahoo-maps, feat-geo-mapquest .

For more information see Wikipedia: [en] Geo (microformat)

Feed

There is a template matching <f:feed xmlns:f="http://www.w3.org/2005/Atom"> . The absolute addresses of the links are converted to relative ones by the framework. Normally the feed is not embedded into the HTML source but contained in a file of its own. It should be located in the same directory as the presentation and may be included by using the a:include directive .