Skip to main content

Scoped Filtering

Scoped filtering is a special type of filtering that's designed for this scenario:

  • You reuse the same topic in multiple places in your publication

  • You want each instance of the topic to be filtered differently, depending on its position in the publication.

For example, you might have an "installation" topic that appears in a "Windows" section of your publication and also in a "macOS" section. You want to filter out macOS content when the topic appears in the "Windows" section, and then filter out "Windows" content when the topic appears in the "macOS" section. To make this possible, you need scoped filtering.

Scoped filtering works by using the hierarchical structure of your content to define which filters to apply. You position the topic you want to use in several places so that it is always a child of another topic. Paligo uses the filters applied to the parent topic to determine which filters to apply to the child.

To use scoped filtering:

Enable Scoped Filtering

To use scoped filtering, you need to make sure it is turned on in the Layout you are going to use for publishing.

Note

For PDF output you find this setting: General / Filtering and taxonomies / Enable scoped profiling / filtering.

Note

For PDF Layouts, the option is in a different location:

  1. Select General in the sidebar.

  2. Select Filtering and taxonomies.

  3. Look for the Enable scoped profiling/filtering setting.

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the Layout you want to update or Create a Layout.

    Tip

    You can copy the URL of the Layout Editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the Layout settings.

  3. Select Classes and attributes in the sidebar.

    Classes_and_Attributes.png

  4. Set Enable scoped profiling/filtering to:

    • Yes to turn scoped filtering on.

    • No to turn scoped filtering off.

    • Default to inherit the value for this setting from the base Layout. The base Layout is either a built-in Layout provided by Paligo or another custom Layout, see Layout Relationships - Base, New, Duplicate.

    Enable_Scoped_Filtering.png

  5. Select Save.

Set Up Scoped Filtering

To set up scoped filtering, you need to create a publication your content arranged as parent topics and child topics. The topic you want to reuse in different places has to be a child topic. For example, in the following publication, the same "Specifications" topic is reused three times. In each case, it appears as a child of a different parent topic. You will then need to apply your choice of filter attributes and filter values to the parent topics as well as the child topic.

reusing_the_same_topic_several_times.webp

To show you how this is set up, we will give you step-by-step instructions. It is easier to follow with an example, so we will include one that filters based on the operating system being macOS or Windows.

Note

The instructions use filter attributes and filter values set in the Element attributes panel in each topic. But if you prefer, you could set up taxonomy filters for filters at the topic-level. You would need a taxonomy tag to represent the filter attribute (type) and child taxonomy tags to represent the filter values. For details on using taxonomy tags for filtering, see Taxonomy Filters.

We assume that you already know how to create and organize publications and topics. You should also have already enabled scoped filtering in your Layout, see Enable Scoped Filtering.

  1. Create a Topic that will serve as a parent topic.

    For these instructions, we will use two example parent topics: "Installing on MacOS" and "Installing on Windows".

  2. Create a topic that will serve as a child topic. This is the topic that is going to be reused in more than one place in your publication.

    For our example, we will use a child topic named "Operating system".

  3. Create a publication and add the parent topic(s) and child topic to it. You can add the child topic many times, but it must always be a child of one of your parent topics.

    A publication structure. At the top is the publication icon labelled 1. At the next level down is an Installing on macos topic labelled 2. Also at this level is an Installing on Windows topic. These are the parent topics. The parent topics both have the same child topic at the next level down. The child topic is called Operating system and is labelled 3 in both places.

    (1) is the publication, (2) is the first parent topic, (3) is the child topic, reused in two different places, and (4) is the other parent topic.

  4. Edit your child topic and apply filter attributes and filter values to the parts you want to filter in or out.

    In our example child topic, we have two itemized lists, one for macOS content and one for Windows content. We have applied the os filter attribute to the itemizedlist elements. We have set the filter value to macOS or Windows respectively.

    A topic with two itemized lists. Each list has a filter applied to the itemizedlist element. The top list has an os filter attribute with a macOS filter value.

    First itemizedlist element has os filter attribute and macOS filter value.

    A topic with two itemized lists. Each list has a filter applied to the itemizedlist element. The lower list has an os filter attribute with a windows filter value.

    Second itemizedlist element has os filter attribute and Windows filter value.

  5. Select Save. Save icon.

  6. Open one of your parent topics in the editor. Select its section element and use the Element attributes panel to give it:

    • The same filter attribute you used on your child topic, for example, os

    • The relevant filter value for that topic.

    Select Save when you have done that.

    With our example, we give:

    • "Installing on macOS" - its section element has the os filter attribute and macOS as the filter value. When we publish, we want Paligo to filter it so that it only includes the content that's relevant for macOS.

      Installing on macOS topic. Its section element is highlighted. In the Element attributes side panel, we can see that the section element has the os filter attribute with a macOS filter value.

    • "Installing on Windows" - its section element has the os filter attribute and Windows as the filter value. When we publish, we want Paligo to filter it so that it only includes the content that's relevant for Windows.

      Installing on Windows topic. Its section element is highlighted. In the Element attributes side panel, we can see that the section element has the os filter attribute with a windows filter value.

  7. Repeat the previous step for your other parent topics that have the same reused child topic.

    Your parent topics and child topic are now set up to use scoped filtering.

  8. Publish your publication and choose your Layout. You must use a Layout that has scoped filtering enabled.

    In the publishing settings, use the Profiling attributes section to include:

    • The filter attribute that you gave to your parent topics and the child topic

    • The filter values for all of the versions you want to include.

    For our example, this means we choose:

    • Filter attribute: os

    • Filter values: macOS and Windows.

    Note that we include all of the values that are needed for the publication. In this case, the first instance of the operating systems topic uses a macOS value and the second uses a Windows value. So we need to include both values.

    profiling-os-windows-mac.webp

    Important

    The parent-child relationship between topics is important for scoped filtering. When a topic appears in a publication many times, Paligo uses the filter attributes and filter values on the parent topics to figure out which filters to apply to the child topics.

The published output should:

  • Show the child topic multiple times in the table of contents

  • Filter the content in the child topic differently, depending on where the child topic appears.

op-system-mac.webp

Scoped filtering on an "Operating system" topic. The first instance of the topic appears as a child of a "Installing on macOS" topic. The "Operating system" topic is filtered so that it only contains information relevant to macOS.

op-system-windows.webp

Scoped filtering on the same "Operating system" topic, but reused later in the publication. It is reused as a child of a "Installing on Windows" topic and is filtered so that it only contains information relevant to Windows.