menu   UA Europe - Training & Consulting
UA Europe - Training & Consulting
UA Europe - Training & Consulting

Specialists in
User Assistance
technology

Condition Tag Expressions in MadCap Flare

Published in ISTC Communicator, Summer 2013

Introduction

Condition Tag Expressions are what you use in your Flare target settings to filter content out of the output for that Target. I decided to write about them for this issue's MadCap Column for two reasons: the first is that the recent release of Flare 9.0 introduced the option of using an Advanced Condition Tag Expression, which gives you more control over what is included and excluded from the output. The second reason is that, at the inaugural MadWorld Conference in San Diego, California (April 2003), I found myself debating with another speaker the merits of selecting the Include checkbox within Basic Condition Tag Expressions - and that led me to investigate the issue more deeply.

Background

Conditional processing works in Flare as follows:

  1. You create the condition tags by storing them in one of more Condition Tag Set (.flcts) files within the Project Organizer.
  2. You then apply the condition tags to the appropriate content items (topics, images, paragraphs, etc.).
  3. Finally, you configure a Condition Tag Expression within each target to filter out the items that you do not require in the output for that target.

In Flare version 8 and earlier, the only way to configure a Condition Tag Expression is to select the required Exclude or Include checkboxes for the conditions as shown in the screenshot below.

Basic Condition Expression

In Flare 9 and higher, there are now two alternative ways of specifying a Condition Tag Expression: you can either use the old way (now called Basic), or use the Advanced option by typing a Boolean expression (which means combining the conditions using and, or and not operators).

You can have as many different conditions as you need within a project, and normally the conditions can be organised into groups of the same type. For example, you might have conditions of Print, HTML, and Mobile that form a group because they all express the medium for which the content is appropriate. Incidentally, these groups are analogous to the attributes available in DITA for conditional processing, which include product, audience, platform, and revision.

Top of page

To include or not to include

One of the key principles underlying both types of Condition Tag Expression is that all content items are included by default in the output, unless explicitly excluded by the condition tag expression. It would seem at first glance, therefore, that selecting the Include checkbox for any condition would be redundant and unnecessary. However, this is not necessarily the case due to a second key principle of Basic Condition Tag Expressions, which is that the Include setting always takes priority over the Exclude setting in cases where a content item has two or more tags with conflicting Include/ Exclude settings. And so an Include setting could potentially be needed to include an item that might otherwise have been excluded.

My own experience is that selecting the Include option for any condition is more likely to cause undesired results than to provide any benefit, so I normally recommend leaving neither checkbox selected for conditions that you want to include. Whether this is the correct strategy for you depends on which system you use for applying conditions.

Let me explain by looking at some example scenarios.

Top of page

Scenario 1: One group of mutually exclusive conditions

In this most basic of scenarios, our Flare project has two conditions of the same type: PrintOnly and HTMLOnly.

We are using these conditions to tag content that is specific to either the Print or HTML medium. In this case the conditions are mutually exclusive — you would never apply both conditions to the same type. This is because, if you wished to indicate that a content item was appropriate to both the Print and HTML mediums, you would simply leave the item untagged (remember, untagged items are included by default in the output).

Let's imagine now that we are configuring the Condition Tag Expression for the PrintOnly target — we want content tagged with the HTMLOnly condition to be excluded, and all other content items (either untagged or tagged with PrintOnly) to be included. We can achieve this using a Basic Condition Tag Expression by simply selecting Exclude for HTMLOnly. Selecting Include for PrintOnly will not make any difference to the output, and is totally redundant.

Top of page

Scenario 2: One group of potentially overlapping conditions

Let's say that our Flare project now has three conditions, X, Y, and Z, which we are using to tag content that is applicable to a particular product (X, Y, or Z). In this case, we may tag an item with two conditions if that content is applicable to two of the products but not to the third. We will leave content untagged where is it applicable to all three products.

Now let's assume that we want to configure a target to build the Help for product X. Using a Basic Condition Tag Expression, we would start by selecting Exclude for Y and Z. But then, should we select Include for X?

The answer is actually a definite "yes" in this case. If we don't, then any content item that has been tagged with X and Y (for example) will be excluded — whereas, since it is applicable to product X, it should be included in the Help for product X.

Now let's consider a scenario of increased complexity...

Top of page

Scenario 3: Two groups each containing mutually exclusive conditions

Our project now has two different groups of conditions: a medium group containing two conditions, PrintOnly and HTMLOnly, and a region group containing EuropeOnly and AsiaOnly. Since there are only two conditions within each group, these conditions are mutually exclusive for the same reasons that I gave within Scenario 1.

To help us understand this scenario fully, let us simplify our example as far as possible by imagining that the project contains only nine topics tagged with the following conditions:

  • Topic 1 [No conditions]
  • Topic 2 PrintOnly
  • Topic 3 HTMLOnly
  • Topic 4 EuropeOnly
  • Topic 5 AsiaOnly
  • Topic 6 PrintOnly EuropeOnly
  • Topic 7 PrintOnly AsiaOnly
  • Topic 8 HTMLOnly EuropeOnly
  • Topic 9 HTMLOnly AsiaOnly

Now, to build an HTML-based Help system for a European audience, how should we configure the conditions in our target? Using a Basic Condition Tag Expression, we would not hesitate in selecting Exclude for PrintOnly and AsiaOnly. But should we select Include for HTMLOnly and EuropeOnly? Let's see what happens if we do:

Topics 1, 3, 4, and 8 are included as required, but unfortunately so is topic 6 despite the fact that this topic is tagged as being applicable only to the Print medium - this is due to the fact that EuropeOnly has been included, and this takes priority over the exclusion of PrintOnly. For similar reasons, the unwanted topic 9 is also included. If instead we had selected neither the Exclude nor the Include checkbox for HTMLOnly and EuropeOnly, the correct set of topics (1, 3, 4, and 8) would have been included in the output. So my recommendation to leave neither checkbox selected for conditions that you want to include proves successful on this occasion.

Top of page

Scenario 4: Two groups each containing potentially overlapping conditions

Let's say that our project now has a region group of conditions containing US, Europe, and Asia, and a product group of conditions containing X, Y, and Z.

Assuming that any content item may be tagged with more than one condition from each group, the situation has suddenly become significantly more complex and challenging — to the extent that it is actually now impossible to achieve the required output for any given target by using a Basic Condition Tag Expression. This is why the arrival of Advanced Condition Tag Expressions in Flare 9.0 is so welcome. As an example, the Advanced Conditional Build Expression that you would use to build the Help for US-based users of product X would be:

(US OR NOT (Europe or Asia)) AND (X OR NOT (Y OR Z))

If you think you can achieve the same output using a Basic Expression (by selecting the Exclude/Include check boxes), it'll drive you mad trying. Let me know if you believe you have succeeded.

 

 

 

Horizontal line

Training and Consulting in MadCap Flare

UA Europe provides specialist consulting and training (either face-to-face or via the Web) in MadCap Flare.

 

Top of page