Taxonomy Filters

You can use taxonomy filters to control whether a topic is included in a publication. For example, you could use them on a topic so that it is included when you publish a Mac version of a user guide, but excluded when you publish a Windows version.

Some Paligo users prefer to use taxonomy filters instead of the "regular" filters (see Filter Topics in a Publication) as they are quick and easy to use. All you need to do is create your taxonomy tags, drag and drop them on to your topics, and choose which tags to include when you publish.

Another benefit of taxonomy tags is that you can use them to create more complex filters, similar to scoped filtering. For this, you organize the tags into a hierarchy. You can then set Paligo to include all of the tags in a branch of the hierarchy, rather than one specific taxonomy tag.

For example, let's say you have set up the following taxonomy tag hierarchy:

taxonomy-hierarchy-usa.jpg
  • 1 is the tag that represents the type of filter you want to use, in this case, the filter is called "Market". This is known as the filter attribute.

  • 2 are all tags for individual filter values. Note that the value tags can be organized into a hierarchy too. Here we have a value tag for the overall market, "USA", and then at a lower level, value tags for the different sub-markets. In this case, the sub-markets are states of the USA.

You can then set Paligo to use the hierarchy in different ways. For example, you can set Paligo to only include those topics that have the "Arizona" tag. Or you could set Paligo to include topics that have the "USA" tag and/or the "Arizona" tag.

To find out about using taxonomy filters, watch the video or read the following instructions.

To use taxonomy filters:

You only need to perform steps 1 and 2 when you first set up taxonomy filtering or when you want to add a new filter or filter value.

Before you create taxonomy tags for filtering, you should add the filter values you need. Then, when you create your taxonomy filter tags, you can give them the same names as the filter tags. This is how Paligo recognizes the relationship between a taxonomy tag and a filter value - they have to have the same name.

Note

If your Paligo instance already contains the filter attributes and values that you need to use, ignore this procedure. Your next step is to Create the Tags and Hierarchy for Taxonomy Filtering.

  1. Select the Publish option for any publication or topic, and then edit the Profiling attributes.

    publish-document-edit-profiling-values.jpg

    When you select Edit, Paligo displays the Profiling attributes dialog, which contains a list of the filter attributes that are available. The filter attributes define the types of filter, for example, there is a Market attribute for filtering by different regions.

  2. Select the field for each profiling attribute to see what values are available.

    profiling-attributes-check-options.jpg
  3. If you need to add values, create a new topic and select an element in it, such as a para element. Then use the Element attributes section to add a new filter attribute, for example, xinfo:product. Paligo displays the Profiling values dialog and you can use that to add new values for the element.

    add-profiling-value-markets.jpg

    Repeat this step for each filter attribute and value that you need for your publication.

When Paligo has all of the filter values that you need, you can Create the Tags and Hierarchy for Taxonomy Filtering.

When you have added the filter values you need to Paligo, you can create the taxonomy tags that you will use to mark your content for filtering.

Note

For this section, we assume that you already know how to create taxonomy tags. If you need to find out more, see Using Taxonomies.

You should create a taxonomy tag to represent:

  • Each filter attribute that you want to use. The filter attributes define the type of filter, for example, PRODUCT.

  • Each filter value that you want to use. The filter values define the condition, for example, ACME 1050 could be a condition for a PRODUCT filter.

    The filter value tags have to be at a lower-level than the filter attribute tags in the taxonomy hierarchy.

The taxonomy tags you create need to have the same names as the filters and filter values that they represent. For example, if you have a topic that is only relevant to an "ACME 1050" product, you could use an xinfo:product filter. For this, you would create a tag called "product" and then add a lower-level tag for "ACME 1050". (When setting the taxonomy tag names, do not include the xinfo prefix).

Note that the taxonomy tags for filter attributes should be named to match the filter attribute name

taxonomy-filters-mapping-to-filter-values.jpg

To set up taxonomy tags for filtering:

  1. In the Taxonomy Manager section of the Content Manager, create taxonomy tags for the filter attributes and the filter values that you need.

    For filter attribute tags, the tag name has to match the attribute name (but do not include any xinfo prefix). For example, if you want a taxonomy filter for the xinfo:market filter attribute, create a tag named: market.

    To find out more about the attributes you can use, see Filter Attributes.

    For filter value tags, set the name to match the value. For example, if you have a market filter with a value of "USA", the taxonomy tag for this should also be named "USA".

  2. Drag and drop the taxonomy tags into a logical hierarchy. The hierarchy has to be organized so that:

    • The filter attribute tags are at the highest level (below the taxonomies tag, but above all other tags)

    • The value tags are at a lower level to the filter attribute that they relate to.

    The filter attribute tags must be the "parent" and the value tags must be "children" in the hierarchy.

    taxonomy-hierarchy-usa.jpg

    In the image "Market" (1) is the filter attribute tag. All of the other tags are filter value tags (2). Note that you can have many levels of filter value tags, so that you can have greater control when filtering.

When you have set up the taxonomy tags, you can associate them with your topics.

When you have the appropriate tags and hierarchy in place, you can apply the taxonomy filter tags to your topics.

  1. In the Content Manager, select the options menu ( ... ) for the Taxonomies tag, and then select Floating content panel.

  2. In the floating content panel, find the tag that you want to apply to a topic. Drag the tag onto the topic in the Content Manager. Repeat this step for each topic that you want to filter.

    Drag and drop taxonomy

When you have applied the taxonomy tags to your topics, the next step is to choose how Paligo uses the taxonomy hierarchy when it applies the filters.

For taxonomy filters, Paligo gives you the option to choose a filter strategy. The strategy affects how Paligo matches the filters and determines what topics should be included or excluded from your publication.

To choose the taxonomy filter strategy:

  1. Select Layout and then edit the layout that you are going to use for publishing.

  2. Find the taxonomy settings.

    For PDF layouts, they are in the General > Filtering and Taxonomies settings.

    For HTML layouts, they are in the Classes and Attributes settings.

  3. Set Output taxonomies as class names to Enabled. This setting has to be enabled for taxonomy filtering to work.

  4. Select the Taxonomy filtering strategy that you want Paligo to use for this layout:

    • Exact value

      If you choose Exact value, Paligo will ignore the taxonomy hierarchy. When you publish and choose what filters to apply, Paligo will only include topics that:

      • Have a taxonomy tag that matches the filter attribute and filter value that you set for the publication.

      • Are not marked up to use the filter attribute that you set for the publication.

    • Descendants

      If you choose Descendants, Paligo will use the taxonomy hierarchy to determine which topics should be included or excluded.

      When you publish and choose what filters to apply, Paligo will only include:

      • Topics that have a taxonomy tag that matches the filter attribute and filter value. We will call this tag the "descendant" tag.

      • Topics that have a tag that is a "parent" of the "descendant" tag in the taxonomy hierarchy. Note that Paligo includes not only the immediate "parent" tag, but also the "parent" of that tag and so on, until the top-level is reached.

      • Topics that are not marked up to use the filter attribute that you set for the publication.

    See the example for a detailed look at how the exact value and descendant value taxonomy strategies affect the results of a filter.

    Note

    There is also a Disabled option, which turns off the taxonomy filter feature.

  5. Select Save.

When you have set a taxonomy strategy, you can publish your content and set the filters that you want it to use.

Example 1. Taxonomy strategy

Let's say you have the following hierarchy for a Product filter, and you filter the publication to include Product: ACME 1050. This is how the filtering strategies will work:

exact-match-example.jpg

Exact value filter strategy applied

descendants-match-example.jpg

Descendants filter strategy applied

The first image shows how the Exact value filter strategy works.

Paligo will ignore the structure of the taxonomy hierarchy. This means that the published output will include:

  • Topics that have the "ACME 1050" tag. Note that it has to be a "child" of the "Product" tag.

  • Topics that do not have any "Product" taxonomy tag

Paligo will exclude any topics that have a "Product" tag but with a different value to "ACME 1050".

The second image shows how the Descendants filter strategy works. Paligo uses the taxonomy hierarchy and includes topics that have the matching tag ("ACME 1050") or are "parents" of the matching tag. This means that the published output will contain:

  • Topics that have the "ACME 1050" tag. Note that it has to be a "child" of the "Product" tag.

  • Topics that have the "ACME 1000" tag or "ACME" tag, as these are "parent" tags of the "ACME 1050" tag in the taxonomy hierarchy.

  • Topics that do not have any "Product" taxonomy tag

Paligo will exclude any topics that have a "Product" tag but with a different value to "ACME 1050".


When you publish your content, you can choose which filters to apply to the published output (HTML5 help center, PDF, etc.).

  1. In the Content Manager, find the topic or publication that you want to publish. Select its options menu ( ... ) and select Publish.

  2. On the Publish document dialog, select an output type (PDF, HTML5, etc.), and set the Languages, Variables, and Optional Parameters.

    These are common publishing settings. To find out more, see Publishing Process.

  3. Select the Edit option in the Profiling attributes section. Paligo displays the Profiling attributes dialog.

    profiling-attributes-blank.png

    The Profiling attributes dialog contains a list of the filter attributes that you can use. There is a field for each attribute.

  4. Select the field for a filter attribute that you want to apply to your publication. A drop-down list of the available values appears. These are the values that have been created for the filter when the content was marked up for filtering.

    Choose the value that you want to apply.

    profiling-attributes.png

    You would normally just choose one value for each filter attribute, the variant that you want to publish at the moment. This is usually the recommended strategy. It's possible to choose multiple values for a filter, however. The filter then works as an OR filter, where Paligo will filter topics that contain any of the values you set (value 1 or value 2 or value 3, etc.).

    Tip

    When you choose filters, you are telling Paligo which content to include in the published output. But sometimes, you may want to exclude content rather than include it. For example, you might want to publish content for all audience types except administrators. To do this, you need to mark up the content so that:

    • The content you want to include has a condition (filter attribute) and a value

    • The content you want to exclude has the same condition as those that you want to include. But set a different value for the topics you want to exclude.

    When you publish, you choose which condition value to include. Paligo will then:

    • Include any content that has the matching condition and value

    • Include any content that does not use the matching condition

    • Exclude any content that uses the matching condition, but has a different value.

  5. Repeat step 4 for each attribute and value that you want to apply and then select OK.

    Note

    Only set a value for those filter attributes that you want to apply to your publication. For any attributes that you do not want to use, leave their fields blank. When there is no attribute set, Paligo ignores that type of filter.

  6. Select Publish document to publish your content.