Tag Archives: 9.0

A First Flare 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.

With the release of MadCap Flare 9.0, Flare has a Plug-In API. With the API, you can add new Toolstrip and Ribbon menus. There are some hooks for the topic editor, the active document, and the current selection.

MadCap has posted documentation for the Plug-In API as a zipped HTML5 help system at: Download MadCap Flare API Documentation 9.0.

This post will go just a step beyond a “Hello World” example and describe a Plug-In to help you as you build other Plug-Ins. The Plug-In creates Toolstrip and Ribbon menus each with a single button. When you press the button, details returned by the API about the open topic editors, active document, and the current selection are shown on a Windows Form.

The reason there are two menus is because Flare can be configured to have either a Toolbar or a Ribbon user interface. A Plug-In doesn’t have to create a menu for each. But it would be frustrating to have an option in only one of two possible user interfaces.

Flare Plug-Ins are Windows application extensions for the Flare application. Application extensions are housed in files with a DLL extension. DLL stands for Dynamic-Link Library. To create a Flare Plug-In, you will have to be familiar with .NET, dynamic-link libraries, Windows APIs, and C# or possibly Visual Basic .NET.

The documentation provided by MadCap is a good starting point. For your first Plug-In, you will probably create a C# class project, reference the Plug-In DLL, implement the interfaces indicated in the documentation, and use the API and Windows APIs to create the behavior you want. A walk-through of those first steps will make a good future blog post. But for now, let’s see one in action.

Download this zipped project (PluginApiDetails.zip) which contains this first example Plug-In. A discussion for those not familiar with .NET development may also be a good future post. But for now, the assumption is you know how to open the project in Visual Studio, fix the references, and build the project.

The result of building the project is a DLL file. Once you have the DLL, you can follow the steps provided by MadCap to deploy the Plug-In. When all of that is complete, here is what the Plug-In looks like in Flare 9.0. Firstly the new Ribbon with a single button:

first-plugin-ribbon

Highlighting some text in a topic…

first-plugin-ribbon-highlighted-text

And clicking the new button. Information returned by API methods appears on a Windows Form called Details…

first-plugin-ribbon-details-screen

Clicking the Text button on the form shows the text of the topic in a message box…

first-plugin-ribbon-details-screen-text-messagebox

Having closed that instance of the form, a different selection is made and another instance of the form is opened by pressing the new button…

first-plugin-ribbon-small-selection

I hope that helps you to get started with your first Flare Plug-In. The sample in this post is intended to give you a tool to examine the results of many of the API properties and methods. You can install it and use it to test what is returned when you select different ranges of text.

What else would you like to know about the API? Let me know in the comments.