Scoped Filtering

Scoped filtering is a very powerful feature in Paligo that allows you even more flexibility when it comes to profiling/filtering content. It is designed for when you want to:

  • Use the same content in multiple places in the same publication

    and

  • Apply different filters to that content, depending on where it appears in the publication.

Note

Scoped filtering is an advanced topic. Make sure you understand the basic profiling/filtering concepts before using scoped filtering.

To show you how scoped filtering can be used, we'll guide you through an example.

Example 1. Scoped filtering for applying different filters to reused content

Let's say you are documenting a product , for example, a fictional video conference software called ACME VCT. The software supports MacOS and Windows, and as most of the documentation is the same for both versions, you want to create a single user guide rather than two separate versions. The user guide will have a MacOS section and a Windows section.

In Paligo, you create the content and organize it in a publication structure like this:

overall-structure-scoped-filtering.png

You have a "chapter" for Windows content, called "Installing on Windows", and you have "Installing on MacOS" as a chapter about MacOS.

You have also reused two topics. The "Prerequisites" topic and the "System Requirements" topic are both used in the Windows and MacOS chapters. For this example, we will focus on the "System Requirements" topic.

In the "System Requirements" topic, you have some information that is for Windows only, and some that is for MacOS only.

scope-filter-on-content.jpg

In the image above:

  1. This is content that is only relevant to Windows. You apply an os filter to this content and set the filter value to windows.

  2. This is for content that is only relevant to MacOS. You apply an os filter to this content and set the filter value to macos.

If you published the content as it is, you would only be able to set the os filter to be either Windows only, MacOS only, or include Windows and MacOS.

This is where scoped filtering comes in. You can use it to tell Paligo to use an os:windows filter in some places, but an os:macos filter in others.

To set the scoped filtering, set a "scope filter" on the section element of a topic that is at a higher level than the topic you want to filter. In this scenario, the higher level topic is called a "parent" and the lower level topic is called a "child".

Note that the "scope filter" is not a type of filter, it is the term we use to describe the filter that is set on the "parent" topic.

apply-scopes.jpg

In this example, there are two "scope filters" to set (1 and 2 on the image above):

  1. Set the "scope filter" for the Windows chapter on the section element of the "Installing on Windows" topic. The "scope filter" is the os filter with the value: windows.

    os-windows-section.jpg

    With this "scope filter" you are telling Paligo that if any "child" topics in this chapter contain os filters, Paligo should include any that have the value: windows. But it should exclude any that have different values.

  2. Set the "scope filter" for the MacOS chapter on the section element of the "Installing on MacOS" topic. The scope filter is the os filter with the value: macos.

    os-filter-mac.jpg

    This "scope filter" tells Paligo that if any "child" topics in this chapter contain os filters, Paligo can include any that have the value: macos. But it should exclude any that have different values.

You now have your content marked up for scoped filtering. The final step is to set the filter and values when you publish.

You publish your content and you edit the Profiling attributes on the Publish document dialog. You choose to include the os filter. Importantly, for scoped filtering, you include all of the os values that need to appear in the published output. In this case, you want the Windows filtered content to appear in one chapter and the MacOS content to appear in another chapter, so you include both values.

publish-scoped-filter.png

The published output will now have reused the same topic "System Requirements" in two parts of the documentation, but it will appear differently in the Windows and MacOS sections respectively, even though it is in the same output:

Windows version

MacOS version

windows-scope.png
macos-scope.png

From the example, you can see that the important principles of scoped filtering are:

  • Scoped filtering applies to content that is reused in the same publication.

  • With scoped filtering you can reuse topics and set them to use different filter values, depending on where the topic is positioned in the publication structure.

  • You tell Paligo which filter values a "child" topic should use by setting a "scope filter" on the "parent" topic

  • When you publish, you set the filters and include all of the values that you want to use in the publication.

When you have read the example and understand the principles of scoped filtering, you can apply it to your own content. The workflow you should follow is:

  1. Make sure scoped filtering is enabled. It is enabled by default, but it may have been disabled on your Paligo instance.

    Select Layout and then edit the layout that you are going to use. Make sure the Enable scoped profiling/filtering option is set to Enabled or Default. You can find the option in the Classes and Attributes settings on HTML layouts and in the General > Filtering and taxonomies settings for PDF.

  2. Organize your publication structure so that you have "parent" topics (high level) and "child" topics (lower level).

  3. Apply filters to your "child" topic elements.

  4. Apply the "scope filters" on "parent" topic elements. Typically, you should set the scope filters on the section element.

  5. Publish your content and include the filter attributes that are set on the "scope filters" and all of the filter values that should be used.