Tag Archives: API

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.

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.