Monthly Archives: March 2013

Hide Some Flare HTML5 Output Glossary Tab Entries

This example uses JavaScript, JSON, and jQuery.

In a response to a forum post, I suggested a rules-based approach to removing plural terms from the Glossary tab in Flare HTML5 output. The sample I provided tackled a few common English rules.

Rules-based Example to Remove Glossary Tab Entries with JavaScript

Rules are one way to approach the problem. Another way is to keep a list of items to remove or hide. What follows is another example which hides three terms on a Glossary tab when the function in the example fires. You can adjust the list of terms in the JSON object which holds the list of terms. You can also adjust when the function is called. In the example project, there is a toolbar button. But you can add an event listener to some other object to call the function if you do not want to be tied to the toolbar.

The sample project is configured as follows. There is a glossary with three glossary terms consisting of a plural term and a singular term: Child/Children, Apple/Apples, and Goose/Geese.

GlossaryEditor

There is a JSON object and a JavaScript function in the Toolbar Javascript.

ToolbarJavaScript

The skin has a custom toolbar button called HideEntries. When that button is clicked, hideEntries() from the Toolbar JavaScript is fired.

HTML5SkinEditorToolbar

HTML5SkinEditorStyles

The Glossary tab appears this way when initially viewed:

GlossaryTabBefore

After the HideEntries toolbar button (the blank one) is clicked, the three terms in the JSON object are removed from the list.

GlossaryTabAfter

A sample project is here: HideTerms.flprjzip

 

 

Review of MadCap Flare Version 9.0

Having spent some more time with MadCap Flare 9.0, I’m ready to offer some opinions.

Disclosure

MadCap Software has provided me with a copy of MadCap Flare 9.0 for the purposes of review on this blog and to keep as my personal copy. MadCap Software has also covered my travel and boarding expenses for the purposes of presenting at the MadWorld 2013 conference. The opinions expressed on this blog are my own. Any details about products and services discussed on this blog should be verified with the manufacturer or provider.

I probably wouldn’t blog about something I didn’t like.

Review

MadCap’s What’s New In this Version documentation for Flare 9.0 describes Major New Features and Additional New Features. This is a blog about markup, programming, scripting, and automating in the context of MadCap Flare. But I’ll give my two cents about some of those listed as Major New Features.

Right-to-Left

If you use a right-to-left language, right-to-left support is THE new feature. I wish I could speak and write Arabic, Hebrew, or Persian to offer more insight. I can’t. But I am happy to see a wider market for the product. The more users, the more enhancements we can expect in the future.

Print Enhancements

Although I enjoy styling print output, I can’t remember the last time I intentionally read a PDF if the content was available as HTML. But if you actually want to print your print output, bleed, crop marks, and registration marks, and support for the CMYK color model are almost essential. Those are new additions. There are more print-related enhancements and I agree with most of those.

Removing the gray from the frame in the page layout editor may be my favorite print-related change. Small things make a difference as Kai Weber expressed in this post.

But the big four for me are…

Split View

This is cool.

split-view

You can now see the semi-WYSIWYG right next to the markup. I wish there was a split view for every type of XML file in a Flare project. For those, I still right-click the files and open those in Notepad++. For topics, I now find myself using the structure bars, the text in the XML Editor, and the Text Editor. Each works well for different tasks. The synchronization between each editor is pretty good. You can still trick it. But I think that will improve with minor releases. For heavy writing, you may find yourself turning this off because displaying two views at the same time doubles the screen real estate.

Advanced Conditional Expressions

“AND” makes an appearance!

Previously, the limitations of conditional expressions necessitated source content replication in certain scenarios. With the previous model, now called Basic, an Include would override an Exclude every time. Those limitations go away now because in addition to “OR” and “NOT” (derived from Include and Exclude), you can specify “AND.”

When editing in Basic mode, one or two clicks of the Include and Exclude column headers can wipe out your Basic settings. Read about how the Basic and Advanced modes work before you make changes. The settings are stored independently which may not be obvious at first.

advanced-conditional-expressions

Plug-In API

If read this blog, you can probably guess that this is my favorite new feature. I’m going to dive deeper into the API in future posts. My first blog post about the Plug-In API is here. The focus of the API is on adding menus, topic editors, and text selections.

Performance Improvements with HTML5

This produced some initial complications for me which were quickly addressed by MadCap’s technical support. Thank you to Lori and Joey for addressing those issues.

I am glad MadCap is working on performance in the output.

If you examine the TOC files in the Data folder of your HTML5 output, you will notice the XML is gone and only the JS files remain. And if you look at those, you can see that the TOC information is now encoded as JSON instead of an XML string.

This means that if you were using the TOC XML in the output for something else, you will now have to switch to reading the JSON. For example, this technique does not work with version 9.0 HTML5 output anymore. But it can be reworked to consume the new JavaScript files.

There are more new features which I haven’t covered. These are the highlights for me. What are your thoughts on the new release?

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.