Monthly Archives: March 2014

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.