02 September 2019

Madcap Flare's Clean HTML: What it does (and doesn’t) do

In a previous post, I outlined how you can download and use a trial version of Madcap Flare complete with their Salesforce Connect addon. This post provides further information on the Clean XHTML output format required to publish your Flare output to Salesforce. The Madcap Flare help file does a good job at describing what is supported in the various output types (see the "Output Type Comparison Table" section of the "Determining the Output Type" page) but this post focuses on the major features of Flare and what is supported in the Clean HTML output type.

What is Clean HTML?


In summary, the Clean XHTML output format is a collection of pure HTML files, one for each Flare topic. The HTML files contain no Madcap Flare proprietary HTML tags, and aren't dependent on any other generated files (e.g. skins, table of contents). This should give experienced Flare users an insight into what types of support is offered. Now we know what Clean HTML is, let's look at the major functionality supported / unsupported with it?

Supported Features

  • Accessibility: This may not be important to you, but Clean HTML is similar to most other output types when it comes to providing an output that needs to conform to Section 508 or WCAG compliance standards. The only thing Clean HTML doesn't support is scrolling toolbars.
  • Numbered / Bulleted Lists: These use pure HTML so are perfectly OK to use in your source.
  • Master Pages: These act as templates for your Flare topics, and you can have as many as you like.
  • Mini TOCs: This may surprise you considering Clean HTML has no need for a TOC file, but these are supported by adding the Mini-TOC proxy inside your master page. Contrary to popular belief, they don't use any scripting.
  • Image Positioning and Formatting: All features available in other online output formats are supported (e.g. image maps, absolute positioning). The only major difference is that thumbnail images set to open inside a popup, are converted to linked thumbnail images.
  • Language Support: This is mostly supported. The major exception being editing skins.
  • Madcap Central: Full support of Madcap Central allows you to build and view your output.
  • Snippets / Variables: These are all supported, except running head variables in a header, footer, or print master page.
  • Tables / Text Boxes: Both are fully supported.
  • Multimedia: Full support is provided for multimedia hosting platforms (e.g. Youtube) as well as file types. The only exception is 3D mimic movie files.
  • Responsive Output: Whilst this is supported, you must select the "Convert Styles to Inline" option in the Clean HTML target. Using this option is recommended by Madcap, so you need to consider whether your output being responsive on small devices is important.

Unsupported Features

  • Context Sensitive Help: This feature requires a proprietary Madcap file containing the link between a topic and the application dialog. Because the Clean HTML is just a collection of topic files with no proprietary Madcap files, you can't have any context sensitive help links.
  • Breadcrumbs: Unfortunately this falls into the same trap as context sensitive help. This is not the end of the world if you're publishing to Salesforce, as that supports the use of breadcrumb trails. You just need to configure your Salesforce template to accommodate this.
  • Browse Sequences: Once again these use a proprietary file. On the surface, this may seem like a major issue for some, but with some thought about your content structure, you can provide a similar navigation experience inside your topics.
  • Concept / Keyword Links: Yes these use proprietary specific tags, so you've guessed it, they are supported.
  • Related Topic Links: A proprietary file once again, but try adding a "Related Topics" heading to your Master Page instead. You'll have to manually add the links, but you'd have had to do that anyway.
  • Scripts: MadCap's proprietary JavaScript (e.g. drop-downs, Help controls, text popups) is removed from the output and converted to text. If you've added your own scripts, these aren't removed and must be excluded manually by deleting them or using conditions.
  • Indexes: These aren't supported, but have gone out of fashion with the advent of online output.
  • Merging Output: Dividing your topics into multiple Flare projects is a common approach for Technical Writing teams. However not being able to merge them at run time isn't a major issue. You can still divide your content up into multiple projects, and provided they all publish to the same Salesforce instance, all is OK. I’ll cover this in more detail in a future post.
  • Drop Down / Expanding Text, Text Popups: These features all require proprietary HTML or scripts.
  • Search: You are totally reliant on the search functionality by the platform used to host your output. As most Clean HTML users will be publishing to platforms like Salesforce, this shouldn't be an issue.
  • Skins: These files all use a multitude of scripts, so fall foul of the "no scripting" rule.
  • Table of Contents: Whilst TOCs aren't supported, you can add mini-TOC to a master page attached to a topic.

Summary


This post should give you a good indication of what you’ll be able to achieve with the Clean HTML target in Madcap Flare. Watch out for further deep dive posts into specific elements.

No comments:

Post a comment