The fourth article in a five-part series, Paul Stoecklein has headed up the documentation department at MadCap Software since its inception, overseeing the development and publication of all online Help systems, PDF manuals, and video tutorials for all applications in the MadCap product family.
One great way to improve your Flare project is to take advantage of master pages. A master page is a file that you can use to add the same content to all of the topics in your online output. They can save you tons of time.
A master page usually include one or more proxies, which are simply placeholders for content that you add elsewhere in your project. They can also include text, images, and other content that you add above or below the main topic body proxy. They’re really easy to create and quite useful.
Many of you may already be somewhat familiar with master pages, and the most common way to use them—one master page associated with one target. However, master pages can be even more powerful than that. It’s possible to have multiple master pages, using a different one for different topics in your output.
When I first started using Flare, I had one master page for my online output. I added breadcrumbs above the topic body and miscellaneous information and links below it.
Using one master page is a pretty easy thing to do. You just add your content above or below the body proxy in the master page.
Then you open the target and point to that master page.
But after time, I found that I wanted the master page content to be different, depending on the topic that was open. For example, in the latest release of the Mimic 8 online Help, you’ll see a blue PDF Guide button at the top-right of most topics.
What you may not know is the PDF file that opens when you click this button is different for some topics. Depending on the topic that is open, the button may open the Getting Started Guide, or maybe it opens the Movie Editing Guide, or perhaps it opens the Touring the Workspace Guide, and so on. I accomplished that in part by having multiple master pages.
First, I created a master page that would serve as my primary master page. I added content to this master page that I wanted all of my topics to display. Knowing that I was going to create additional master pages, I turned some of the master page content into snippets so that I wouldn’t have to retype it each time.
Then for each PDF that I planned to generate from the project, I made a copy of my primary master page. Inside each of those master pages, I inserted my PDF Guide image in the upper-right corner, and I hyperlinked that image to the appropriate PDF file location.
Yes, it is possible to add multiple images into the same master page and use conditions to separate them in the output. I actually did this in many cases. For example, most MadCap products have a Getting Started Guide, so I created a single master page with images that link to the different Getting Started Guides.
But I have so many different PDFs related to MadCap’s different products, and I decided it would be confusing and difficult to manage if I put them all into the same master page. At some point you just have to decide whether you’re trying to single-source too much, at the expense of simplicity.
That’s how I ended up with multiple master pages.
But creating multiple master pages is just one part of the puzzle. Next, I had to tell Flare when it should use which master page.
I opened my target for the online output and I pointed to my primary master page. By pointing to this master page, Flare would use it for all of my topics, unless I told it otherwise.
So how did I tell it “otherwise”? Here’s how…
First, I opened my stylesheet and I created a class of the html style. For example, for our Mimic 8 online Help I created a class called “html.MimicMovieCreation.” I created this class because I have a bunch of topics that are included in a PDF called the “Movie Creation Guide.” And when you open any of those topics in the online output, I want the PDF Guide button to open that specific PDF file. Within my html.MimicMovieCreation style class, I pointed to the correct master page.
Stylesheet Editor:
Internal Text Editor:
Then I located all of the topics where I want that button to show in the online output. In the Content Explorer, I clicked the Toggle Show Files button so that I could select multiple topics at the same time.
With my topics selected, I right-clicked and opened the Properties window pane, and on the Topic Properties tab I selected MimicMovieCreation, the name of my style class.
For the selected topics, I’m essentially telling Flare, “Instead of using my primary master page, I want you to look at this style that I created, and that style is telling you to use a different master page.”
This might be a somewhat complex case, one that you might never encounter yourself, but it does show the power and flexibility of Flare. If you can come up with a scenario involving different master page content for various topics, you can make it happen as long as you know how.
In my case, yeah, it was some extra leg work, but for the end users I like to think it makes life easier for them because they can more easily and quickly open a PDF that contains information that they’re looking at, rather than any old PDF.
So take a look and your own line output and ask yourself if you can benefit from having multiple master pages. Will it make life better for your readers? If so, you’ve found one more great way to improve your Flare project.
