Category Archives: Flare for Programmers

material about MadCap Flare and document automation

Read the book!

XML Press has published MadCap Flare for Programmers: A guide to getting the most from Flare by Thomas Tregner and David Owens.

MadCap Flare for Programmers cover

I’m pretty excited about this. We cover the core subjects of this blog, often in greater detail. Some of the examples will look familiar but with more background information and deeper explanations. Other examples are completely new. You can read the list of chapters at the book’s page at XML Press.

If you want a narrative to help you begin scripting, automating, or programming in the context of MadCap Flare, MadCap Flare for Programmers is your starting point.


  • Flare projects, the key items in Flare projects, and the underlying markup
  • Generating content with code
  • JavaScript with Flare web outputs.
  • Flare plugins including a step-by-step Hello World walkthrough and more advanced examples
  • Code samples

Fun with Online TOCs!: #4, Single Page Scrolling Navigation Using XHTML Book and Bootstrap Scrollspy

My manager asked me to build a prototype single page Flare output that implements a right-hand navigation that updates with scrolling. The example I was given was the documentation for the Bootstrap library. The documentation for Bootstrap uses Bootstrap. We used Bootstrap too. Here is how the prototype looks. The link after this image is a video clip of the scrolling behavior and the link after that is a live copy of the output.

See It


Video: Single Page Scrolling Example

Output: Single Page Example

Try It Yourself

You can download a sample project from BootstrapExample.flprjzip.

To change the content, you can adjust the topics in the Content.fltoc TOC. The XHTML Book target (SinglePage.fltar) is configured to build an output for another TOC (Master.fltoc) that contains Content.fltoc. If you want to make other kinds of adjustments, read the next section for more details about how this example works.

When you publish this output, you must manually copy some of the JavaScript files to the appropriate relative location. You may want to adjust the the paths in the example to suit your needs to reuse the script for multiple outputs.

There is a comments section or you can email if you need more guidance.

Build One Yourself

Before jumping into the JavaScript part, let’s firstly create a single page output from Flare. If we decide to manage all our content from a single topic, there is no problem using any of the outputs to generate a single HTML file. But that defeats many of the benefits of using Flare and topic-based authoring. Rather than manage content in a single topic, let’s use a target type that will define a single page output from a TOC of many topics.

That target type is called XHTML Book. But we won’t be using the book viewer. You might say we are breathing new life into this target type.

We are going to use the generated XHTML file and CSS and omit the TOC that can be generated at the top of the content. Let’s work up to that point and then do our scripting.

Create a project. Use the Empty template. In Flare 10, we can’t select XHTML Book as the default target type from the New Project Wizard.

Create some topics in the project. Let’s throw in some different heading levels for good measure.

We’ll create a new TOC and add those topics to the TOC.

We’ll reference the new TOC in the default TOC. The reason is we want to bookend the content TOC with some other utility topics but keep those from clouding the authored content. We can reuse those utility topics for other single page outputs.

Now we’ll add an XHTML Book target.

And we’ll explicitly reference the default (outer TOC) from the target. This is just to ensure that one is always used.

We’ll select Modern.css as the Master Stylesheet.

We’ll deselect the option to generate a TOC proxy and the other proxies.

Now we have the basis for our single page output.

Let’s build the target to see what we get. But we won’t view the output with the book viewer. Instead, we’ll open the output folder and look at the *.htm file.

Let’s download Bootstrap and place it in our project in the Content\Resources folder.

Next we’ll create those two bookend utility topics mentioned earlier. We’ll call those Scripts0.htm and Scripts1.htm. In the outer TOC, we’ll put Scripts0.htm before the wrapped TOC and Scripts1.htm after the wrapped TOC. For most online outputs we could use a Master Page. But there is no Master Page option for XHTML Book targets. This is a “book” target. It uses Page Layouts. The outer TOC will serve as our “Master Page.”

Now we’ll remove the headings from Scripts0.htm and Scripts1.htm.

In Scripts0.htm, we’ll create script elements to load jQuery from a CDN (Content Delivery Network) and to load Bootstrap from the copy in the project. jQuery is a dependency for Bootstrap so that one goes first.

In Scripts1.htm, we’ll add this markup to form the outer elements for our navigation and to load the script (single-page.js) we are about to create.

The menu that updates with scrolling will appear in the div element in the preceding markup. The script adjusts the markup after it is loaded. In particular, we are clearing out name attributes used for bookmarks and replacing those with id attributes. Then we are building the navigation with JavaScript and Bootstrap.

We’ll also place this script in the Content\Resources folder in the project. In the example a subfolder is used. Much of this script adjusts the markup of the XHTML Book *.htm file to suit our needs. Many of the changes are to links and destinations. The script converts some of the cross reference information to true links. This involves sanitizing the strings for characters that are not valid in URL encoding.

You may run into issues with some types of links in your content. You’ll have to adjust the script to handle those. This script covers the scenario where there is an absolute link with some of the more common schema names. The script leaves those alone.

There are only two levels in the navigation. When the script builds the menu items, it places links in either the first level or as a child of a first level entry. First level entries are li elements with a link and a ul for children. Second level entries are li elements with links placed in a first level entry’s ul. The script places links to h1 elements in the first level and links to h2-h6 as second level entries. But the script can be adjusted if the division should be be somewhere else. To accomplish that, edit the condition in the inner if statement to include other tags. Look for the comments to find that section of the script. Right now the condition is as follows.

But to place h2 elements in the first level, the condition could be changed to this.

Scrollspy is started with the following line.

Some content may run into issues where the navigation tracks up an entry when a link in the menu is clicked. The overcome that, adjust the offset.

Here is the entire script.

We’ll adjust the body element rules in Modern.css. This is so scrollspy plays well with the styling.

Then we’ll add this to Modern.css. We’ll append the following to define how the navigation appears. Notice the left borders are used to indicate the active parts.

A note about publishing. The script locations resolve locally. But we must manually copy the scripts for Bootstrap and our single-page.js file from the project and post those at the correct relative location. Scripts are not included in the output for XHTML Book targets. One way around that is to adjust the example to point to a CDN for Bootstrap and to place the JavaScript from single-page.js in the script tag in the utility topic.

There it is. We also used a smooth scrolling library in a version of our prototype to animate scrolling when links are clicked. That may be a short post at a later date.


Adjusting Flare 9 Plug-ins for Flare 10

There were some excellent additions to the plug-in API with version 10 of Flare and this blog will touch on that in later posts. But I want to make a quick note about a change to the API that you may need to address if you built plug-ins for version 9 and are planning to use those in version 10.

In version 9, there was an ICustomToolstrip interface.  Now there is an ICustomToolBar interface. This bothered me a little until I realized that although the change broke my version 9 plug-ins that used ICustomToolstrip, it eliminated a silly workaround I had to use to share code between buttons for custom toolstrips, now called custom toolbars and ribbon groups. Note that MadCap still refers to the classic UI as the Tool Strip (user) Interface.

Before there was AddToolStripButton(string, string, EventHandler). Now there is AddButton and it can use the same class that inherits ICommand as AddRibbonButton(string, ICommand, object, string, RibbonIconSize, string, string, string). This enables better code sharing for buttons on a toolbar and a ribbon group and eliminates the need for the EventHandler and silly path to share logic for the buttons that was necessary before. Dealing with toolbar buttons and buttons on ribbon groups is just a fact of life if you want to support both UI options in Flare.

In conclusion, I think a little bit of rework in existing plug-ins is a good thing in this case.

Read The Techwriting Engineer Blog

I want to draw your attention to another blog with some interesting posts about programming and scripting in the context of MadCap Flare. The Techwriting Engineer isn’t solely devoted to that. But here are three posts that the author, Mattias Sander, has selected that fit in with the theme of Flare for Programmers.

So consider subscribing to the feed for The Techwriting Engineer and let’s see what Mattias comes up with!

Fun with Online TOCs!: #3, Revisualizing a TOC by Upgrading to Flare Version 10

This doesn’t involve scripting or programming. I hesitated to include this post because it may come off as a promotion for the new version of MadCap Flare. But this series is about revisualizing TOCs and what better way to do that than to use out-of-the-box improvements?

The latest version of MadCap Flare includes an updated HTML5 target type that is more responsive than the previous versions.  It adapts more readily for viewing on smart phones, tablets, desktop monitors.

MadCap did not compensate me for this post and I have not yet received a copy of version 10 for the purposes of this blog. However, here is a marketing image provided by MadCap that shows the more responsive output.

responsiveOutput_620px wide

Notice the behavior of hiding the TOC on smaller devices and the emphasis on the previous and next buttons in the example skin. Have you tried it yet? What do you think? Let me know in the comments.

So far in this series we have explored revisualizing TOCs with jQuery UI draggable, arbor.js, and an upgrade to version 10 of Flare. I think there are plenty of interesting JavaScript libraries to aid in revisualization. That will probably be the focus of the upcoming posts in this series. But if you have other thoughts about ways to revisualize TOCs, especially in online outputs, let me know in the comments.


Fun with Online TOCs!: #2, Revisualizing a TOC with arbor.js

The arbor.js library is described on the arbor.js site as follows.

a graph visualization library using web workers and jQuery

A TOC is a graph. So let’s see what what we can do with arbor.js and TOCs. Here is how a first attempt turned out. The following is the main page. The first topic displays the graph.

Main page

Here is just the topic with the graph visualization. Notice you can drag the nodes on the graph around, at least as tested in the latest version of Chrome.

Topic 1

The project used to generate this output contains a copy of the arbor.js download. There is also a main.js file based on the example in the arbor.js documentation.

Flare HTML5 output uses RequireJS to load TOC data. Since the format for the TOC data files uses RequireJS define(), define() was used in the main.js script to get the TOC data. This script assumed a single chunk for the TOC. That was a big assumption. To apply this technique to any HTML5 output, the script would have to be adjusted. But this is an arbor.js example and traversing the TOC tree in HTML5 output is another topic. It would also be nice to reuse the loaded RequireJS modules instead of using require() again.

Probably the most desirable item to address is to create clickable or tappable links on the nodes. The script includes the relative path for the file in the graph node information. But the click and tap behavior to open the link was omitted from this demo.

Here is the portion of the script that gets the TOC data and creates graph nodes and edges.

But there are other things happening in main.js to define the graph. Those are described in the arbor.js documentation introduction and reference. The topic that displays the graph has script tags for arbor.js, the main.js file that defines the graph, and a canvas element that serves as the viewing area for the graph.

How would you use graph visualization with TOCs?

Fun with Online TOCs!: #1, Draggable HTML5 TOC Panes with jQuery UI

Does jQuery UI draggable work with HTML5 output?

It does, at least in the most recent version of the Chrome browser where it was tested. Here is a link to an example or you can try it in the iframe that follows. Go ahead. Click and drag the TOC.

Draggable TOC Demo

Here is what was changed in the default page for the output after it was built.

This CSS link and script tag were appended to the head element. The script loads jQuery UI. Pages that use jQuery UI also require jQuery. But the HTML5 output already includes a version.

Part of the div for the navigation resize bar was commented out. The bar doesn’t make as much sense if the panes are not connected.

Draggable behavior was added with jQueryUI and the navigation resize bar was hidden with a display:none style. This script was appended to the end of the body tag. The z-index for the navigation pane was bumped up so it will not get lost behind the content pane.

That was it. There wasn’t much to do. A bootstrapper for the JavaScript toolbar would be a nice follow-up for this little experiment. Some other finishing touches could be a drag handle and maybe some resizable behavior for the navigation and content panes. Those are possible with the jQuery UI library. But I just wanted to see if draggable works on a TOC pane.

Links for Today’s Scripting Webinar (October 2, 2013)


The Power of Scripts in MadCap Flare’s HTML5 Output

Key events and key codes

Clear a Flare HTML5 Search Field with the Escape Key

Toolbar Examples Project

Show-hide and effects with jQuery

Show and Hide with jQuery in HTML5 Output

Embellishing the jQuery Slides with Fade Effects

Finding elements and show and hide with JavaScript

Hide Some Flare HTML5 Output Glossary Tab Entries

Show and hide attached to an input

Version Filters in HTML5 Output

Version Filters in HTML5 Output (persisting display instead of toggling)

New Project Example That Handles Inline Elements

Rearranging elements with JavaScript

Sorting TOCs in an Output with JavaScript

Snippet parameterization with AngularJS

Snippet Parameterization for Flare HTML5 Output Using AngularJS


Create Topics in Bulk with a Plug-in

Note (3/13/2014): A change to the API for version 10 requires adjusting the code in this sample if the plug-in is to be used with version 10. The change is explained in Adjusting Flare 9 Plug-ins for Flare 10.

Sometimes you just want to create a bunch of blank topics all at once and put all of those topics in a TOC.







If you are interested in that sort of thing, you can create a Flare plug-in to add the functionality to MadCap Flare. If you want to play around with the code to create what is shown in the preceding screen shots, here is a sample solution and project:


If you just want to try it, here is a plug-in DLL: BatchTopics.dll and help for MadCap’s Plug-in API. Use the code or the plug-in at your own risk. No warranty is offered. Let me know what you think in the comments.

Edit (9/102013): There is additional information at MadBlog. Also the project and DLL were recently updated to fix a namespace issue.

Automating Imports

If you work with more than a few projects that import from a common project, you may want to automate importing from that project. Automating imports can be as simple as scheduling this command:

 How does that work? Isn’t madbuild.exe for generating output content?

Yes. But some other things happen when a target is built.

Flare targets have an Auto-Sync feature that enables running an import prior to generating content. Auto-Sync can be disabled for a target from the Target Editor. The setting is on the General tab, under Auto-Sync: Disable auto-sync of all import files. When not checked, the option is specified in the target file markup as a DisableAutoSync=”false” attribute and value on the CatapultTarget element. The value is true when the box is checked.

Flare imports have a setting on the Source Project tab called Auto-reimport before “Generate Output”.  Targets with Auto-Sync enabled will prompt an import specified by the import files with the Auto-reimport before “Generate Output” option selected. The markup for this option is AutoSync=”true” on the CatapultProjectImport element.

The command line executable that enables starting builds outside of the Flare user interface is called madbuild.exe. It is located in the folder where Flare is installed. When a target is built with madbuild.exe, Auto-Sync is still run if specified. However if the project is under source control, madbuild.exe does not prompt for a checkout as happens in the Flare interface. But more about that later.

By the way, this post is a follow-up to a previous discussion about batch files called Batch Files, madbuild.exe, and commands.

Setting up automated imports is accomplished by scheduling builds of targets that cause an import with Auto-Sync. Builds can be scheduled by placing build commands in a batch file and scheduling a call to the batch file with Windows Scheduler.

The target can be a throw-away that builds a one topic TOC. The output doesn’t matter. The target is just a means to get madbuild.exe to cause an import.

But I use source control and madbuild.exe does not prompt me to check files in or out.

Depending on your source control solution, you can automate that also. For example with Team Foundation Server and Visual Studio (Team Explorer), the executable is tf.exe and it is located in a Visual Studio folder.

One thing to watch out for is that not every file in a project should be checked in and out of source control. Some folders are local such as the Output folder in the root of the project and Users folders in the Project folder. The second example that follows shows this.

Build Commands


Build with TFS Source Control Commands