Single Sourcing with MadCap Flare – Part 3 - Placeholders

Another Flare feature that supports single-sourcing is placeholders, which Flare offers in two forms – variables and snippets. Placeholders let you insert the same content in multiple places in a project, such as multiple topics, and automatically change that content everywhere with just a few mouse clicks.

For example (from the introductory post), let’s say that you’re documenting a new product whose pre-release code name is Longhorn. You write the word “Longhorn” in hundreds of places throughout the documentation.

Then, just before release, Marketing changes the product’s name to Vista. You now have to search the documentation for all instances of “Longhorn” and change them to “Vista”. It’s easy – just do a search and replace.

But what if you misspelled “Longhorn” several times? A search and replace won’t fix that. You could do a fragmentary search and replace – search for “Long” – but that would give many false hits. 

Or, let’s say that you have to repeat the same set of steps in multiple topics. Easy – type the steps once, then copy them and insert them in the appropriate topics. But what happens when one of the steps changes? You have to find each insertion and change it. But how do you know where you inserted the material. You might keep track of the insertions but that calls for an unusual level of management. You could again search for the insertions but that might again bring up false hits. Placeholders are a solution in both cases.

Variables

The simplest placeholder is the text-only variable. In the first example, rather than typing the product’s name over and over again, you’d create a variable called, perhaps, productname, and set its definition (its value) as “Longhorn”. You’d then tell Flare to insert the value of the productname variable wherever you wanted the word “Longhorn” to appear in a topic or other file.

Then, when Marketing changes the product name, you’d simply change the value of productname from “Longhorn” to “Vista”. Flare then automatically changes the “wording” everywhere you inserted the variable. You don’t have to keep track of the insertions – Flare does that.

Variables are easy to create and use. What can be tricky is defining them. For example, what do you do if you need to use a variable as a possessive – if you want to say “Longorn’s features include…” Do you create two variables called productname and productname_possessive with values of Longhorn and Longhorn’s, or do you use the single productname variable and type “’s features include…” and insert the productname variable in front of the “’s”? Either approach works; you just have to define which approach to use and get all authors to agree.

Flare stores variables in a file called a VariableSet, with an extension of flvar, accessible from the Project Organizer pane. You can create multiple VariableSet files if you want to categorize multiple variables or simply break multiple variables into smaller groups.

Several points regarding variables:

• Variables usually have one value but you may need more sometimes for different outputs. For example, you might be generating US and Canadian outputs and have a variable called country. You specify that the value of that variable is US. But if you’re generating Canadian output, you’d want to change the value to Canada. You can override the US value on the Variables tab of the Target Editor but it’s a good idea to minimize the typing needed to specify output settings. The solution is to create the country variable, specify its value as US, but then click the third icon, Add Variable Definition, on the VariableSet Editor toolbar. You’ll see a second instance of the country variable, greyed out, and can now type the additional value, here Canada.
• How then do you tell Flare what value to use for a particular output target? On the Variables tab of the Target Editor, there’s a dropdown link to the right of any variable that has multiple values. Click that dropdown link and select the desired value.

• In addition to the standard variables, you can also specify date and time variables. One common use is to add a variable that specifies when the output was generated and that’s automatically updated. Click the second icon, Add DateTime Variable, type the name, such as Generated On, then click in the Definition field. When the Edit Format dialog box opens, type the format – click the I icon for help – then specify when to update the variable.

Snippets

Snippets are similar to variables but more powerful because they can contain anything you’d enter in a topic – text, lists, images, tables, links, formatting, and so on – including variables. In example two above, rather than typing the steps, copying them, and pasting them into the appropriate topics, you’d create a snippet called, for example, task1_steps. You’d then insert the task1_steps into the appropriate topics. When the time came to change one of the steps, you’d change it in the snippet itself. Flare would then automatically change the “wording” everywhere that you inserted the snippet. Again, you don’t have to keep track of the insertions – Flare does.

Each snippet exists in a separate flsnp file that’s accessible from the Resources folder on the Content Explorer. (You can put the snippet files anywhere you want within the project’s structure. I just find it simplest to store them in the Resources folder.)

Several points regarding snippets:

• You can create text snippets and block snippets. A text snippet consists of one paragraph of text or less. If you insert a text snippet on a new line or in an existing paragraph, it keeps its structure as a line of text. A block snippet consists of two or more paragraphs of text or other element followed by a return, such as a graphic. If you insert a block snippet on a new line, the snippet retains its paragraph structure. However, if you insert a block snippet in an existing paragraph, the block snippet paragraphs become run together.

• As noted above, a snippet can contain a variable. However, because you can assign conditions to snippets and variables, it’s possible to have a snippet to which you’ve assigned a condition to be excluded for a particular output but that contains a variable to which you’ve assigned a condition to be included for that same output. In such a conflict, Flare will default to an include so it will display the snippet because it contains the variable. The problem here is a management one; you’ll be wondering why that snippet displayed in the output when you thought you’d excluded it. Keep careful track of how your snippets, variables, and conditions interact.

• If you have numerous snippets and need to modify one, it can be hard to pick out the right one. The shortcut is to find one instance of the snippet, right-click on it, and select Open Link. This immediately opens the correct snippet file, saving you the trouble of hunting for it.

• Snippets can solve one limitation of variables. What if you want to end a step in a procedure by telling the users to “Press Enter.” You might create a variable called actionstep, for example, whose value is “Press Enter”. But what if you want the action step’s value to be “Press the Enter icon” followed by the actual Enter key icon. A variable is text, so that won’t work. However, you could create a snippet called actionstep that contains both the text and the icon.

As with conditions, common problems with placeholders are in design and management. We often give placeholders names that are not clear. The result? Other authors using the same set of variables or snippets won’t find what they’re looking for and wind up creating duplicates, which complicates project management. A related problem lies in not documenting the rules and logic to use if an author really does need to create a new variable or snippet. As with conditions, when you leave and a new author comes on the project, they may send the project off the rails because the lack of documentation makes it easy to make mistakes.

That’s it for placeholders. Next up – Flare Project Import, one of Flare’s coolest and least-known features.