Skip to main content

Variables

Variables allow you to swap out small parts of content for different publications. They are very useful when you have topics that you want to reuse, but need to have parts of the text changed, such as product names.

For example, let's say you have a topic and you insert the product name "Acme 100" as plain text. By adding it as plain text, you have limited where the topic can be reused, as it is specific to the "Acme 100" and so cannot be used for other products. But if you use a variable to set the product name, you can reuse the topic and tell Paligo which product name to use each time you publish.

variable-diagram.jpg

In Paligo, there are several types of variable that you can use:

  • Text: for plain text that does not need to be translated, such as product names, number values, etc.

  • Text (translatable): this variable type will let you enter translations of each variable value (for the languages you have selected). If you use this type of variable, remember that different languages can have very different grammars. Translated variables can read badly if the grammar, gender, etc., of each language has not been considered.

  • Image: these variables allow you to swap out images. They are useful when you have topics that contain images that need to be changed for different variants or publications. It is often more convenient to have a variable for the image, rather than many images with filtering.

  • XML: these variables are similar to plain text variables, but allow you to add XML tags too, so you can include inline tags if needed.

  • Dynamic text variables: These are a special type of variable, and you can use them for inserting things like today's date or for inserting the content from an element that is elsewhere in the publication. They are different to other variable types as you do not create them in variable sets. Read more about them in Dynamic Text Variables.

To use variables in your topics and publications, follow this process:

  1. Create a Variable Set - This is a collection of variables and the possible values that they can contain.

    • In the variable set, add variables for each type of information that needs to change in different scenarios.

    • Create variants for the variables. A variant is a collection of values that will be inserted into the variables when you publish. For example, if you have a product name variable, you could have a variant where the product name is "ACME 100X" and you could have another variant where the product name is "ACME 200X". Think of each variant as the values that will be used in one particular scenario.

    You can skip this step if you already have suitable variable sets available in Paligo.

  2. Insert a Variable into your topics where appropriate.

  3. Preview Variables to check that they are providing the correct information.

  4. About Publishing your conten and choose the variants that Paligo should use.

Note

The process is different for Dynamic Text Variables.

You can use variables for many different types of changeable content, but one of the most popular uses is for product names and company names. With these, you may want to add superscript text to the variable, for example, to add a trademark TM after the product name.

To add superscript text to a variable:

  1. Create or edit a variable set (see Create a Variable Set).

  2. In the variable set, create an XML variable and give it a name, for example, ProductNameTM.

    add-new-xml-variable.jpg
  3. Set the value for the XML variable. The value is called a variant. As this is an XML variable, include the inline <superscript> element. For example:

    ACME<superscript>TM</superscript> 1000
    
  4. Insert the variable in your topics as needed.

With variables, you can alter small pieces of content (text, images, values, links) that you want to change for different scenarios. This makes it possible to reuse more content. The variables are defined in a Variable Set, which is a collection of variables and their possible values.

When you publish with a variable set containing variants, you can choose which variant to use. The variables (like height, product name, variant image, weight and width) fetch the values from the column that represents the chosen variant.

Variables_Editor_small.png
  • The left column contains the variables, which are the placeholders that you add to your topics. In this column, you enter the variable names.

  • The second, third and fourth columns contain variants. Each variant column represents a different scenario and contains the terms or values that will be used for the variables, for example different weights.

Tip

Once the Variable Set is created, you can use the variables in your topics, see Use Variables.

To create a variable set, watch the following video or read the instructions below.

 
  1. Scroll down to Variable sets in Content Manager. Re-index_Translations_button_small.png

  2. Select the dotted menu (...) for Variable Sets and choose Create variable set. Insert_Variable.png

    VariableSet_Create_small.png
  3. Name the variable set and confirm it with the check mark. Checkmark_small.png

  4. Select the new variable set to open it in the Variable Editor.

    New_Variable_Set.png

    Paligo displays it in the Variables Editor.

  5. Select Add Variable.

    variableset.png
  6. Select the Variable type to create.

    CreateVariable.png
    • Text: for plain text that does not need to be translated, such as product names, number values.

    • Text (translatable): this variable type will let you enter translations of each variable value (for the languages you have selected). If you use this type of variable, remember that different languages can have very different grammars. Translated variables can read badly if the grammar, gender of each language has not been considered.

    • Image: these variables allow you to swap out images. They are useful when you have topics that contain images that need to be changed for different variants or publications. It is often more convenient to have a variable for the image, rather than many images with filtering.

    • XML: these variables are similar to plain text variables, but allow you to add XML tags too, so you can include inline tags if needed.

    Tip

    If you create a text variable and later realize that you need it to be a translatable variable, you can convert it by using the Convert Variable Type option. Similarly, you can convert a translatable variable into a text variable.

  7. Repeat step 5 to create as many new variable types as needed for this variable set.

  8. Select Add variant and enter a name.

    The variant is going to be one set of values that can be used for the variables. You might want different values for depending on the product model you are publishing for, so add product models as the variant columns.

  9. Enter values for each variable.

    These values will only be used if this particular variant is selected when publishing.

    AddVariableValue.png
  10. Repeat steps 8 and 9 to create as many variants and variant values as needed.

    Variables_Editor_small.png

You can convert an existing text variable into a translatable variable or vice versa by using the Convert Variable Type option. Paligo automatically detects the type of variable you have selected and will convert it into the other type.

Tip

If you have made a mistake, you can always do another conversion to change the variable back to its previous type.

To convert a variable:

  1. Scroll down to Variable sets in Content Manager. Re-index_Translations_button_small.png

  2. Select the arrow in front of the Variable sets to expand it. Insertion_point_small.png

    Paligo content manager side panel. It has sections for Documents, Media, Templates, and Variable sets. The Variable sets section is expanded to reveal two variable sets in a list.
  3. Select the variable set that contains the variables you want to convert.

    Variables_Editor_small.png

    Paligo displays it in the Variables Editor.

  4. Select the Dotted Menu (...) for the variable you want to convert.

    Variables_Editor_DottedMenu_small.png
  5. Select Convert Variable Type.

    Convert_Variable_small.png
  6. Select Confirm to convert the variable.

You can copy an existing variable set to use as a starting point for a new set. This is sometimes quicker than creating a new variable set from scratch.

Note

For performance reasons, we recommend that your variable sets have less than 2,000 entries. For example 100 variables x 20 variants = 2,000. In most cases it's better to divide your variables into a number of smaller sets in different categories.

  1. Scroll down to Variable sets in Content Manager. Re-index_Translations_button_small.png

  2. Select the arrow in front of the Variable sets to expand it. Insertion_point_small.png

    Paligo content manager side panel. It has sections for Documents, Media, Templates, and Variable sets. The Variable sets section is expanded to reveal two variable sets in a list.
  3. Select the Dotted Menu (...) for the variable set you want to copy.

    copyvariableset.png
  4. Select Copy.

    Paligo makes a copy of the variable set and adds it to the list of variable sets. It has the same name as the original version, but is appended with a number.

A variable set cannot be deleted unless all the variables from the variable sets are removed from the instances where they are used. To see where a variable is used, see Display Usage Information.

  1. Scroll down to Variable sets in Content Manager. Re-index_Translations_button_small.png

  2. Select the arrow in front of the Variable sets to expand it. Insertion_point_small.png

    Paligo content manager side panel. It has sections for Documents, Media, Templates, and Variable sets. The Variable sets section is expanded to reveal two variable sets in a list.
  3. Select the Dotted Menu (...) for the variable set you want to delete.

    VariableSet_Delete_small.png
  4. Select Delete.

  1. Scroll down to Variable sets in Content Manager. Re-index_Translations_button_small.png

  2. Select the arrow in front of the Variable sets to expand it. Insertion_point_small.png

    Paligo content manager side panel. It has sections for Documents, Media, Templates, and Variable sets. The Variable sets section is expanded to reveal two variable sets in a list.
  3. Select the variable set that contains the variables you want to display.

    Variables_Editor_small.png

    Paligo displays it in the Variables Editor.

  4. Select the Dotted Menu (...) for the variable you want to display the usage information for.

    Variables_Editor_DottedMenu_small.png
  5. Select Usage information.

    Usage_Information_small.png
  6. Paligo shows the usage information for the chosen variable.

    Usage_Information_2.png

If you need to reorganize your variables, you can move them from one variable set to another.

  1. Scroll down to Variable sets in Content Manager. Re-index_Translations_button_small.png

  2. Select the arrow in front of the Variable sets to expand it. Insertion_point_small.png

    Paligo content manager side panel. It has sections for Documents, Media, Templates, and Variable sets. The Variable sets section is expanded to reveal two variable sets in a list.
  3. Select the variable set that contains the variable you want to move.

    Variables_Editor_small.png

    Paligo displays it in the Variables Editor.

  4. Select the Dotted Menu (...) for the variable you want to move.

    Variables_Editor_DottedMenu_small.png
  5. Select Move variable.

    Move_Variable_small.png
  6. Choose the Variable set that will receive the variable.

    move-variable.png
  7. Select OK.

    Paligo moves the variable to chosen variable set.

A variable cannot be deleted unless it has been removed from the instances where it is used. To see where a variable is used, see Display Usage Information.

  1. Scroll down to Variable sets in Content Manager. Re-index_Translations_button_small.png

  2. Select the arrow in front of the Variable sets to expand it. Insertion_point_small.png

    Paligo content manager side panel. It has sections for Documents, Media, Templates, and Variable sets. The Variable sets section is expanded to reveal two variable sets in a list.
  3. Select the variable set that contains the variables you want to remove.

    Variables_Editor_small.png

    Paligo displays it in the Variables Editor.

  4. Select the Dotted Menu (...) for the variable you want to remove.

    Remove_Variable_small.png
  5. Select Remove Variable.

A variable is a piece of content that can have many different values, and when you publish, you choose which value Paligo should use. For example, you can have a product name variable and when you publish, you choose which product name should be used in the published content.

To use variables in your topics, you first need to create a variable set. In the variable set, you define what variables you need, and the different possible values that they can have. Each set of possible values is called a variant.

To find out how to insert variables in a topic, watch this video or read the sections that follow:

 

To insert a variable in your content:

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

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Place the cursor in a valid position for a variable.

    You can insert variables into most types of text block, including para elements.

    usingvariables1_50.png
  3. Select the Insert tab in the Toolbar.

    Toolbar_Insert_small.png
  4. Select Variable. Insert_Variable.png

  5. Select the variable set that contains the variable to be used.

    Alternatively, use the Search field to find the variable.

    usingvariables3_50.png

    A dialog opens, showing all of the variable sets you have available.

  6. Select the variable.

    usingvariables4_50.png
  7. Select OK.

    usingvariables5_50.png

    The variable is inserted at the cursor position.

  8. Select Save. Save icon.

After adding a variable, you can use the Preview feature to choose different variants. These allow you to see what value Paligo will use for the variable for each different variant.

When you are ready to publish your content, you can choose which variant Paligo should use for the published output.

You can use the Preview feature to see what values that are applied for your variables. This is useful for checking that the value you need is actually included in a variable set. If the value is not there, you will need to edit the variable set or create a new one.

To preview variables:

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

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Select the Preview tab in the Toolbar.

    Preview_menu_small.png
  3. Select Profile settings. Profile_settings_button_small.png

  4. Select the Variables tab.

  5. Select the variant that you want to preview in the topic.

    profile-settings-variables.png

    The variant is a collection of values, as defined in a variable set.

  6. Select Apply.

    preview-variables-shown.png

    Paligo updates the topic to show the variables that will be used with the variant you have selected.

When you publish your content, you can choose which values (variants) should be used for the variables in your content.

  1. In the Content Manager, select the options menu ( ... ) for the topic or publication you want to publish, and then select Publish.

  2. On the publish dialog, choose the type of output you want Paligo to create, and set the Languages and Profiling Attributes.

  3. Select the Edit option for Variables.

    select-edit-on-variables.png

    Paligo displays a list of all of the variable sets that are available.

    variables-list-publish.png
  4. For each variable set that is used in your topic or publication, select a variant. The variant's values will be inserted into the relevant variables in your content. Select OK to confirm.

    choose_a_variant.png
  5. Select Publish document to publish your content.

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.

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:

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.

Timestamp_small.jpg

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.

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    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.

    Element context menu shows a search field and a list of elements that are valid at the current position.
  4. Enter phrase and select it from the menu.

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

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

    phrase-role-dyntextvar.jpg

    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. Save icon.

  9. Preview the topic to verify the timestamp.

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 find out how to get the XML file, watch the video or read the following instructions:

 
  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.

    Publish document settings. Make debug build is enabled.
  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.