Content Reuse In-Depth: Variables

(This is part two of a five-part series dealing with content reuse in the Help Authoring Tool (HAT) MadCap Flare.)

Yesterday I gave an overview of what content reuse is, and why it is important, and who should use it. Today we are discussing a specific way MadCap Flare allows you to reuse content: variables.

I start with variables, because they are a simple concept that is probably quite familiar to you. Snippets, which we discuss tomorrow, are like advanced variables, so it is important that we have a basic understanding of variables first.

If you have worked in FrameMaker, or have done any programming, you are already familiar with the concept of variables. A variable is code that you insert in your Flare topics that gets replaced when the project is built (prepared for output; when you develop content in Flare, the content isn’t in a usable form until you build an output).

For example, you might use a variable in your project to represent the product name or version number. Every time you want to use the project’s version, instead of typing in the version number, you insert the version variable. When the version changes, you modify the variable in one location, and the project is instantly up-to-date. No more find-and-replace projects where you hope you catch every reference.

Suppose you have a product that gets re-branded and then re-sold. I once worked for a company that created portal software for educational institutions. Each school branded their portal. Using variables, you can refer to the portal name generically, and create a separate output for each client with their portal branding information in the variable settings.

So, how do I use variables in Flare? Keep reading.

Flare groups variables into Variable sets. They are accessed (or added) in the Project Organizer, in the Variables folder. By default, your project contains a variable set called “MyVariables.” You can right-click on the Variables folder to add a new variable set, or you can just double click “MyVariables” to open the generic set. (For starters, it is probably easier to just use one variable set, instead of trying to incorporate multiple variable sets. Multiple variable sets is an advanced topic, not covered in this series.)

By default, there are two variables in MyVariables: CompanyName and PhoneNumber. Click the New button to add a variable to the set. Click in the Definition cell to change the variable’s definition.

So if you want to add a variable for your product Name, you would do the following:

  1. Click the New item button.
  2. Click in the Name cell (on the word NewVariable). Replace NewVariable with the name of your variable (in this case something like ProductName)
  3. Click in the Definition cell. Type in the variable definition (like ACME Explorer).

If you want to add a separate variable for the version number, you’d just repeat the steps, but change the variable name and definition.

When you are editing a topic, you insert your variable by using the Insert menu, and selecting Variable.

You’ll see two variable sets: MyVariables and System. The MyVariables set contains all the variables you’ve set using the process described above. The System variable set contains variables like Date, and page number (for use in printed output).

Select the variable set that contains your variable, then select the variable you want to insert. Click OK. The variable is added to the topic at the cursor’s insertion point.

There is your introduction to variables in Flare. I highly recommend that you use variables in place of all your content that may change from release to release. I use the following variables in my projects:

  • Company Name
  • Windows installation directory
  • Linux installation directory
  • Product Long Name
  • Product Short Name
  • Product version

And before I set you lose creating variables to your heart’s content I leave you with a word of caution: If you change a variable’s name after you’ve inserted it into a topic, the link will break, and the variable will no longer be updated in those topics that contain the old variable name. Once you’ve inserted a variable into your topics, don’t change the variable name. (Obviously you can change the definition; that’s the whole point. Just don’t change what you CALL the variable, or the variables that exist in your project will break, and you’ll end up doing some fancy find-replace to update/fix the problem. Think about what you want to name your variable, and then don’t change it after you’ve begun inserting it into your project!

Tomorrow I’ll be back with information on Snippets–basically longer variables that can contain formatted text, images, etc. See you then!

Day 3: Snippets

Leave a Reply