Skip to main content

Filters on Hierarchical Structures

When you are setting filters on your content, you need to be aware of how filters work on hierarchical structures, otherwise you may get unexpected results. A "hierarchical structure" is any structure that consists of a top-level "parent" element and lower-level "child" elements. These include lists, procedures, tables, and admonitions.

Procedure structure. There is a procedure element at the top level and it acts as a container. At the next level there are three step elements. Each step element has a child para element for the content.

The important rules with filters on hierarchical structures are:

  • If a parent element is set to be excluded from a published output, the entire structure is excluded.

    For example, you can't instruct Paligo to exclude a procedure element but include a step inside the procedure. If you filter out the procedure, the entire procedure is excluded, irrespective of the filters on the child elements in the structure.

  • If you want to filter out parts of a structure, make sure you apply:

    • The filters you want to use for each individual child item, such as a list item or a row in a table.

    • The same filters to the parent element that represents the hierarchical structure as a whole, such as procedure or informaltable. Set the parent element to have all of the filters and filter values of the child elements.

    We have included an example to show how this works.

When you understand the rules for using filters on hierarchical structures, you can use them in your content. For instructions on adding filters, see

Example 1. Filters on Table and Table Row Elements

Let's say you have a table with three rows and two columns, like this:

Model

Operating system

Acme 100

Android

Acme 200

Android, iOS

Acme 300

Android, iOS, Windows

The underlying code for the table looks like this:

 <informaltable width="50%" xinfo:market="Europe">
      <colgroup>
        <col></col>
        <col></col>
      </colgroup>
      <thead>
        <tr>
          <th>
            <para xinfo:text="260458">Model</para>
          </th>
          <th>
            <para xinfo:text="260459">Operating system</para>
          </th>
        </tr>
      </thead>
      <tbody>
        <tr xinfo:market="Europe">
          <td>
            <para xinfo:text="260460">Acme 100</para>
          </td>
          <td>
            <para xinfo:text="260461">Android</para>
          </td>
        </tr>
        <tr>
          <td>
            <para xinfo:text="260462">Acme 200</para>
          </td>
          <td>
            <para xinfo:text="260463">Android, iOS</para>
          </td>
        </tr>
        <tr xinfo:market="USA">
          <td>
            <para xinfo:text="260464">Acme 300</para>
          </td>
          <td>
            <para xinfo:text="260465">Android, iOS, Windows</para>
          </td>
        </tr>
      </tbody>
    </informaltable>

Look at the informaltable element, which is the parent element (container for the entire table). It has this market filter:

xinfo:market="Europe"

Look at the first row (tr) in the table. It also has this market filter:

xinfo:market="Europe"

Next, look at the second row (tr) in the table. It has no filter.

Finally, look at the code for the final row in the table. The tr has a filter set to:

xinfo:market="USA"

Now let's see how these filters work when you apply the filters and publish.

Publish and include xinfo:market:Europe

You publish the topic containing the table and, in the publishing settings, choose to include xinfo:market:Europe. Paligo publishes the table as:

publish-to-eu.webp

The third row for Acme 300 is not included. This is because:

  • The informaltable element has xinfo:market:Europe, and so is included.

  • The first row's tr has xinfo:market:Europe, and so is included.

  • The second row has no xinfo:market filter at all, and so is included.

  • The third row's tr has xinfo:market:USA. You did not set this to be included, so this row does not appear in the output.

Publish and include xinfo:market: USA

You publish the topic containing the table again. This time, you choose to include xinfo:market:USA. Paligo publishes the topic, but it does not contain a table.

This is because:

  • You told Paligo to include content that has xinfo:market:USA.

  • The informaltable has the filter xinfo:market:Europe, and so the entire table container is excluded.

  • Paligo cannot publish a child element if its parent is not included.

Just as you can't publish a paragraph without its parent topic, you can't publish a table row without its parent table structure. This same principle applies to all hierarchical structures, including lists and admonitions.

How would you get the table to publish with only the row for the USA market? Let's take a look.

Add xinfo:market:USA to the table and publish again

You need the table structure to appear when the xinfo:market value is Europe or USA. There are two ways to do this:

  • Remove the xinfo:market:Europe filter from the informaltable element

  • Add the USA filter value to the xinfo:market filter.

Here, we'll add the USA filter value.

You edit the table so that the informaltable element has two filter values: xinfo:market:Europe;USA.

You publish the table and again choose to include xinfo:market:USA. This produces:

publish-to-usa.webp

This is because:

  • The informaltable element has xinfo:market:Europe;USA. You set Paligo to include any content that has xinfo:market:USA, so the table is a match. It has one of the two specified values.

  • The first row (Acme 100) from the original table is excluded. It had xinfo:market:Europe and you told Paligo to only include content with xinfo:market:USA.

  • The second row from the original table is included as it has no xinfo:market filter.

  • The third row from the original table has xinfo:market:USA and so is included.