Using XslBricks

User's Guide

Introduction

What is XslBricks for?

XslBricks is an XSLT/XSL-FO template library that serves three main purposes:

  1. Create simple Serna XSL stylesheets for arbitrary XML documents very easy and rapidly (from 5 to 30 minutes).

  2. XSL stylesheet that uses XslBricks produces not only XSL-FO, but also HTML.

  3. XslBricks contains popular, reusable XSL modules, e.g. XHTML, CALS tables, etc.

XslBricks provides a set of templates that cover most popular set of decorations that HTML has. Therefore it has templates like: div, para, pre, h1, etc. Also it has modules for drawing images, lists and tables.

What XslBricks is not?

  1. XslBricks is not the ultimate XSL library to build tricky stylesheets. It is good for quick and easy start-up. If you want to create a sophisticated template, create your own in place of simple XslBrick.

  2. XslBricks is not the panacea to create mighty stylesheets for both XSL-FO and HTML. However, it works fine for simple use cases.

How does it work?

XslBricks idea is simple. There are two XSL libraries (backends), one for XSL-FO generation, and another one is for HTML. Each of the backends contains the same list of templates. Every template is called by its name. Here is an example:

Suppose we want element emphasis to be rendered as bold inline. In our stylesheet myspecs.xsl we write a template:

<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format">

  <xsl:template match="emphasis">
    <xsl:call-template name="bold.inline"/>
  </xsl:template>

</xsl:stylesheet>

Now, if we want to generate XSL-FO, we include the XSL-FO backend:

<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <xsl:include href="path_to_xsl_bricks/fo/fo.xsl"/>

  <xsl:template match="emphasis">
    <xsl:call-template name="bold.inline"/>
  </xsl:template>

</xsl:stylesheet>

That's all! Now, you can open your document in Serna with this stylesheet, and emphasis elements will be shown bold, while all others will be rendered with default templates. The default templates, page setup templates, default parameters and all other things are included with fo.xsl from XSL-FO backend. If you want other elements to look pretty ASAP, just use other XslBricks templates!

Is There a Working Example?

Find a more detailed example you in sernaInstallationPath/examples/xslbricks. Try to open example.xml with myfoexample.xsl stylesheet, or produce HTML with myhtmlexample.xsl.

What's Next?

Once you have a simple stylesheet for your documents, you will probably want more complexity for your stylesheet. For example, section numbering, sophisticated itemized lists, etc. You can either add complexity within your stylesheet, or replace simple XslBrick with your code one after another.

It may happen that finally you will not use anything from XslBricks. But it allowed you to make quickly something that really works.

Making XslBricks Stylesheets

Usually you want to organize your XslBricks stylesheet in three files:

  1. Main specification module

    This file contains all the match rules, applied to your document. The templates there must be invariant, e.g. work for both XSL-FO and HTML backends, which is achieved by calling XslBricks templates that make the decoration job.

    For example, myspecs.xsl:

    <xsl:stylesheet version="1.0"
                    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format">
    
      <xsl:strip-space elements="*"/>
    
      <xsl:template match="emphasis">
        <xsl:call-template name="bold.inline"/>
      </xsl:template>
    
      <xsl:template match="section">
        <xsl:call-template name="div"/>
      </xsl:template>
    
    </xsl:stylesheet>

    These specifications say only that emphasis will be rendered as bold inline area, and section as a plain block.

  2. XSL-FO driver module

    This is a very small file that includes the main specification module, and imports XSL-FO backend module. Default XSL-FO parameters or templates may also be overridden here. For example, myfodriver.xsl:

    <xsl:stylesheet version="1.0"
                    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format">
    
      <xsl:import href="path_to_xsl_bricks/fo/fo.xsl"/>
      <xsl:include href="myspec.xsl"/>
    
    </xsl:stylesheet>
  3. HTML driver module

    Just as XSL-FO driver module, a very small file that includes the main specification module, and imports HTML backend module. Default HTML parameters or templates may also be overridden here. For example, myhtmldriver.xsl:

    <xsl:stylesheet version="1.0"
                    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format">
    
      <xsl:import href="path_to_xsl_bricks/html/html.xsl"/>
      <xsl:include href="myspec.xsl"/>
    
    </xsl:stylesheet>

Now you can:

  • Open your document with myspec.xsl stylesheet in Serna.

  • Produce PDF with your favourite XSL-FO formatter, e.g. with FOP:

    fop.sh -xml mydocument.xml -xsl myfodriver.xsl -pdf mydocument.pdf
  • Produce HTML with your favourite XSLT processor, e.g with Saxon:

    saxon.sh mydocument.xml myhtmldriver.xsl mydocument.html

List of all available XslBricks templates see in Reference Guide.

Reference Guide

XslBricks Files

There are two general hub files that include all the FO and HTML backends: fo/fo.xsl, and html/html.xsl. Include this or the other file to your specifications for generating FO or HTML output.

Each (FO and HTML) backends introduce the same set of names and semantics of templates. However parameters for FO and HTML backends significantly differ.

Some files from both backends my be reused as a standalone module. The description of each file in both backends follow below:

  • parameters.xsl

    Parameters that drive the area presentation and minor stylesheet behaviour.

  • layoutsetup.xsl

    Set up a very simple page sequence for FO, and miscellaneous head/meta content for HTML.

  • default-elements.xsl

    A default rule for showing elements that were not provided explicit templates. In particular, this helps to show documents with XslBricks stylesheet without any user-defined templates.

  • inlines.xsl

    Inline area generating templates.

  • blocks.xsl

    Block area generating templates.

  • lists.xsl

    Templates for drawing simple numbered and itemized lists.

  • simple-tables.xsl

    Trivial table model templates.

  • xhtml-tables.xsl

    This module is not included to fo/fo.xsl and html/html.xsl. You can reuse this module if your document supports XHTML table model.

The following modules constitute FO backend, and absent in HTML templates:

  • page-sizes.xsl

    Easy switch for page height and width, determined with well-known page format identifiers.

  • common.xsl

    Templates for processing common attributes.

Inline Area Templates (inlines.xsl)

inline

generate plain inline area

Parameters
Name Default Notes
content empty node-set nodes for canned context

italic.inline

generate inline area similarly to i HTML tag.

Parameters
Name Default Notes
content empty node-set nodes for canned context

bold.inline

generate inline area similarly to b HTML tag.

Parameters
Name Default Notes
content empty node-set nodes for canned context

bold-italic.inline

generate bold-weight and italic-style inline area.

Parameters
Name Default Notes
content empty node-set nodes for canned context

blue-underline.inline

generate blue underlined inline area (similar to "hyper-links" in HTML browsers).

Parameters
Name Default Notes
content empty node-set nodes for canned context

monospace.inline

generate monospace font inline area (similar to HTML code).

Parameters
Name Default Notes
content empty node-set nodes for canned context

small.inline

generate smaller font inline area (similar to HTML small).

Parameters
Name Default Notes
content empty node-set nodes for canned context

big.inline

generate larger font inline area (similar to HTML big).

Parameters
Name Default Notes
content empty node-set nodes for canned context

strike.inline

generate strike-through inline area (similar to HTML strike).

Parameters
Name Default Notes
content empty node-set nodes for canned context

underline.inline

generate underlined inline area (similar to HTML u).

Parameters
Name Default Notes
content empty node-set nodes for canned context

super.inline

generate superscripted inline area (similar to HTML sup).

Parameters
Name Default Notes
content empty node-set nodes for canned context

sub.inline

generate subscripted inline area (similar to HTML sub).

Parameters
Name Default Notes
content empty node-set nodes for canned context

quote.inline

generate quoted inline area (similar to HTML q).

Parameters
Name Default Notes
content empty node-set nodes for canned context

image.inline

generate inline image (similar inline HTML img).

Parameters
Name Default Notes
url empty string a string with image url value

inline.decoration

generate arbitrary inline area.

Parameters
Name Default Notes
content empty node-set nodes for canned context
background-color empty string background color name/code
color empty string font color name/code
vertical empty string baseline shift value
font-{style|family|weight|size} empty string respective font properties
text-decoration empty string text decoration value (e.g. underline)
border-width 0 border width value
border-color black border color value
border-style solid border style value
padding empty-string padding value

Block-area Templates (blocks.xsl)

para

generate paragraph (similar to HTML p).

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)

pre

generate pre-formatted block (similar to HTML pre).

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)

div

generate a block (similar to HTML div).

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)
background-color empty-string background color code/name

para.decoration

generate a paragraph block with arbitrary properties.

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)
text-align empty string text align value
background-color empty-string background color code/name
color empty string font color name/code
font-{style|family|weight|size} empty string respective font properties
text-decoration empty string text decoration value (e.g. underline)
padding empty-string padding value
border-width 0 border width value
border-color black border color value
border-style solid border style value
start-indent empty string start indent value
end-indent empty string end indent value

pre.decoration

generate a pre block with arbitrary properties.

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)
text-align empty string text align value
background-color empty-string background color code/name
color empty string font color name/code
font-{style|family|weight|size} empty string respective font properties
text-decoration empty string text decoration value (e.g. underline)
padding empty-string padding value
border-width 0 border width value
border-color black border color value
border-style solid border style value
start-indent empty string start indent value
end-indent empty string end indent value

div.decoration

generate a div block with arbitrary properties.

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)
text-align empty string text align value
background-color empty-string background color code/name
color empty string font color name/code
font-{style|family|weight|size} empty string respective font properties
text-decoration empty string text decoration value (e.g. underline)
padding empty-string padding value
border-width 0 border width value
border-color black border color value
border-style solid border style value
start-indent empty string start indent value
end-indent empty string end indent value

h1

generate header block (similar to HTML h1- h6).

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)

image.block

generate block image (similar to block HTML img).

Parameters
Name Default Notes
url empty string a string with image url value
height empty string height value
width empty string width value

blockquote

generate block similar to HTML blockquote.

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)

center

generate block similar to HTML center.

Parameters
Name Default Notes
content empty node-set nodes for canned context
class local-name() a class identifier (HTML only)

br

generate empty block similar to HTML br.

Parameters

None.

Templates for Lists (lists.xsl)

ul

generate unordered list (similar to HTML ul).

Parameters
Name Default Notes
content empty node-set nodes for canned context

ul.nested

same as ul, but for lists within lists (padding-top is set to 0).

Parameters
Name Default Notes
content empty node-set nodes for canned context

ol

generate ordered list (similar to HTML ol).

Parameters
Name Default Notes
content empty node-set nodes for canned context

ol.nested

same as ol, but for lists within lists (padding-top is set to 0).

Parameters
Name Default Notes
content empty node-set nodes for canned context

ul-li

unordered list item (similar to HTML li within ul).

Parameters

None.

ol-li

ordered list item (similar to HTML li within ol).

Parameters

None.

dl

definition list (similar to HTML dl).

Parameters

None.

dt

definition term (similar to HTML dt ).

Parameters

None.

dd

definition description (similar to HTML dd ).

Parameters

None.

Simple Table Templates (simple-tables.xsl)

simple-table

generate table (similar to HTML table).

Parameters
Name Default Notes
rows child nodes with name row If your table has row elements with name other than row, select these elements and pass them with this parameter.
text-align empty string text align value
background-color empty-string background color code/name
color empty string font color name/code
font-{style|family|weight|size} empty string respective font properties
text-decoration empty string text decoration value (e.g. underline)
padding empty-string padding value
border-width 0 border width value
border-color black border color value
border-style solid border style value

simple-row

generate table row (similar to HTML tr).

Parameters
Name Default Notes
cells child nodes with name cell If your table has cell elements with name other than cell, select these elements and pass them with this parameter.
text-align empty string text align value
background-color empty-string background color code/name
color empty string font color name/code
font-{style|family|weight|size} empty string respective font properties
text-decoration empty string text decoration value (e.g. underline)
border-width 0 border width value
border-color black border color value
border-style solid border style value

simple-cell

generate table cell (similar to HTML td).

Parameters
Name Default Notes
content empty node-set nodes for canned context
span empty string number of columns spanned
border-width 0 border width value
border-color black border color value
border-style solid border style value
text-align empty string text align value
padding 2pt padding value
background-color empty-string background color code/name
color empty string font color name/code
font-{style|family|weight|size} empty string respective font properties
text-decoration empty string text decoration value (e.g. underline)