Tag Archives: TOC

A Simple Flare HTML5 Output ‘Re-skin’ with PHP

Although I am not a huge fan of PHP, there are some things it does well. One of those is content reuse on web pages. Having previously built a (no longer extant) website which used little more of PHP than the include function, I admit the choice saved a lot of time and code for little cost. A little PHP enabled content reuse without a CMS.

This post describes a simple “re-skin” of an existing HTML5 output. The idea is to use the topic files and the Toc.xml file to recreate a navigation and topic display. This will be a simple example without many bells and whistles and no CSS. But you can build on it if you find it useful. This example does not goes as far as using the Title attribute for the text of the links or indenting the links based on topic level. This is just a proof-of-concept.

To create the PHP “skin,” you can install PHP on the web server hosting the skin, place the Flare HTML5 output on the web server, and place the code sample in a file called Index.php at the root of the Flare HTML output folder. You can read more about how PHP works at:

http://www.php.net/

In the PHP file, HTML5 syntax will be used for the HTML portions and the scripting will be PHP tags. The “skin” will have a list of linked topics based on Toc.xml in the Data folder of the HTML5 output and a view of the selected topic which appears at the top when you click a link.

A previous post described how to return all of the Link attributes in the TocEntry elements in the Toc.xml file in an HTML5 output with XPATH. That was a building block post. Now we are going to use that block to build the list of linked topics.

In Flare HTML5 output, the URLs for topic navigation appear as a pound sign and topic file name after the URL for the main help file: http://localhost/flareoutput/default.htm#topicname.htm

With this PHP “skin,” the URL will look like this: http://localhost/flareoutput/Index.php?topic=topicname.htm

The first PHP script checks if there is a topic qualifier in the URL.  If there is a topic qualifier, the script removes the / from the beginning. This is because Toc.xml stores the paths that way and PHP expects no / at the beginning of relative URLs in this case. It loads the topic into an iframe at the top of the page. There is also a check to see if the qualifier is there: isset.

The second script uses the XPATH expression to get all of the Link values for TocEntry elements in Toc.xml. It displays each as a hyperlink with a format which uses Index.php and the qualifier with the topic name.

You can install PHP on your web server, copy a Flare HTML5 output to it, place an Index.php file containing the sample below at the root of the output, an open the URL to Index.php to see this work.

Index.php:

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.