Variables in Paligo

5 min read

Dynamic Text Variables

Dynamic text variables are pieces of content that take their value from either the client session or from other elements in your content. They are resolved when you publish and you can use them to insert content such as:

Important

If you publish to PDF in multiple languages, there is an option to Combine selected languages in the PDF layout.

You can only use dynamic text variables if Combine selected language is disabled (unchecked). Dynamic text variables are only supported when publishing individual PDFs.

Dynamic Text Variables for Elements and Attributes

You can use dynamic text variables to insert the value of an element or attribute from your content into a topic. For example, you could add the value of the edition, author or releaseinfo elements from a Publication Topic into the topic. To learn more, see Supported Elements, Supported Info Elements and Supported Attributes.

To reference elements and attributes, you will need:

Dynamic Text Variables for Time and Date

With dynamic text variables, you can enable time and date to be automatically added to your content during the Publish Content. Since the information is retrieved from your browser's client session time and date, it will be accurate for your location. To find out more about the syntax for time and date variables, see SimpleDateFormat (Java 2 Platform SE 5.0).

To Insert a Dynamic Text Variable in your topics, add the references using the appropriate syntax in a phrase element. There are many different ways of displaying the time and date and we have included some examples below.

Syntax

Returns

${date:date-time()}$

The current date, time, and timezone information.

${date:format-usertime('h:m')}$

The current hour and minutes. Use this function for greater control over the format of the date and time in the output.

Set the arguments for the function in brackets, where string arguments must be enclosed in single quotes (as shown in the table).

${date:format-usertime('EEE, MMM d, yyyy')}$

The current day, month, and year.

${date:format-unixtime(ancestor::d:section[@xinfo:time-modified][1]/@xinfo:time-modified, 'EEE, MMM d, yyyy')}$

This syntax formats the Unix time stamp into readable text: Thu, Aug 10, 2023. Replace the date format in the syntax to change how the date is presented. To find suggestions, see Simple Date Format.

If ${@xinfo:time-modified}$ is used on its own, it presents the date as a computer code (1691661600). Embedding the syntax (like in the left column) the date becomes readable.

Insert a Dynamic Text Variable

When you know what elements and attributes you want to use for your dynamic text variables, you add them to your topics. This works for both HTML5 and PDF output.

To write XPath expressions, there are several things you need to be aware of:

  • Include the "d:" prefix for navigatingthe XML, for example: ${/*[1]/d:info/d:title}$. The namespace prefix d is bound to http://docbook.org/ns/docbook

  • Some DocBook attributes and Paligo extension attributes do not require a prefix. To access the extension attributes, use the @xinfo prefix, for example ${@xinfo:time-modified}$. It will show the date as a computer code, see Dynamic Text Variables for Time and Date for examples of how to make it readable. The namespace prefix xinfo is bound to http://ns.expertinfo.se/cms/xmlns/1.0.

  • For PDF output the top-level node that you can access is article. You cannot access the article's parent node (part).

To insert a dynamic text variable:

  1. Select the topic or component in the Content Manager to open it in the Editor.

    Alternatively, you can Create a Topic and edit that.

  2. Position the cursor at a valid position for the dynamic text variable.

    For example, inside a para element.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

  4. Enter phrase and select it from the menu.

  5. Select the phrase element in the Element Structure Menu and choose Go to element.

  6. Add the role attribute in the Element Attributes Panel and set its value to dyntextvar.

    This will add the minimum required syntax for the dynamic variable

    <phrase role="dyntextvar">${}$</phrase>
  7. In the phrase element, enter the syntax for the relevant XPath expression to access the element or attribute you want to use.

    Important

    If you use an expression to access an element or attribute that does not exist, the dynamic text variable will be empty (blank) in the output.

  8. Select Save.

  9. Preview the topic to verify the timestamp.

Plan your References with the Debug XML File

Paligo can provide you with a single XML file that contains all of the content in a publication (the publication itself and all of the topics). You can use this XML file to get a better understanding of the structure of your content, so that you plan the XPath expressions for your dynamic text variables. Use XPath 1.0 expressions to access the elements and attributes in your content.

To get the XML file:

  1. In the Content Manager, find your publication, select its option ( ... ) button, and then select Publish.

  2. On the Publish document dialog, choose the type of output you want, set the Languages, Profiling Attributes, and regular Variables, and then select the Make debug build option.

    The Make debug build option tells Paligo to include the build files in the output as well as the actual output. One of the build files is an XML file that contains your content.

  3. Select Publish document to publish your content.

    When it downloads, unzip it and look for the XML file that contains your content.

    For PDF outputs, the XML file has the same name as the publication and has a language suffix. For example, "Acme_100_user_guide-en.xml".

    For HTML, HTML5, XML, Word, and SCORM outputs, the XML file is named index and has a language suffix, for example, index-en.xml.

  4. Open the XML file from step 3 and use it to plan your XPath 1.0 expressions. When you have planned the expressions, you can insert dynamic text variables into your content and add the relevant expressions.