Articles in this section

See more

Variables

Avatar
Anders
  • Updated
Follow

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

Variable Types

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.

Variables Workflow

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. Publish your conten and choose the variants that Paligo should use.

Note

The process is different for Dynamic Text Variables.

Superscript Text in 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.

Use XML Variables for Links

Using XML variables is the only way to have links that change depending on publish settings. Unlike text variables, they allow you to use full XML strings. A link's destination is determined by the URL in the underlying XML, so you can use XML variables to change the link dynamically.

With XML variables, your link label can have the same name, but the destination can change depending on your publishing settings. You can use a different label altogether or disable linking completely in some versions of your documentation. XML variables give you more flexibility than other types of variables.

As an example, if there is a product that has two versions for different markets (one for the US market and one for the European market), the link label can be the same but the link destination can point to different distribution websites. You can also change the link label to something like "US Store" for the US version of the documentation, and "Europe Store" for the European version, with different link destinations for each.

Example_XML_LinkVariables_DocVersions_small.png

This instruction shows how to use different web pages depending on market.

  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 Create variable set from the menu.

    Create_VariableSet_small.png

  4. Enter a name for the variable set and select the check mark. Checkmark_small.png

  5. Expand the Variable sets with the arrow to the left. Insertion_point_small.png

    Show_VariableSets_small.png

  6. Select the new variable set.

  7. Select Add variable for each variable that is to be inserted in a topic.

  8. Name it and select XML to make it a link variable. Edit_Source_Code_small.png

    Add_XML_LinkVariable_small.png

  9. Select Add variant for each variant to publish to.

    Example_XML_Link_Variables_MarketPrices_small.png

  10. Copy the XML code below:

    <link xlink:href="ZZZ">XXX</link>

  11. Replace ZZZ with the URL.

  12. Replace XXX with the visible link label.

    In the example, we used "Car window" and "Electric motor" as the visible link names. Scroll down to see the result.

    Note

    To show the URL instead, remove the XXX.

  13. Open a topic and insert the created XML link variables. Insert_Variable.png

    Example_XMLLinkVariable_1_small.png

  14. Select the Preview tab in the Toolbar.

    Preview_menu_small.png

  15. Select Profile settings. Profile_settings_button_small.png

  16. Select the Variables tab. Re-index_Translations_button_small.png

  17. Select the variable set and XML link variable to be used.

    Example_XML_Link_Variables_MarketPrices_2_small.png

  18. Select Apply.

    Chosen XML link variable will be shown in the topic.

    Example_XMLLinkVariable_2_small.png

  19. Publish the topic to see the visible link name.

    Example_XMLLinkVariable_3_small.png

Variable Sets

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 be used. 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.

Create a Variable Set

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.

    VariableSet_Create_small.png

  3. Select Create variable set.

  4. Name the variable set.

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

    Variables_Editor_small.png

    Paligo displays it in the Variables Editor.

  6. Select Add Variable .

    variableset.png

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

  8. Repeat step 4 to create as many new variable types as needed for this variable set.

  9. 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.

  10. Enter values for each variable.

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

    AddVariableValue.png

  11. Repeat steps 9 and 10 to create as many variants and variant values as needed.

    Variableset

Convert Variables

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.

Copy a Variable Set

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.

Delete a Variable Set

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.

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 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

Move Variables between Variable Sets

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.

Remove Variables

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.

Use Variables

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:

 

Insert a Variable

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.

Preview Variables

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.

Choose Variable Sets for Publishing

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

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 General Publishing Process. 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

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.

    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.

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

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk