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:

<?xml version="1.0" encoding="utf-8"?>
<CatapultToc
  Version="1">
  <TocEntry
    Title="Test Topic 1"
    Link="/Content/TestTopic1.htm"></TocEntry>
  <TocEntry
    Title="Test Topic 2"
    Link="/Content/TestTopic2.htm">
    <TocEntry
      Title="Test Topic A"
      Link="/Content/TestTopicA.htm"
      StartSection="false" />
  </TocEntry>
  <TocEntry
    Title="Test Topic 3"
    Link="/Content/TestTopic3.htm" />
</CatapultToc>

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:

<?xml version="1.0" encoding="utf-8"?>
<CatapultToc
  Version="1">
  <TocEntry
    Title="Links to Topic"
    Link="/Content/TestTopic1.htm" />
  <TocEntry
    Title="Links to TOC"
    Link="/Project/TOCs/Test.fltoc"></TocEntry>
  <TocEntry
    Title="Links to Browse Sequence"
    Link="/Project/Advanced/NewSequence.flbrs"></TocEntry>
  <TocEntry
    Title="Links to Flare Target"
    Link="../../FlareAutomation.flprj#Test_HTML5"
    AbsoluteLink="file:///C:/Users/Tom/Documents/My Projects/FlareAutomation/FlareAutomation.flprj#Test_HTML5"></TocEntry>
  <TocEntry
    Title="Links to Flare HTML5 Output"
    Link="../../../../../../../FlareOutput/FlareAutomationBook/Output/FlareAutomationBook_HTML5/FlareAutomationBook_HTML5.mcwebhelp"
    AbsoluteLink="file:///C:/FlareOutput/FlareAutomationBook/Output/FlareAutomationBook_HTML5/FlareAutomationBook_HTML5.mcwebhelp"></TocEntry>
  <TocEntry
    Title="Links to Nothing"></TocEntry>
</CatapultToc>

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.

  <TocEntry
    Title="Links to TOC"
    Link="/Project/TOCs/Test.fltoc"
    ReplaceMergeNode="true"
    AutoMerge="replace"></TocEntry>

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.