Using Snippet Conditions

Snippet conditions are condition tags that you can apply to content within snippets. They are especially useful when the majority of the snippet content is identical everywhere the snippet is used, but there are some small differences in some places. This lets you use one snippet for many purposes, rather than having to create multiple snippets to account for the small exceptions. Whereas regular conditions are included or excluded at the target level, snippet conditions are included or excluded at the snippet or topic level.

  1. Create all of the condition tags that you plan to use for separating your snippet content.

    Note: The more variations that you will have in your snippet content, the more condition tags you will need to create. An average number is four to eight condition tags, but you may find that you require fewer or more tags than this for snippet content. It is always preferable to create more condition tags than you may need, rather than to realize later that you have too few. You can even create a separate condition tag set to be used specifically for holding your snippet condition tags (while keeping your regular condition tags in other tag sets).

    Tip: It is also a good idea to include the word "Snippet" somewhere in the name of a new snippet condition tag. This way, you can easily identify it, rather than confusing it with the regular condition tags that you use for other purposes (e.g., online output or printed output condition tags).

    See Creating Conditions and Adding Condition Tag Set Files.

  2. Create and open the snippet.

    See Creating New Snippets from Existing Content and Opening Snippets.

  3. Apply the necessary condition tags to the text or other content in the snippet.

    See Applying Conditions to Content.

    Tip: It is a good idea to click the Hide/Show Conditional Indicators button at the bottom of the editor so that you can clearly see where the different tags have been applied in the snippet.

  4. Do one of the following:

    This method is recommended in most cases. It allows you more flexibility and tends to be easier to maintain topics as time goes by. Snippet conditions at the snippet level override snippet conditions applied at the topic level.

    1. Insert the snippet into the necessary topic, or determine which topic already contains the snippet.

      See Inserting Snippets and Viewing File Links.

    2. In the topic, right-click the first instance of the snippet and select Snippet Conditions from the context menu. The Snippet Conditions dialog opens.

    3. If you want to exclude a condition tag from the snippet, click the Exclude check box next to it. If you want to make sure a condition tag is included in the snippet, click the Include check box next to it. The primary reason for having Include check boxes is to account for possible conflicts. Snippet conditions set on a snippet override snippet conditions set at the topic level.

      Example

      Let's say you are working in a topic that has several snippet conditions set at the topic level. When you insert an existing snippet into your topic, you notice that some of the text in the snippet is excluded using the condition tag Snippet1. However, the Snippet1 condition tag is also excluded at the topic level in the topic you are working on, so that text does not appear in the XML Editor or your output.

      Snippet conditions on individual snippets override those at the topic level. So in the topic you right-click the snippet and choose Snippet Conditions.

      In the Snippet Conditions dialog, you set the conditions on this snippet to include Snippet1. While Snippet1 will still be excluded at the topic level, in this particular snippet, you will be able to see the text that is marked with that tag.

      Note: If you want to create more advanced condition tag expressions, you can switch to Advanced mode. See Creating Basic and Advanced Tag Expressions.

      Warning: If you do not select any check boxes at all, all of the tags will automatically be included. If you include only some tags and exclude others, any remaining tags without check marks for either Include or Exclude will automatically be included. However, if you select Include for any of the tags (even just one) and do not select Exclude for any tags, all of the other tags that do not have Include check marks will automatically be excluded. If you want to be safe and always know that the correct tags are included or excluded, you can make sure that all of the tags have check marks with either Include or Exclude.

    4. Click OK.

    5. (Optional) Repeat steps b-d for the other instances of the snippet in your topic.

    6. Click to save your work.

    This method is good if you have snippet conditions set throughout a topic and you want to include and exclude the same conditions for the entire topic. Otherwise, it is recommended that you apply snippet conditions at the snippet level.

    1. Insert the snippet into the necessary topics, or determine which topics already contain the snippet.

      See Inserting Snippets and Viewing File Links.

    2. After you determine that a particular topic should display only certain tagged content from the inserted snippet, open the Content Explorer and select the topic file.

      Note: If there are several topics that you know in advance will include a particular snippet condition tag, you can open the File List window pane (View > File List) instead and select all of those files at the same time.

    3. In the local toolbar, click . The Properties dialog for the topic opens.
    4. Click the Snippet Conditions tab.

    5. If you want to exclude a condition tag from the topic, click the Exclude check box next to it. If you want to make sure a condition tag is included in the topic, click the Include check box next to it. The primary reason for having Include check boxes is to account for possible conflicts.

      example

      Suppose you have two condition tags—one called "Beginner" and another called "Advanced." Let's say that you have a snippet containing three paragraphs. You apply the Advanced tag to the first two paragraphs, and you apply the Beginner tag to the last two paragraphs.

      You have created a topic called "Advanced Set Up." For this topic, you obviously want to include all snippet content associated with the Advanced tag, but you want to exclude snippet content associated with the Beginner tag.

      By default, Flare will include snippet content associated with both tags, unless you tell it not to. So you tell Flare to exclude the content associated with the Beginner tag. The problem is the middle paragraph from the snippet mentioned above. It is associated with both tags. You have told Flare to exclude content associated with the Beginner tag, and it will do so, overriding the default. But you want to make sure that paragraph is included in the "Advanced Set Up" topic. That is why you need to make sure you select the Include check box next to the Advanced tag.

      Warning: If you do not select any check boxes at all, all of the tags will automatically be included. If you include only some tags and exclude others, any remaining tags without check marks for either Include or Exclude will automatically be included. However, if you select Include for any of the tags (even just one) and do not select Exclude for any tags, all of the other tags that do not have Include check marks will automatically be excluded. If you want to be safe and always know that the correct tags are included or excluded, you can make sure that all of the tags have check marks with either Include or Exclude.

      Tip: It is a good idea to create enough snippet condition tags in advance. If sometime later you realize you need to create additional snippet condition tags, you may find that you need to revisit all of the topics where you have already inserted snippets with conditions. Why? Because by default the snippets containing the new tags may be displayed in all topics unless you specify otherwise.

    6. Click OK.

example

Let's say that you have a table with 15 rows and four columns. Suppose that the table needs to be included in 40 topics. Rather than copying and pasting the table 40 times, you create one snippet containing the table and insert it into those 40 topics. However, suppose that in 30 of those topics, you need to add three more rows to the table to explain something. In the remaining 10 topics, the three additional rows are not necessary. Otherwise, the table content is the same in all 40 topics. What do you do? You have a few options.

The first option is to add a note to the table explaining that the three additional rows are intended only for some of the topics but not others. However, this might be confusing to your readers.

The second option is to create two separate snippets—one for the 30 topics and another for the 10 topics. However, this means that you need to maintain identical information in two different places. And that is no way to single-source your content.

The third option is to create snippet conditions. Here is how you might do it in this example.

  1. Create a condition tag called "Additional Rows." See Creating Conditions.
  2. Open the snippet and add the necessary three rows to the table. See Opening Snippets and Inserting Table Columns and Rows.
  3. Using the table row structure bars, apply the new condition tag to the additional three rows. See About Structure Bars and Applying Conditions to Content.
  4. Use the File List window pane (View > File List) to select the 30 topics requiring the additional rows, and open the Properties dialog. See File List Window Pane and Properties Dialog (Topics).
  5. Select the Snippet Conditions tab.
  6. Next to the new condition tag, click the Include check box.
  7. Use the File List window pane to select the 10 topics not requiring the additional rows, and open the Properties dialog.
  8. Select the Snippet Conditions tab.
  9. Next to the new condition tag, click the Exclude check box.
  10. After you save all of your changes and generate the target, you will notice that the three additional rows are displayed only in the 30 topics where they were included. See About Building and Publishing Output.

Example

Let's say you are writing a user guide. There is a three-step process that users need to repeat very frequently, so you create a snippet for those steps. However, there occasionally is a fourth step in the process, where users can optionally select an extra check box before completing the process. You sometimes need to include this process multiple times in the same topic, so you create a snippet for the four-step process, and apply a condition to the optional step.

You add your snippet to the topic...

...and then exclude the snippet condition on the second instance of the snippet. By doing this, you won’t see the optional step in that instance of the snippet.

Later, if you need to edit the content, you only have one snippet to edit.

For more information see About Snippets, Creating Conditions, and Applying Conditions to Content.

Tip: If you are using snippet conditions, you may want to enable snippet condition indicators from the Show tags drop-down in the XML Editor. This command enables or disables a marker that overlays snippets that have snippet conditions applied to them.

If you enable this indicator, you will see it on snippets if you have snippet conditions enabled at either the topic level or the snippet level.

Note: Remember that snippet conditions only apply to a particular instance of a snippet. If you add new snippet conditions to an existing snippet, be sure to use the Link Viewer to check that the content in other instances of the snippet is still visible (or hidden) the way you want it to be. See Viewing File Links.

Note: You can generate a report to see topics in your project that contain snippet conditions at the topic or snippet level. See Reports and Generating Reports.