15 August 2020

Madcap Flare: CSS perils publishing to Salesforce, Zendesk, or ServiceNow

The 2019 release of Madcap Flare added support to publish your output to Salesforce and Zendesk. Support was added to publish to ServiceNow in the Madcap Flare 2020 release. To do so, you need to purchase a separate plug-in licence for the appropriate platform. Use the links below for further details:

Publishing Prerequisites

Before you can publish your output, you must:
  1. Install the relevant plugin. I've covered how to do this in a previous post.
  2. Configure the connection to the hosting platform in your Flare destination file.
  3. Ensure the "Convert Stylesheet Styles to Inline Styles" option is enabled in your Flare target file.

The CSS Conundrum

It is the last of these prerequisite tasks that is at the heart of this post. Each of these plug-ins requires you to use a Clean HTML target. You can't use anything else. This is because the hosting platforms require only the raw HTML file for each topic. There is no need for TOC, glossary, snippet, or any other proprietary Flare files. Additionally, as the platforms you're using has its own CSS files, your CSS styles aren't required.
 
By enabling the "Convert Stylesheet Styles to Inline Styles" option, you're telling Flare to embed any styling you're using in your project's stylesheets in each topic's HTML output, thereby ensuring your styling is maintained. 

The Issue

So what's the big issue with embedding the CSS styling in the HTML output? In a nutshell, it's the character limit in the host application. For example, the Connect for Salesforce plugin publishes to Salesforce's Knowledge component. This allows a maximum of 131,072 characters per page, including all the HTML tags.

This may seem like a lot, but consider the number of characters in a table. Say you've a dialog comprising of nine fields, which you've listed in a table. Any styling applied to the table cells in Flare is applied inline to the <td> tag for each and every cell in the HTML. The same is true of all other styles (e.g. numbered lists, headings, etc.)

In short, the number of characters in a Flare topic's Clean HTML output soon starts to add up. What's more, there is no easy way to ascertain if you've topics in your project that exceed the character limit. The only ways I'm aware of (neither of which are satisfactory) are:
  • Publish the target. If the limit is reached, an error is returned.
  • Open the source of each page's output, copy it to your clipboard, and paste it into a blank Word file. The number of characters is displayed in the Word Count function.

Examples

I've created two topics and added some lists and a table to them. To create the examples, I created a new Flare project using the "Blank" project template, which uses a fairly basic CSS file.

List Topic

Here's a topic containing an ordered and unordered list:
The topic's HTML offers no surprises. It's all standard HTML tags:
But let's look at the HTML from the Flare project's Clean HTML target with the "Convert Stylesheet Styles to Inline Styles" option enabled:

Table Topic

Here's a topic containing a simple three column, three row table, with a header row and a 3px table border:
The topic's HTML again offers no surprises, with standard HTML tags:
Finally let's see the HTML from the Flare project's Clean HTML target with the "Convert Stylesheet Styles to Inline Styles" option enabled:

The Statistics

Let's look at the character numbers in these examples.
  • In the list topic, the total number of characters in the Flare project's HTML equals 759. In the Clean HTML output file, that jumps to an impressive 1213. That's a 62% increase!
  • In the table topic, the total number of characters in the Flare project's HTML equals 1865. In the Clean HTML output file, that jumps to 1908. That's not a big jump, but it's a small table with limited formatting.

Solution

I'm hopeful that Madcap will address the issue of only being aware of a topic exceeding the character limit when you publish, in a future release. They've certainly accepted it causes issues.

Even if they address the issue, the hosting platform's limit still exists. If you hit the limit, the only way to successfully publish your Flare project is to reduce the number of characters in the topic's output. That means one or more of the following:
  • Splitting topics into smaller chunks.
  • Not having over complex CSS styles, particularly in table styles. 
  • Checking the topic's HTML for any unnecessary characters (e.g. "&#160;" or "<span>" tags).
  • Removing all unnecessary topic text. This is a great way to improve your editing skills and reduce localization costs.
  • Use shorter topic titles and headers.
  • Only use hyperlinks and bookmarks where necessary.

No comments:

Post a comment