Getting Started with Paligo

Filtering Content

The core idea of topic-based authoring is to author content in small pieces of reusable information - topics. And the ideal is to have chunked your content into topics so that it is as reusable as possible. Sometimes, however, you may find that a topic could be highly reusable if it weren't for a small paragraph, list item or image. If you could only vary that piece of content within the topic it would make it so much more flexible.

This is what you can accomplish using filtering, sometimes also called "profiling" or "conditional content".

Imagine you have a list of content, where just one list item needs to vary depending on the product you publish for:

To do this, filter the content as follows.

  1. Select the first item you want to filter by placing the cursor inside the element, in this case a listitem.

    Select the right element

    Selecting e.g a paragraph is easy, and you just need to place the cursor inside the text.

    For some elements, however, you have to take more care to make sure the correct element is selected. To make sure you select the whole list item above for instance, and not just the text paragraph inside it, use the arrow keys until you see in the Element menu that it is the listitem element that is selected.

    Similarly, filtering on variables requires an extra step: you cannot apply a filter directly on the variable. Instead, you need to add an extra phrase element, and insert the variable there. Now you can apply a filter on the wrapper phrase element.

  2. Open Element attributes in the Side Tool bar to the right and select the attribute xinfo:product.

    Several available filter attributes

    There are some default filter attributes available, such as:

    • condition (a general purpose filter attribute that you can use for any condition you choose.)

    • audience

    • vendor

    • os

    Additional custom filter attributes are possible to add as well, and some commonly used are already available out of the box, for example:

    • xinfo:product - for profiling based on product names/models etc.

    • xinfo:country - for profiling based on countries the publication is meant for

    • xinfo:market - similar to country, but may offer a less geographically rigid categorization, e.g Asia, EU, US/North America, etc.

    • xinfo:version - For versioning information. Can be used in combination with the version management features of Paligo, but does not have to be. The usage is up to you.

    • xinfo:proglang - For filtering on programming language, or to publish to API style "on-the-fly" filtering HTML5.

    As an option, you can also filter on (natural) languages as well, and this is a bit special, because you do not select a profile filter for this when publishing, it is automatically filtered when you publish to any other language than the one set on an element. For this you can use the xml:lang attribute. To enable that option to use xml:lang as a filter attribute you need to do so in the Layout Editor under "General / Misc". You should use the ISO codes for languages, such as "en" for English, "sv" for Swedish, and so on.

    Note that not all attributes that start with xinfo are filtering attributes, it just means they are custom attributes that have been added and can be extended with others.

  3. The dialog Profiling attributes pops up, showing you the available values. You can also add new values here. Select the appropriate value to filter, in this example the listitem, and click Apply.

    A filter icon will show up next to the element. The Element attributes panel to the right will show the value if you have the cursor in the element.

  4. Repeat for any other element you want to profile, perhaps with a different value.

  5. Finally, once you have filtered the topics that need filters, once you go to publish your Publication, Paligo will show you the filters available. Just select the value you want to profile your Publication with in the publish dialog.

    Note

    The standard approach to filtering is to only select one value, except when using Scoped Filtering. Should this in any way conflict with your filtering strategy, Scoped Filtering can be disabled in the Layout Editor (under General / Misc for PDF, or Classes and attributes for HTML5). It is recommended to leave it on though. If using the standard approach there will be no conflict whether you use Scoped Filtering or not.

When you use filters on elements like this, only the content matching the value you select in the publishing dialog will be included in the published output. Of course any content that has no filter attributes set at all will also be included.

Tip

Note that you can use filter attributes on almost any element, including the top ("root") element of a topic, called section. If you put a filter on the section element at the top, the entire topic will be excluded from the publication. This can be useful if you want to use the same publication structure for many different products, where only a topic or two should be excluded from some products. In some cases that may be more manageable than creating a separate publication for each product. Use your judgment to choose the most manageable solution.

See also

Variables

Removing or renaming filter values

Caution

This is a very convenient feature that makes it easy to change filters in bulk, but it should be done with great care, as it affects all components possibly using the filter values you are editing or removing.

  1. Make sure all components are checked in first. Do this in the Check in widget on the dashboard:

    Select the All option to see every checked out document, and then select all documents by clicking the top checkbox.

  2. Verify that all documents are really checked in.

  3. Create a dummy topic, just a topic with a title and a single para element.

    You need to do this in a dummy topic, as all topics affected should be checked in.

  4. Now put the cursor in the para element, and then click to add the filter attribute that you want to remove or rename to. In this case we'll use xinfo:product as an example:

  5. Hover over the filter value you want modify:

    • If you want to remove the value, click the Remove icon:

    • If you want to rename the value, click the Edit icon:

  6. Verify by spot checking some topics that used to have the filter that you changed or removed.