Programming

Certainly the most important feature of the Publisher is the ability to implement very flexible layout requirements. This is mainly achieved by the built-in programming language in connection with the query options of the Publisher.

Basic programming knowledge is required to use the full functionality of the Publisher. The programming language has been kept as simple as possible to maintain the readability of the layout.

Data processing with Record and ProcessNode

The foundation of data processing in the speedata Publisher is the interplay between [Record](/publisher/en/reference/record/) and [ProcessNode](/publisher/en/reference/processnode/). Similar to xsl:template match and xsl:apply-templates in XSLT, Record defines processing rules for data elements and ProcessNode invokes them.

The Publisher processes XML data by finding the matching Record for each data element and executing the instructions it contains. The Record for the root element of the data file is called automatically; all other data elements must be processed explicitly using ProcessNode.

<Record element=”product”>
  <PlaceObject>
    <Textblock>
      <Paragraph><Value select=”@name” /></Paragraph>
    </Textblock>
  </PlaceObject>
</Record>

This Record is executed when a <product> element is processed.

Pattern matching with the match attribute

Since version 5.5.8, the match attribute can be used instead of element. This allows processing rules to be assigned based on XPath-like patterns, not just the element name.

A simple element name in match is equivalent to element:

<!-- These two lines are equivalent: -->
<Record element=”product”>
<Record match=”product”>

Beyond that, match supports additional patterns:

Predicates Allow distinguishing elements based on their attributes or content.

<Record match=”item[@type='book']”>
  <!-- Only executed for item elements with type=”book” -->
</Record>

Parent/child patterns Enable context-dependent matching based on the parent element.

<Record match=”catalog/product”>
  <!-- Only for product elements whose parent is catalog -->
</Record>

Ancestor patterns Match across arbitrary nesting depth.

<Record match=”catalog//item”>
  <!-- For item elements anywhere below catalog -->
</Record>

Wildcards Match any element, useful as a fallback rule.

<Record match=”*”>
  <!-- Called for all elements that have no more specific Record -->
</Record>

Wildcards with predicates

<Record match=”*[starts-with(local-name(), 'chap')]”>
  <!-- Matches all elements whose name starts with “chap” -->
</Record>

Priorities with multiple matching Records

When multiple Records match a data element, the most specific one is selected. A Record with element (or match with a simple element name) always takes precedence over pattern-based Records. Among patterns: patterns with predicates or path expressions have higher priority than the wildcard (*).

Modes

The mode attribute allows defining different processing rules for the same element. The mode in ProcessNode must match the mode in the corresponding Record. mode works with both element and match.

<Record match=”product” mode=”summary”>
  <!-- Short representation -->
</Record>

<Record match=”product” mode=”detail”>
  <!-- Detailed representation -->
</Record>

<ProcessNode select=”product” mode=”summary” />
<ProcessNode select=”product” mode=”detail” />

Variables

All variables are globally visible. This means that a variable never becomes invalid. Here’s an example:

<data>
  <article number="1" />
  <article number="2" />
  <article number="3" />
</data>

<Layout xmlns="urn:speedata.de:2009/publisher/en"
  xmlns:sd="urn:speedata:2009/publisher/functions/en">

  <Record element="data">
    <ProcessNode select="article"/>
    <Message select="$nr"/>
  </Record>

  <Record element="article">
    <SetVariable variable="nr" select="@number"/>
  </Record>

</Layout>

The global visibility is necessary because the program execution in the layout sometimes “jumps back and forth”. At the end of the page the content of <AtPageShipout> is executed in the current page type. It must also be possible to access the variables there.

In variables not only simple values can be stored, but also complex XML sections:

<Record element="data">
  <SetVariable variable="foo">
    <Paragraph>
      <Value>Hello world!</Value>
    </Paragraph>
  </SetVariable>

  <PlaceObject>
    <Textblock>
      <Copy-of select="$foo"/>
    </Textblock>
  </PlaceObject>
</Record>

This produces the expected output of “Hello world!”. A use case is to store table width declarations:

<SetVariable variable="tablecolumns">
  <Columns>
    <Column width="1cm"/>
    <Column width="4mm"/>
    <Column width="1cm"/>
  </Columns>
</SetVariable>

and then use them in several tables:

<PlaceObject>
  <Table>
    <Copy-of select="$tablecolumns"/>
    <Tr>
      ..
    </Tr>
  </Table>
</PlaceObject>

The one-time definition and reuse saves typing work and reduces the sources of error.

Execution time

The contents of variables containing child elements are evaluated immediately. I.e. in the following case

<SetVariable variable="tmp">
    <Paragraph><Value select="$greeting"/></Paragraph>
</SetVariable>

the variable greeting must already be defined. Subsequent modification of the output in the paragraph does not happen.

It follows that the variables must not contain any output commands, such as <PlaceObject> or <ClearPage>, since these would take effect immediately.

There is an option to defer this evaluation time to the application at <Copy-of> (execute="later"):

<SetVariable variable="tmp" execute="later">
    <Paragraph><Value select="$greeting"/></Paragraph>
</SetVariable>

<SetVariable variable="greeting" select="'Hello User'"/>

<PlaceObject>
    <Textblock>
        <Copy-of select="$tmp" />
    </Textblock>
</PlaceObject>

Here, only when <Copy-of> is used, the contents of $tmp are evaluated, then output. This also works with output commands:

<SetVariable variable="tmp" execute="later">
    <PlaceObject>
        <Textblock>
            <Paragraph><Value select="$greeting"/></Paragraph>
        </Textblock>
    </PlaceObject>
    <ClearPage />
    <PlaceObject>
        <Textblock>
            <Paragraph><Value>Hello user</Value></Paragraph>
        </Textblock>
    </PlaceObject>
</SetVariable>

<SetVariable variable="greeting" select="'Hello User'"/>

<Copy-of select="$tmp" />

generates twice the output ‘Hello User’ on a separate page.

Copy of

was already used before. This copies the contents of the variable to the current position. The contents of the variables remain unchanged during copying.

variable =
   Copy-of variable
   new value

This appends the new value to the previous ones.

<SetVariable variable="chapter">
  <Copy-of select="$chapter"/>
  <Element name="entry">
    <Attribute name="chaptername" select="@name"/>
    <Attribute name="page" select="sd:current-page()"/>
  </Element>
</SetVariable>

If-then-else

In XPath you can perform simple if-then queries. The syntax for this is if (condition) then ... else ...:

<PlaceObject>
  <Textblock>
    <Paragraph>
      <Value select="
        if (sd:odd(sd:current-page()))
           then 'recto' else 'verso'"/>
    </Paragraph>
  </Textblock>
</PlaceObject>

Case distinctions

Case distinctions are similar to the switch/case construct in C-like programming languages. They are applied in the Publisher as follows:

<Switch>
  <Case test="$i = 1">
    ...
  </Case>
  <Case test="$i = 2">
    ...
  </Case>
   ...
  <Otherwise>
    ...
  </Otherwise>
</Switch>

All commands within the first possible case are processed if the condition in test applies there. In test, an XPath expression is expected that returns true() or false(), like $i = 1, and if no case occurs, the contents of the optional <Otherwise> section will be executed.

Loops

There are various loops in the speedata Publisher. The simple variant is <Loop>:

<Loop select="10">
  ...
</Loop>

This command executes the enclosed commands as many times as the expression in select results in. The loop counter is stored in the variable _loopcounter, unless otherwise set by variable="...".

Besides the simple loop there are also loops with conditions:

<Record element="data">
  <SetVariable variable="i" select="1"/>
  <While test="$i &lt;= 4">
    <PlaceObject>
      <Textblock>
        <Paragraph>
          <Value select="$i"/>
        </Paragraph>
      </Textblock>
    </PlaceObject>
    <SetVariable variable="i" select="$i + 1"/>
  </While>
</Record>

The expression $i <= 4 must be read as $i \<= 4, because the opening angle bracket at this point in the XML is a syntax error. The loop above is executed as often as the content of the variable i is less than or equal to 4. Don’t forget to increase the variable as well, otherwise an infinite loop will result.

In addition to the while loop, there is also the until loop, which works in the same way:

<Record element="data">
  <SetVariable variable="i" select="1"/>
  <Until test="$i &lt;= 4">
    <PlaceObject>
      <Textblock>
        <Paragraph>
          <Value select="$i"/>
        </Paragraph>
      </Textblock>
    </PlaceObject>
    <SetVariable variable="i" select="$i + 1"/>
  </Until>
</Record>

Functions

It is possible to define functions with the new XPath module :

<Layout xmlns="urn:speedata.de:2009/publisher/en"
    xmlns:sd="urn:speedata:2009/publisher/functions/en"
    xmlns:fn="mynamespace">

    <Record element="data">
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value select="fn:add(3,4)" />
                </Paragraph>
            </Textblock>
        </PlaceObject>
    </Record>

    <Function name="fn:add">
        <Param name="a" />
        <Param name="b" />
        <Value select="$a + $b" />
    </Function>
</Layout>

The functions can also contain more complex expressions:

<Layout xmlns="urn:speedata.de:2009/publisher/en"
    xmlns:sd="urn:speedata:2009/publisher/functions/en"
    xmlns:fn="mynamespace">

    <Record element="data">
        <Value select="fn:chapter('First chapter')" />
    </Record>

    <Function name="fn:chapter">
        <Param name="chaptername" />
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value select="$chaptername"/>
                </Paragraph>
            </Textblock>
        </PlaceObject>
    </Function>
</Layout>

The namespace for the function must be defined in the root element (here: xmlns:fn="..."). Variables defined in the function remain local, i.e. are not visible in other program parts.

Data Structures

The speedata Publisher does not offer direct support for data structures such as arrays (fields) or dictionaries (hashes or dictionaries). These can be simulated using variables. The array elements a1, a2, …, ai could be populated as follows:

<SetVariable variable="{ concat('a',1) }" select="'Value for a1'"/>
<SetVariable variable="{ concat('a',2) }" select="'Value for a2'"/>
...

Of course, a1 could also be specified directly as the variable name. In this example, both the prefix and the suffix could be created dynamically:

<SetVariable variable="prefix" select="'a'" />
<SetVariable variable="{ concat($prefix,1) }" select="'Value for a1'"/>
<SetVariable variable="{ concat($prefix,2) }" select="'Value for a2'"/>
...

The read access goes via sd:variable(...):

<SetVariable variable="prefix" select="'a'" />
<Message select="sd:variable($prefix,1)"/>
<Message select="sd:variable($prefix,2)"/>
...

The function sd:variable() concatenates all arguments as a string and takes the result as variable name.