Variables in documents

Introduction

Daisy allows to insert variables in documents, which will be replaced with their actual value during publishing of the documents.

A typical use-case of this is to avoid hard-coding product names in documentation, since the product might be marketed with different names or could change over time.

Another way to look at variables is that they allow for re-use of inline content, while document includes allow for re-use of block content (inline and block are HTML/CSS terminology: inline = things which are stacked horizontally on lines, block = things which are stacked vertically on a page). Be aware though of the limitations, explained further on.

Here are some basic facts about the variables:

• Variable name-to-value mappings are defined in Daisy documents of type Variables, containing a VariablesData part.

• It is possible to configure variable substitution on a per-site level. Thus the same document, displayed in different sites, can have its variables resolved to different values.

• Book publishing also supports variables.

• The actual variable resolving is a feature of the Publisher, configured using p:variablesConfig.

• Variables can be inserted in document content (= Daisy-HTML parts) or in the document name. Some effort is done to substitute variables in these document names also when the document name occurs in navigation trees or query results.

Quick variables how-to

These are the basic steps to put variables in action.

Create a new document of type Variables and save it. As you will see, the editor for the variables is simply XML-source based. Take note of the ID of the created document, you'll see it in the URL after saving, something like 55-DSY.

Create one of these files, depending on whether you want to configure variable resolution per-site or for the Wiki as whole:

site-specific:
<wiki data dir>/sites/<sitename>/conf/variables.xml

global:
<wiki data dir>/conf/variables.xml

And put the following in it:

<?xml version="1.0"?>
<variables>

  <variableSources>
    <variableDocument id="55-DSY"/>
  </variableSources>

  <variablesInAttributes allAttributes=”true”/>

</variables>

In this XML, change the value of the id attribute to the ID of the created variables document.

Allow up to ten seconds for the Wiki to notice this configuration change.

You are now ready to start using variables. Create a new document (e.g. of type Simple Document), on the toolbar of the rich text editor there's a button to insert variables. If you insert one, and save the document, you should see the variable resolved to its value.

Defining variables

Creating new variable documents

Variables are defined by creating documents of type Variables, containing the part VariablesData.

Actually the only real requirement is the presence of the VariablesData part, so one could create other types of documents containing this part and use them for variable substitution.

Structure of the variable documents

The variables are specified in an XML format, which follows this structure:

<v:variables xmlns:v="http://outerx.org/daisy/1.0#variables">
  <v:variable name="var1">value 1</v:variable>
  <v:variable name="var2">value<strong>2</strong></v:variable>
</v:variables>

As you can see in the example, variable values can contain mixed content.

The editor will validate the well-formedness and structure of the XML upon saving. When the content of the part is empty (= typcially when creating a new document), some sample XML is inserted to get you started.

Editing existing variable documents

If you want to edit the variables in use in the current site, you can use Tools -> Variables to get an overview of the active variable documents.

If a variable document is invalid

If during document publishing, a variable document cannot be loaded (e.g. due to invalid XML), no exception will be thrown, rather the variables defined in that document will not be available and an error will be logged to the repository log file.

Staging / live mode

Depending on whether the site is in staging or live mode, either the last or live versions of the variable documents will be used.

Permissions on the variables documents

The variable documents are filtered based on the read rights of the current user on the document. In staging mode, read access to non-live versions is required.

Configuring Wiki variable resolution

It is possible to define the variable configuration globally for the Wiki, or per site. If the config for a site is missing, it will fall back to the global configuration, if present.

The global variable configuration should be placed here:

<wiki data dir>/conf/variables.xml

The site-specific variable configuration should be placed here:

<wiki data dir>/sites/<sitename>/conf/variables.xml

The content of the files is in both cases the same, and follows this structure:

<?xml version="1.0"?>
<variables>

  <variableSources>
    <variableDocument id="64-DSY"/>
    <variableDocument id="128-DSY"/>
    <variableDocument id="256-DSY"/>
  </variableSources>

  <variablesInAttributes allAttributes=”false”>
    <element name="img" attributes="daisy-caption,[comma separated list]"/>
    <element name="table" attributes="daisy-caption"/>
  </variablesInAttributes>

</variables>

Multiple variable documents can be specified, these will be searched in the given order when resolving variables.

For resolving variables in attributes, one can either explicitely define the attributes for which this should happen, or simply say to do it in all attributes. Explicitely listing the attributes can be used when performance is a concern (however, the amount of attributes in a Daisy document is typically not very high).

When the configuration doesn't seem to be used

The Daisy Wiki only looks for configuration changes every ten seconds. Thus if you count to ten and don't see the result of your configuration changes, there's something wrong.

Problems with errors in the configuration file (e.g. invalid XML) will be logged in the Daisy Wiki log file. They will not cause display of documents to fail.

Problems with loading the variables documents (e.g. don't exist, invalid XML, etc.) will be logged in the repository server log file.

Configuring variable resolution for books

This is done using some book metadata properties.

Inserting variables in documents

Inserting variables in document text.

This can be done by using the “Insert/remove variable” button on the toolbar.

In HTML source, a variable is inserted as <span class='variable'>variable-name</span>

Inserting variables in attributes and in the document name

This can be done by using the syntax ${variable-name}. To insert the text ${... literally, use $${....

Note that the actual attributes which support variable substitution are dependent upon configuration.

Unresolved variables

If a variable cannot be resolved to a value, the following construct is inserted: <span class='daisy-missing-variable'>[unresolved variable: variable name]</span>

Limitations of the variables

By putting variables in documents, the documents become simple templates which generate different content depending on the context in which they are displayed. If the user sees a word in a document which results from a variable, and the user searches for that word using the fulltext search, then the document will not be part of the search results since that word doesn't really occur in the document.

Similarly, searches on document names search on the not-variable-resolved document names.

The variable names are part of the fulltext index, so you can search where variables are used.

Variable substitution in document names is currently not performed everywhere in the Wiki. The basic document display (documents, navigation tree, queries embedded in documents) are processed, but in other locations such as the document browser used in the editor etc. the document names are are unprocessed, since authors are probably more interested to see the raw document name.