Topics in a Flare project are XML files. Here is the markup for a basic topic file in a Flare project:
<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head>
<link href="Resources/Stylesheets/FlareAutomationBookStyles.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Topic Title</h1>
<p>Delete this text and replace it with your own content.</p>
</body>
</html>
The first line is called the XML declaration.
<?xml version="1.0" encoding="utf-8"?>
If you edit a Flare topic with the XML Editor in Flare, you can not change that declaration. But you can alter the declaration outside of the XML Editor. For example, you can open the topic file with the Text Editor in Flare, delete the declaration, and save it. If you open the file with the XML Editor again, Flare will recognize the file is no longer an XML document and offer to convert the document to XML with a wizard.
Following the declaration are XML elements.
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head>
The root element in this document is named html. It contains two other elements (head and body) and a namespace (xmlns:MadCap=”http://www.madcapsoftware.com/Schemas/MadCap.xsd”). These XML elements correspond to elements used in HTML and XHTML. But a Flare topic file in a project is an XML document. Therefore, the html, head, and body elements in the XML document are XML elements. The correspondence is purposeful. Topics in a Flare project are not HTML. But is possible to generate HTML output based on the topics in a Flare project.
If you look at the structure information in the XML Editor, you will notice head element is not included. There is a block for html which contains body. You can right-click the html block for a menu of actions you can take on the html element. These actions focus on adjusting the attributes for the html element. For example, you can add a class attribute. Flare determines which values are allowed for the class attribute through a stylesheet, CSS file. This is the case for all of the elements in the Flare topic. The class attribute of an element in a Flare topic should correspond to a style in a CSS. But if you change the value of the class attribute outside of the XML Editor to a value not defined in the CSS and open the file again in the XML Editor, Flare will respect the change. But you will not be able to set that particular value for another element in the file using the XML Editor unless you add a style to the CSS.
The namespace in the html element refers to a MadCap Software schema document. The html element in a Flare topic file in a project should conform to that schema. The schema is an XSD file.
If you want to make changes to the head element in a Flare topic from the Flare user interface, you can right-click a topic file in the Content Explorer and select Properties. Some of the actions you can take on this Properties screen involve the head element attributes and others involve the html element attributes. For example, you can also change the class for the html element from the Properties screen (Topic Properties > Topic Style Class). For the head element, you can add a title element from the Properties screen (Topic Properties > Topic Title).
Flare provides an XML Editor, a Text Editor, and right-click behavior to open files with other programs. So you can easily find out what the effect of an action in Flare is by observing the changes in the XML Editor and comparing those changes to the markup in the Text Editor. Sometimes the interface gives hints. For example, you can insert a text box into a topic with the Insert > Text Box… menu item in the Classic view or the Insert > Text > Text Box button on the Ribbon view. The screen that appears makes it clear that text boxes in Flare are div elements. You can also see this in the structure blocks in the XML Editor. On the Text Box screen, you can set items such as width. From the XML Editor, you can also adjust the width through a floating drop-down or the right-click menu for the div block. But it may not be apparent that the width is stored in a style attribute for the div element until you view the markup in the Text Editor. Not every div is a text box.
With a better understanding of topics in a Flare project, we can recognize how topics change when they are generated into an output. But firstly, let’s review the workflow to generate output such as a PDF or a help file. This is a broad overview.
Source files are maintained in Flare projects. Source topics are XML files. TOCs are XML files which organize topics. Targets define how to build a output such as a PDF. There is a TOC associated with every target. When you build a target, Flare creates an output structured according to the target’s associated TOC. Sometimes an output includes a file structure and files which correspond to the source project structure. HTML5 output is an example of this. HTML5 output can have a Content folder and a Project folder just like a Flare project. But the files inside those folders are different. For example, topic files in Flare projects are XML files but topic files in HTML5 output are HTML5 files.
If you produce HTML5 output which includes this topic,the generated HTML5 topic may look like this:
<!DOCTYPE html>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" lang="en-us" xml:lang="en-us" class="no-feedback" data-mc-search-type="Stem" data-mc-help-system-file-name="Test_HTML5.xml" data-mc-path-to-help-system="../" data-mc-target-type="WebHelp2" data-mc-runtime-file-type="Topic" data-mc-preload-images="false" data-mc-in-preview-mode="false" data-mc-toc-path="">
<head>
<meta charset="utf-8" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../Skins/Default/Stylesheets/TextEffects.css" rel="stylesheet" type="text/css" />
<link href="../Skins/Default/Stylesheets/Topic.css" rel="stylesheet" type="text/css" /><title>Topic Title</title>
<link href="Resources/Stylesheets/FlareAutomationBookStyles.css" rel="stylesheet" type="text/css" />
<script src="../Resources/Scripts/jquery.min.js" type="text/javascript">
</script>
<script src="../Resources/Scripts/plugins.min.js" type="text/javascript">
</script>
<script src="../Resources/Scripts/MadCapAll.js" type="text/javascript">
</script>
</head>
<body>
<h1>Topic Title</h1>
<p>Delete this text and replace it with your own content.</p>
</body>
</html>
The declaration at the top of a generated topic in HTML5 output is the declaration defined by the HTML5 standards in progress. For WebHelp output, the declarations at the top of the generated topics are one of the three options in the XHTML standard. If you produce WebHelp output which includes this topic, the generated XHTML 1.0 topic may look like this:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../" MadCap:HelpSystemFileName="Test_WebHelp.xml" MadCap:SearchType="Stem">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><title>Topic Title</title>
<link href="Resources/Stylesheets/FlareAutomationBookStyles.css" rel="stylesheet" type="text/css" />
<script src="SkinSupport/MadCapAll.js" type="text/javascript">
</script>
</head>
<body>
<h1>Topic Title</h1>
<p>Delete this text and replace it with your own content.</p>
<script type="text/javascript" src="SkinSupport/MadCapBodyEnd.js">
</script>
</body>
</html>
If you produce WebHelp Mobile output which includes this topic, the generated XHTML Mobile Profile 1.2 topic may look like this:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelpMobile" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../" MadCap:HelpSystemFileName="Test_WebHelpMobile.xml" MadCap:SearchType="Stem">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../Resources/Topic.css" rel="stylesheet" type="text/css" />
<link href="../Skins/Default/Stylesheets/StackLayout.css" rel="stylesheet" type="text/css" />
<link href="../Skins/Default/Stylesheets/Header.css" rel="stylesheet" type="text/css" /><title>Topic Title</title>
<link href="Resources/Stylesheets/FlareAutomationBookStyles.css" rel="stylesheet" type="text/css" />
<meta name="viewport" content="width=device-width, minimum-scale=1.0, maximum-scale=1.6" />
<script src="../Resources/Scripts/MadCapAll.js" type="text/javascript">
</script>
</head>
<body>
<div id="header">
<div id="navigationContainer"><a class="button" href="../Test_WebHelpMobile.htm"><span class="buttonLeft"></span><span class="buttonCenter">Home</span><span class="buttonRight"></span></a>
</div>
</div>
<div class="MCTopicBody">
<h1>Topic Title</h1>
<p>Delete this text and replace it with your own content.</p>
</div>
</body>
</html>
In each of these outputs, the declarations at the top of the document are different from the XML source document. The attributes for the html element also vary. For each output, there are different children in the head and body elements. In the head element, the meta, link, and script elements are tailored to the needs of the output.
Before we look closer, let’s review some other Flare artifacts which influence the output. In addition to an association with TOCs, targets for online outputs have an association with a skin and a topic stylesheet. Skins establish the appearance and user interaction wrapping a generated topic displayed in a web browser. Skins support interactions such as TOC navigation and search. Stylesheets have already been mentioned in context of topics. But there are also stylesheets associated with skins. With topic stylesheets, you can edit the styles through Flare’s topic stylesheet editor or you can go outside of Flare to edit the stylesheet. Most of your outside edits will be still supported by the Flare editor. You can adjust some of the styles for skins from the skin editor in Flare.It is also possible to adjust the stylesheets used by the skins. But these stylesheets are not maintained in your project. Rather, skin stylesheets live in the installation folder for Flare. If you make changes to these stylesheets, the changes are global to any output created on the machine. For outputs such as HTML5 where both the topic and skin stylesheets are exposed in the file structure of the output, you can potentially perform post-build processing to change the behavior of the output.
There are links to different stylesheets and each output may use different JavaScript to control the skin behavior. A quick inspection of the values of the href attributes of the stylesheet links indicates how the stylesheet is used. Skin stylesheets have a path such as:
../Skins/Default/Stylesheets/TextEffects.css
Topic stylesheets have a path such as:
Resources/Stylesheets/FlareAutomationBookStyles.css
From the perspective of the generated topic, the TextEffects.css is located a folder back and three folders down another path. For example, if the generated topic is in this folder:
C:\FlareOutput\FlareAutomationBook\Output\FlareAutomationBook_HTML5\Content
Then the TextEffects.css file is in this folder:
C:\FlareOutput\FlareAutomationBook\Output\FlareAutomationBook_HTML5\Skins\Default\Stylesheets
The ../ part of the file path means parent directory. For the topic stylesheet above, the CSS file is in a subdirectory of the topic file. So there is no notation for parent directory at the beginning of the file path. But both path in the link element href attributes are relative paths. This way you can copy the output files anywhere and the output still works.
In summary, topics in Flare projects are XML files. You can edit the text of a topic file directly in the XML Editor and you can change attributes and elements through features in the Flare user interface. Topics in a Flare project are source files which are transformed when Flare builds a target to generate an output such as a PDF or HTML5 help. The generated topics may appear as another document type sucha s HTML5 or XHTML in the file structure for the output.
How would we add/customize the meta tags generated for the top-level frameset document for HTML5 output? We don’t want to do that after generating, but configure things inside Flare if possible.
It won’t be a frameset with the HTML5 output since frameset is no longer supported in HTML5. Instead the sections of the skin are established with div, ul, etc. There is an iframe for the topic pane, which is what is addressed when the TOC links are clicked. But that is different than frameset and frame. You can change the source files for the target type on a particular installation. For example, on my computer the source for the main help file (by default, Default.htm) is located in C:Program Files (x86)MadCap SoftwareMadCap Flare V9Flare.appResourcesWebHelp2Desktop. Those changes will persist for anything generated on that computer. You may be able to add the meta tags there. Make sure to back up the original file before you change it. There are several threads about this technique at forums.madcapsoftware.com.
At a topic level, you can add meta descriptions this way: http://webhelp.madcapsoftware.com/flare9/Default.htm#Topics/More_About_Topics/Adding_Meta_Descriptions_for_Topics.htm