Tag Archives: HTML5

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.

Create a Java Application That Uses Flare HTML5 Help

This post describes the creation of a simple Java application and Flare project and HTML5 output to demonstrate opening a Flare HTML5 help topic with a button click or an F1 keypress from a Java application. This is a “hello world” level example.


Java Application and Flare HTML5 Help

MadCap provides conceptual information and instructions for programmers and authors about how to configure applications to use context sensitive help with Flare HTML5 outputs. This post covers some of that workflow. The example is less complicated but not as flexible as MadCap’s suggested workflows. However this post goes into greater detail about how to connect an application to HTML5 help in the context of a Java application.

MadCap Software: CSH Calls for HTML5 Output (WebHelp 2.0)

The example Java and Flare projects are configured such that the application opens a URL for the Flare HTML5 output using the CSHID number in the URL For simplicity, the CSHID number value used is 1 and the topic is Topic.htm (topic.htm in the sample output). Additional calls to open help can be added with the same technique. For more information about CSHID and CSH calls, see the preceding link.

With the arrangement established by the samples in this post, a Flare author would manage the mapping of ID numbers to topics. A programmer would call the same function for every help button click or F1 press and pass the desired ID number. No lookup is necessary on the Java application side. A programmer only needs to know which values to use for actions and UI locations in the application. There is no need to supply a properties file to a programmer with this setup. One possible workflow is the author informs a programmer which IDs to use and the programmer implements those. Another workflow is a programmer assigns IDs and the author updates the Flare project to map those IDs to the topics. Either way the mapping is managed through the Flare HTML5 system.

Other scenarios may be explored in subsequent posts. The Flare documentation describes a workflow in which a copy of a header or a properties file is used by the application so that the application is aware of the mapping between the ID name and number. That workflow adds some flexibility. But that workflow is not demonstrated in this post.

Create a Java Application with NetBeans

This example uses NetBeans to create the Java sample. The steps use the IDE options so that those who do not program regularly with Java can replicate the steps more easily. However designing forms in an IDE such as NetBeans involves a reliance on the mechanisms the IDE uses to generate code. For example a NetBeans project with a JFrame form may contain an additional XML file with a .form extension to facilitate form building. The Java class for the JFrame is sufficient to run the program. But the .form file is required for the form designer in NetBeans.

NetBeans wiki: What is the .form file?

  1. Install NetBeans. This example was created on a computer running Windows 8 with Java, the Java Development Kit, and NetBeans installed. https://netbeans.org/
  2. From the menu, select File > New ProjectThe New Project screen appears.
  3. Select Java Application.
  4. Click Next.
  5. Enter a project name such as JavaAppFlareHtml5Help.
  6. Click Finish.

Add a JFrame Form to the Application

The window user interface for this example is implemented with a JFrame. The steps which follow describe adding a a JFrame to a Java project in NetBeans.

  1. Right-click the package and select New > JFrame form.
    The New JFrame Form screen appears.
  2. Enter a class name such as JFrameHtml5Example.
  3. Click Finish.
  4. The JFrame designer appears in NetBeans.

Add a JLabel and a Help JButton to the JFrame

The JLabel is just an embellishment for this example to place some text on the JFrame. The JButton provides an interface to click to show a help topic.

  1. Drag a JLabel from the palette to the designer. JLabel is located under Swing Controls on the palette and is indicated as Label. This and the next step are not necessary to demonstrate opening help.
  2. From the properties screen for the JLabel, change the text to Flare HTML5 Help Example.
  3. Drag a JButton from the palette to the designer. JButton is located under Swing Controls and is indicated as Button.
  4. From the properties screen for the JButton, change the text to Help.
  5. Double-click the button in the designer. The code for the action event appears in the code editor. Call a yet-to-be-defined function called showHelp and pass a string value of 1.


Add F1 Events

To create F1 behavior, a handler must be added for every control on the form which should cause help to open when F1 is pressed. In this case the only control to worry about is the JButton since it is the only control which can be active. By default, JLabels cannot be activated. A handler is also added to the JFrame itself.

  1. To add a keyPressed event for the JFrame and the JButton, from the properties screen for each, click the ellipses next to keyPressed under Events. The Handlers for keyPressed screen appears. The screen shot shows the screen after the event has been added.
  2. Click Add.
  3. The Add Handler screen appears.
  4. Enter a name such as jFrameKeyPressed and click OK.
  5. The handler code appears in the code editor. Call the yet-to-be-defined showHelp method from the handler for the case where F1 is pressed. The constant value for the F1 keycode in Java is 112. Wrap the call to showHelp in a conditional that checks for that value.


Add Methods to Open Help

The technique employed in this example relies on a call to a showHelp method within every event and handler that should cause help to open. The context for the help comes from the ID passed to showHelp. The showHelp method appends the ID to a base URL for the help system. The base URL is the path to the main help file followed by #cshid=. Once the URL is built, it is passed to a method to open a web page.

Stack Overflow: Open a Link in Browser with Java Button

  1. Add methods to open a web page from the Java application. You can paste these into the class for the JFrame.
  2. If the above code is pasted into the class file and there are not imports for the classes on which the methods depend, the Import Classes screen appears. These are the imports required for the example:



  3. Click OK.
  4. Save the project files.

Code the Main Method to Open the JFrame

Open the java file that contains the main method. For this example, the file is JavaAppFlareHtml5Help.java. The main method should create and show an instance of the JFrame. Change the main method to this:


Create a Flare Project to Build the Help

Create a new Flare project with the Empty template. Use HTML5 as the default target.

  1. Select File > New Project. The Start New Project Wizard appears.
  2. For the name, enter java-example.
  3. Click Next.
  4. Under Source, select New from template and select Empty.
  5. Click Next.
  6. For the primary target, select HTML5.
  7. Click Finish.

Add an extra topic named extra-topic.htm and set that as the default topic on the HTML5 target. This ensures the default topic is not the topic opened by the application. That demonstrates the application opens a specific topic and not just the default.

  1. Right-click the Content folder in Content Explorer and select New > Topic. The Add File screen appears.
  2. In the File Name field, enter extra-topic.
  3. Click Add.
  4. Save the topic.
  5. In the Project Organizer within the Targets folder, double-click the HTML5 target to open it in the Target Editor.
  6. On the General tab in the Startup Topic field, select extra-topic.
  7. Save the target.

Set the topic alias. Open the alias file and assign Topic.htm to the identifier in the alias file. The header file will update when the alias file is saved.

  1. From the Project Organizer within the Advanced > CSH folder, double-click the AliasFile.flali file. The alias file appears in an editor.
  2. In the alias file editor, navigate to the Topic.htm file and right-click the file.
  3. From the menu, select Assign topic to selected identifier.
  4. Save the alias file.
  5. In the Target Editor for the HTML5 target on the General tab, change the name of the output file to java-app-help.
  6. In the Target Editor for the HTML5 target on the General tab, change the Startup Topic to extra-topic.htm.

MadCap Software: Creating and Assigning Identifiers

A handful of changes were made to the template for this example. Some of the changes are shown in the screen shot that follows. The order of items in the screen shot is:

  • Project Organizer
  • Content Explorer
  • Topic.htm in XML Editor
  • HeaderFile.h in Header Editor
  • AliasFile.flali in Alias Editor


Test the Application and Help

Build the target an place the output somewhere. Adjust the path in the showHelp method to reflect the location of the help files.

To run the program from the IDE, with the project open and active, select Run > Run Project.


Clear a Flare HTML5 Search Field with the Escape Key

If you want the search field in Flare HTML5 output to clear when escape is pressed, add the following to the toolbar JavaScript.

If there is already a window.onload assignment, just add the inner part to the existing assignment.



Show and Hide with jQuery in HTML5 Output

MadCap Flare includes some show-and-hide controls for web-based outputs such as Togglers and Expanding Text. This blog has explored some alternatives for show-and-hide in the context of condition tags. Here is another option which uses jQuery to expand and collapse an element with a sliding animation.

Sliding show-and-hide actions are simple tasks with jQuery. Two such functions are slideUp() and slideDown(). Here is a function which uses both functions to show and hide an element given the element’s id attribute value.

You can add this script to many places in a Flare project. For simplicity in this example, here is an image of the script inserted into a topic and then edited.


With the Attributes Window in Flare, you can set the value for an attribute of an element highlighted in the XML Editor. You can also edit the markup directly with the Text Editor. For this example the element to show and hide is given the value ‘show-hide’ for the id attribute.


The element to click is given the following value for the onclick attribute to call the JavaScript function. The value for id is passed to the function:


The final markup for the topic looks like this:

When the target is built and the output is opened, the click behavior looks like this:


Other relevant concepts:


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

In the previous post, the sample included a JavaScript which toggled the display attribute of elements between none and block depending on the value of a select element and the MadCap conditions applied to the elements.

But what if the display attribute wasn’t set to block in the first place? This second sample project includes a variation of the previous script which uses a custom data-* attribute to persist the original value of the display elements toggled. Instead of toggling between block and none, the original display attribute value is stored in a custom data* attribute and applied to the display element when the element is made visible again.

Section in W3C Working Draft: Embedding custom non-visible data with the data-* attributes

Why is this better? Not all elements start with a value of block for the display attribute and the default is inline anyhow. As an example, many menus implemented with CSS use a display value of inline to place the menus next to each other instead of underneath the previous. If you don’t care about that sort of thing, the original sample is sufficient. In other words if your granularity for tagging content by version doesn’t extend to elements which use display values of inline or something other than block, you can just toggle between block and none as the values for the display attribute.

Why is this controversial? The controversy surrounds the separation of markup and presentation. It also surrounds the idea of semantic misrepresentation. And the specification at one point indicated as much. Here are some links about that:

HTML Doctor: HTML5 Custom Data Attributes (data-*)

danwebb.net: Put that data-* attribute away, son…You might hurt someone

These are all valid concerns. Add to that, there is another way to indicate visibility. But given the situation of acting on markup in a help system after it has been built, isn’t this worth it? It definitely works. You can have filtering before publishing and in the output itself.

But it wouldn’t hurt to run the filtered content through a screen reader to see how the custom attribute and the filtering technique influences accessibility. My instinct is that it wouldn’t have a negative impact. But that is a subject for another post. This is an ongoing exploration.

sample project (version filter) 2

Version Filters in HTML5 Output

Keep the condition tags but skip the target settings.

Quick unpaid promotion! Attend MadWorld for my session and many others. Meet and learn from top technical communicators.

sample project


You can apply conditions to your Flare content and use those conditions to create a version filter in your Flare HTML5 output. The main ingredients are a select element and a little JavaScript. Here’s how.

We’ll start with a fresh project based on the Empty template which comes with Flare.


To keep it simple, we’ll use the Default condition tag set. But one of the nice things about having condition tag sets is there can be more than one. Since we aren’t going to touch the settings for these tags in the target, this is a situation when a separate set would make sense.


We can change the conditions to represent versions of a product. Periods are not allowed in the Condition Tag field. If you use periods or full stops (.) in version numbers you will have to find a different character for the tag. But you can still use the period in the text of the drop-down we will create in the topic.


Now we can create some content to which to apply the tags.


And apply the tags.


Here is the topic in the XML Editor with the conditions applied:


Now let’s look at those tags in the Text Editor.


Here is the first tagged paragraph. In the XML for the topic, the MadCap:conditions attribute holds the conditions. The condition is appended to the condition tag set name and a period symbol:

When there is more than one, the conditions are separated by commas.

File that in your memory. Now let’s add the UI for the filter. We can create a snippet to hold the filter for topic reuse. The snippet will use a select element, the element’s children, and some attributes. Here is the snippet in the Text Editor.


There is an id attribute on the select element so the JavaScript can find the filter. The select element fires a JavaScript every time the the selection is changed. Here is the snippet in the topic:


We can’t see the UI for the snippet from the Text Editor or the XML Editor. But we can see a preview when we add the snippet.


The JavaScript will look at the selected option and show or hide tagged elements based on the selection. Here is the JavaScript in Flare’s Text Editor:


There are two functions. The first, getElementsWithAttribute, is used by the other function, showHideVersion, to get all of the elements in the topic with the data-mc-conditions attribute. Remember MadCap:conditions in the topic XML? That becomes data-mc-conditions in the HTML5 output topics.

The showHideVersion function looks for the select element and gets the selected option. Then it loops through all of the elements with data-mc-conditions and shows or hides the elements based on whether the elements include the selected condition.

The last line of the script ensures the script runs when the page initially loads.

We can reference the JavaScript in the master page. There is no default master page in the Empty template. We can base the new master page on the MasterPage.flmsp Factory Template. The script will go after the body element in the master page so we will add it through the Text Editor. Note the relative path to the file.


Let’s not forget to add the master page to the target.


At this point we are ready to build. Here again is how the output looks. You can select a version and only content tagged with that version appears.




Now you can filter on a single condition in a topic from the published output. In this example and sample, the content must be tagged to appear. But you don’t have to limit yourself to that behavior with your JavaScript. What kind of filter behavior would you expect to see in a version filter? Let me know in the comments.

sample project

Update: There is a follow-up post and sample which persists the original display value instead of toggling between none and block.