(This is part four of a five-part series dealing with content reuse in the Help Authoring Tool (HAT) MadCap Flare.)
Now that we’ve covered variables and snippets in depth, I want to talk about another tool that Flare includes that makes content reuse possible: conditions.
Conditions are settings that are applied to content. When a target is built, that content will either be included in the target, or excluded in the target, based on the conditions. For example, you can have some content that only appears in online versions of your help, and different content that appears only in print version of your help.
You may want to include a simple procedure in your online help, but for the printed guide, include additional paragraphs of information. You use the same topic; you just mark the additional content with a print-only condition, and exclude the print-only condition in your online output.
Conditions can be applied at the character level, paragraph level, or topic level. That means that you can choose to include/exclude a character, a word, a sentence, an entire paragraph, a series of paragraphs, or an entire topic.
In my Flare projects, I typically use four conditions:
- printOnly
- onlineOnly
- internalOnly
- doNotDistribute
I’ve already addressed the print/online only conditions. My internalOnly condition is associated with internal versions of our target files. In our release notes, for example, I add the bug number after known issues, or after resolved issues so we can track them from release to release. We don’t want this information published in our customer-facing version, but I do want it in the guides I release to our support staff (so if they have questions about a particular issue’s progress, they can open the bug tracking system to the specific issue).
I apply my doNotDistribute condition to text that I only want to see in the Flare editor. This content isn’t included in any Flare output; it just exists in the source files. This allows me to leave notes for myself in individual topics that I can easily see when I am looking at a topic. Because the condition is excluded from all my outputs, I never have to worry that these pubs-staff-only notes will be included in an output.
If you produce multiple versions of your content, you can use conditions to mark some content as basic and other content as advanced. You can then exclude advanced content from the basic guide, and include it in the advanced version of the guide.
The conditions available in your project are governed by the file(s) in the Conditional Text folder of the Project Organizer. Unless you are an advanced Flare user, you shouldn’t need to add an additional file to this folder. You can just modify the Default conditional text file.
To modify the Default file, double click it in the Conditional Text folder of the Project Organizer. Here you can add a new condition, or change the conditional text background color. This is the color that will be applied to the text, paragraph, or topic that contains the set condition.
As with variables, don’t change the name of a condition after you have added it to a topic, or the conditions won’t build correctly for those topics.
Save your changes by clicking the Save button on the application tool bar.
Now you are ready to apply the conditions to your content.
To add a condition to a character or partial paragraph in Flare:
- Open a topic, and select some content.
- From the Format menu, select “Conditions…”
- Select the condition you want to apply to the content.
- Click OK.
The selected content will have the background color for the condition that you applied. (If you don’t see it, be sure you’ve enabled the “show/hide conditional text indicators” option on your XML Editor tool bar.)
If you apply more than one condition to text, you will be able to see both condition colors in the background in a checkerboard pattern. If you don’t see both condition colors in this pattern, see the Note at the end of this post
Let’s say you have the following text (I’m include my conditions in brackets; this isn’t the exact code Flare uses, but it is easier to read and is close enough for the purposes of this discussion):
[Conditions="PrintOnly"]Jack and Jill went [/Conditions]
[Conditions="OnlineOnly,PrintOnly"]up the hill [/Conditions]
[Conditions="OnlineOnly"]to fetch a pail [/Conditions]
of water.
If my output includes no conditions settings, I’ll get the following text in my output:
Jack and Jill went up the hill to fetch a pail of water.
If my output includes the “PrintOnly” condition, but excludes the “OnlineOnly” condition, I’ll get the following text in my output:
Jack and Jill went up the hill of water.
If my output excludes the “PrintOnly” condition, but includes the “OnlineOnly” condition, I’ll get the following text in my output:
up the hill to fetch a pail of water.
Notice that the text “up the hill” has both conditions applied to it. If any condition is included in the output, the text will be included, even though another condition has explicitly excluded the condition. The include setting trumps the exclude setting. (See Note at end of post.)
To add a condition to a paragraph-level element in Flare:
- Open a topic, and right-click on the element’s block.
- From the context menu that appears, select “Conditions…”
- Select the condition you want to apply to the content.
- Click OK.
The selected block-level content will have the background color for the condition that you applied. (Again: if you don’t see it, be sure you’ve enabled the “show/hide conditional text indicators” option on your XML Editor tool bar.)
When using block-level conditions, if you apply two conditions to a block, you’ll see a checker-board mix of the condition colors, so you can see that multiple conditions apply. Remember: if your output includes any of those conditions, the block will be included in the output, even if the other condition is explicitly excluded.
To add a condition to a topic in Flare:
- Open the Content Explorer.
- Select a topic (or a folder).
- Press F4 (or right click on the topic, and select Properties).
- Open the Conditional Text tab.
- Select the condition you want to apply to the topic/folder.
- Click OK.
The selected topic or folder will have the condition color appear in the box next to the topic title in the Content Explorer. If you apply more than one condition to a topic or folder, you’ll see multiple colors in this box.
When you exclude a topic from a target, then that topic won’t be copied when the target is built. This can be important if you are providing the files to your clients and you don’t want them to have copies of the files that are only included in the “advanced” version of your project. (It is important to note here that all files in the project are included in all online output versions if they aren’t excluded at the topic level. This allows you to link to files in your help system, even if they aren’t listed in your TOC.)
Conditions can get a bit complicated, and I hope you’ve been able to follow through to the end on this one. It is, however, their complexity that allows them to be powerful tools in your content reuse tool box. You will notice that I’ve not discussed snippet conditions in this discussion. I think Snippet conditions are different enough from your standard conditions, that I want to discuss them in a separate post to try to keep their differences separate. Suffice it to say that there are even more options for conditions with your snippets (new functionality in Flare V3.1).
Now you have the power to use variables, snippets, and conditions so you can use a single source for your content and still publish it in multiple formats, with different content depending on the output. This is content reuse at its finest!
Come back tomorrow and we’ll talk about a sample project where we put all of this together to create several separate output products using the content reuse skills we’ve been discussing in this series.
Day 5: Wrap-up
—
NOTE: This is an update to my original post, which corrects some information I originally included. When you apply the condition settings properly, the INCLUDE condition trumps the EXCLUDE condition. In order to apply the settings properly, you must select each chunk of text separately and apply the conditions to it.
In our example, you would select “Jack and Jill went” and apply the PrintOnly condition. Then you would select the “up a hill” and apply both conditions. Then you would select “to fetch a pail” and apply the ScreenOnly condition. When you have done this properly, you will see a checkerboard background comprised of both colors. That is how you know you applied your conditions correctly.
Instead, if you were to select “Jack and Jill went up a hill” and applied the PrintOnly condition, then selected “up a hill to fetch a pail” and applied the ScreenOnly condition, you would have applied the conditions improperly. The background would only show one color, and the conditions will not be applied correctly in your output.
The tip here is to watch the background. If you see the checkerboard background with both condition colors, you’ve done it correctly. If you don’t both colors in the background, you’ve done it wrong.
When you are working in a topic in the XML editor, you can use the Context Menu to quickly create links and cross-references; the process is the same for both.
