Tag Archives: TOCs

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.

Sorting TOCs in a Project

TOC sorting is probably only useful for reference documentation. But please post comments with any use-cases for TOC sorting you can think of. My desire to sort a TOC is threefold. I want to be able to:

  • Flatten a TOC with levels down to one level
  • Sort a flattened TOC in ascending order by the Title attribute of a TocEntry
  • Sort a TOC with a multi-level hierarchy in ascending order by the Title attribute of a TocEntry and respect the level structure

The UI is left to you.

Create a Visual Basic Windows Forms project and build a form with items which correspond to the procedures in the sample. An open file dialog is necessary to select the TOC. With the dialogs, limit the file type to *.fltoc. The TOC structure is rendered in a tree view. I placed it prominently in the center of the form. I used buttons for the options. But radio buttons would make more sense.

A preview of the options display in the tree view when a button is clicked. But nothing is saved until the save dialog is shown. You can use that to overwrite or to create a new TOC. If I see any use-cases, I’ll post a full sample project in a later post.

Flare Topic Titles, Topic Headings, and TOC Labels

If you create Flare topics and TOCs outside of the Flare application, it is a good idea to learn the differences between topic titles, topic headings, and TOC entry labels.

In the Flare UI, when you drag a topic from a Content folder to a TOC in the TOC Editor, the topic is added to the TOC. That topic already had a title and at least one heading. In many cases, a topic’s heading matches its title. The TOC label created when you drag the topic to the TOC will match the topic title and possibly the heading text. But sometimes those items do not match.

Why? Because a topic title, topic heading, and TOC entry label are distinct values.

Within the XML for a topic in a Flare project, there are elements which closely follow the patterns for XHTML. There is an html element which contains a head and a body element. If you view the markup for the topic file, you can see both. If you view the topic file in Flare’s XML editor, you can only see the html, body, and children of the body element. The head element is not accessible. But if you view the properties for the topic such as through the right-click menu, you can see items maintained in the head element. One of these is the value of the title element, a child of the head element. It appears on the Topic Properties section of the Properties dialog for the topic file as Topic Title.

The topic title also appears in many browsers as the title on the browser tab for the page rendered in the browser tab. When you use a breadcrumbs proxy, the topic title is the text you see in breadcrumbs.

MadCap Flare 8 Documentation: Changing Topic Titles

Flare TOCs do not contain topics. Flare TOCs have references to topics. These references are primarily established through links. In the markup for a TOC, a reference to a topic is a Link attribute in a TocEntry element. The text that appears in the TOC Editor for the topic reference is the value of the Title attribute for the TocEntry element. When you view the Properties for an entry on a TOC from the Flare UI, there is a Label field on the Appearance section. The value in the Label field is the value of the Title attribute for the TocEntry element. The TOC label appears in help outputs as the text in the TOC navigation. But in print outputs, the topic heading is used.

MadCap Flare 8 Documentation: Changing the Label for TOC Entries

The heading in the topic influences the behavior of cross-references. If you update the heading and then a cross-reference to the heading, the cross reference will reflect the heading text. But updating the heading will not affect the label on the TOC. However, the choice for first heading will affect the topic title if you add the topic through the TOC Editor and indicate for the title to match the first heading.

Here is a useful exercise: Create a Flare topic from the TOC Editor. Then compare the Properties for the topic with the topic markup, topic heading, the label for the node in the TOC, and the TocEntry element in the TOC markup. Do the same comparison for an existing topic dragged to a TOC. Finally, make some changes and compare the markup.

Flare TOCs (part 1)

Like topics in a Flare project, Flare TOCs are also XML files. But Flare TOCs are not designed to reflect the structure of HTML. Instead, Flare TOCs establish a hierarchy for topics. This hierarchy may also include other TOCs or the generated output from another system. A Flare TOC which only contains references to topic files may look like this:

This simple TOC creates a structure of four topics. Each TocEntry element corresponds to a topic file. The relative file location is indicated by the Link attribute and the Title in the TOC is indicated in the Title attribute. One of the entries contains another entry.This child entry, TestTopicA.htm, fould be considered a subtopic of TestTopic2.htm from the perspective of the TOC.

Let’s take note of some qualities of a Flare topic in relation to a TOC. A Flare topic has a filename with an htm extension. It is an XML file, but it has an HTML extension. The HTML-like markup in the Flare topic file may include a title element within the head element. The text of the title element in a Flare topic does not necessarily correspond the value of the Title attribute in a TocEntry element in a TOC. When you add a topic to a TOC, it is possible that the Title attribute takes the value of the title element in the topic. But that depends on the topic and how you go about adding the topic. When you view the Properties screen for a node in a TOC, the Title attribute in TocEntry does correspond to field called Label on the General tab. If you change the value in Label and save, the Title attribute in the TocEntry element changes. But the title element in the topic does not change.

The TOC Editor in Flare enables quick manipulation of this XML. You can drag and drop elements in the TOC within the TOC itself. You can also drag files into the TOC. You can change attributes for each element through a Properties screen. If you delete a topic in a project, Flare can check all of the TOCs to see if there is a reference to that topic. Flare does this with many of file types to ensure links are not broken throughout the project when a file is added or deleted.

If you perform actions on topic files outside of the Flare user interface, that last point is a very important consideration. Flare backs you up by checking for links. If you delete or move a topic or any other Flare artifact outside of the Flare user interface, you are on your own. But since the project structure is so open, you can perform your own checks as you see fit. For example, if you want to programmatically delete a file from a Flare project outside of the user interface, there is nothing stopping you from programmatically checking each TOC in the project for links to the topic.

Flare TOCs are not limited to TocEntry elements with references to topics.Here is a TOC with other kinds of links:

The TocEntry with Title=”Links to Topic” has a relative path to a topic file as the value of its Link attribute. We have seen this kind of link already. The next TocEntry links to another TOC file (Test.fltoc). When the outer TOC is generated, the references in the nested TOC will be included in the output.

The TocEntry with Title=”Links to Browse Sequence” has a relative path to a browse sequence. A browse sequence is similar to a TOC. The Browse Sequence Editor looks much like the TOC Editor. The file extension is different (FLBRS) and Flare outputs handle browse sequences differently than TOCs.

The next two entries include an attribute for the absolute path as well as the relative path. The entry which links to a Flare target indicates paths to the project file with bookmark notation for the target file name minus the file extension for targets. The entry which links to a Flare HTML5 output has paths to the main XML file for the help system. In this case, the file extension is MCWEBHELP.

Finally, there is a TocEntry with no link. This represents just a label in the TOC with no linking behavior. In HTML5 output, this would appear as a node in the TOC navigation with text equal to the value of the Title attribute. If there were child TocEntry elements, the node could be expanded or collapsed. But there would not be a link directly from the node.

On that note, if a TocEntry links to another TOC, there is a setting which merges the node when output is generated. The property (When merging, replace node with merged TOC) appears on the Advanced tab of the Properties screen. There are several options for this property. A Flare TOC stores this as an attribute of the TocEntry element. Here is how the element looks when the property is selected with option to Replace.

Flare TOCs manifest in different ways depending on the output type. The hierarchy of a TOC appears in a PDF as bookmarks and as the document order of topic content. In HTML5 output, the TOC navigation reflects the TOC and the links in the navigation correspond to the paths in each TocEntry. In HTML5 output, a file called TOC.xml is clearly based on the TOC associated with the target from which the output was generated.