XPath expressions#

Attributes select and test expect an XPath expression to get the data. For example the test in a Switch/Case statement must evaluate to true() or false():

<SetVariable variable="a" select="1234"/>
...
<Switch>
    <Case test="$a > 12">
        ...
    </Case>
</Switch>

or the contents of a variable is set like this:

<SetVariable variable="foo" select="data"/>

This selects the child elements of the current node in the data file with the name data. See an XPath 2 introduction for more information on XPath (for example on W3Schools).

All other attributes in the layout file allow a temporary XPath mode using curly braces. In the next example the attributes row, column and backgroundcolor don't allow dynamic settings, but with the curly braces you can jump into XPath evaluation and get the attribute values on the fly:

<Layout xmlns="urn:speedata.de/2021/xts/en"
 xmlns:sd="urn:speedata.de/2021/xtsfunctions/en">
    <Pageformat height="6cm" width="10cm" />
    <SetVariable variable="x" select="12 * 2"/>
    <SetVariable variable="y" select="36 div 2"/>

    <Record element="data">
        <PlaceObject row="{$x}mm" column="{$y}mm">
            <Box height="1cm" width="3cm" backgroundcolor="{ @col }"/>
        </PlaceObject>
    </Record>
 </Layout>

<data col="goldenrod"></data>

Layout functions#

The layout functions are in the name space urn:speedata.de/2021/xtsfunctions/en.

sd:aspect-ratio()#

Return the result of the division width by height of the given image. (< 1 for portrait images, > 1 for landscape).

The return value is a double.

sd:attribute()#

Return the value of the attribute in the data file.

Assuming that the variable $attributePrefix contains the string "fo", the following XPath expressions are equivalent: @foo, @*[local-name() = 'foo'], sd:attribute( 'foo' ) and sd:attribute( ($attributePrefix,'o') ) (notice the argument of the last example is a sequence).

sd:current-page()#

Return the current page number.

sd:current-row()#

Return current row within the the area.

sd:decode-base64()#

Decode a string with base64 encoding.

The base64 encoded data which has to be stored in a string gets converted into a byte array. Useful for including images stored in the data file. See sd:file-contents() and the base64 example.

sd:decode-html()#

Convert a string to HTML.

Example: sd:decode-html('<b>bold text</b>') creates a HTML structure like putting <b>bold text</b> in the data file.

sd:dummy-text()#

Create a lorem ipsum text which is useful for debugging.

sd:even()#

Return true if the given number is even.

sd:file-contents()#

Write the argument to a file in a temporary directory and return the file name.

Useful for including images stored in the data file. See sd:decode-base64() and the base64 example.

sd:file-exists()#

Return true if the file exists.

sd:format-number()#

Insert thousands separator into a number.

Example: sd:format-number(-12345678.912, ',', '.') returns the string -12,345,678.912, sd:format-number(-12345678.912, '.', ',') the string -12.345.678,912 (last to arguments swapped).

sd:group-height() and sd:group-width()#

Return the height or width of a group.

Example: sd:group-height('mygroup','cm') could return 2.74.

sd:image-height() and sd:image-width()#

Return the height or width of an image.

The image dimensions are rather meaningless when the image is a bitmap file (PNG or a JPEG). XTS assumes a PPI (pixels per inch) value of 96. So a 960 pixel wide image has a width of 10 inch or 254 mm. XTS does not extract the PPI values from the image itself.

sd:last-page-number()#

Return the last page number of the document. This actually returns the number of pages of the previous run, so it might not be accurate if the number of pages changes in a subsequent run.

sd:markdown()#

Interpret the argument as markdown and return HTML.

Example: sd:markdown( '**strong text**' ) returns the string <strong>strong text</strong> which gets interpreted as HTML.

sd:md5(), sd:sha1(), sd:sha256(), sd:sha512()#

Calculate hash values.

Example: sd:md5( ('Hello, ', 'world') ) returns the string bc6e6f16b8a077ef5fbc8d59d0b931b9.

sd:mode()#

Check if mode is set.

Example: sd:mode('print') returns true() if XTS is called with --mode print on the command line.

sd:number-of-columns()#

Return the width of an area in grid cells.

sd:number-of-rows()#

Return the height of an area in grid cells.

sd:odd()#

Return true if the argument is odd.

sd:page-number()#

Return the page number of a marker.

sd:roman-numeral()#

Return a number as a roman numeral.

Example: sd:roman-numeral(13) returns the string XIII.

sd:to-unit()#

Convert units to other units.

sd:total-pages()#

Return the number of pages in a graphics file.

This function returns the number of pages in a PDF file. If the image is not a PDF file, the function returns 1.

sd:variable()#

Return the value of a variable. The variable name can be created dynamically.

Assuming that the variable $variablePrefix contains the string "fo", the following XPath expressions are equivalent: $foo, sd:variable( 'foo' ) and sd:variable( ($variablePrefix,'o') ) (notice the argument of the last example is a sequence).

XPath functions#

The following XPath functions are implemented. This list follows the structure of the function specification.

Functions on Numeric Values#

Functions to Assemble and Disassemble Strings#

Equality and Comparison of Strings#

Functions on String Values#

Functions Based on Substring Matching#

String Functions that Use Pattern Matching#

Additional Boolean Constructor Functions#

Functions on Boolean Values#

Component Extraction Functions on Durations, Dates and Times#

Functions on Nodes#

Context Functions#