MadWorld 2013 – Customizing HTML5 and WebHelp: Modern Output Matching Your Company Style

Again, stomach I’m honored to present at the 2013 MadWorld Conference today in SanDiego. Today I present on customizing HTML5 output.

This post includes links to the slides, viagra videos, viagra approved and source code that I used in this presentation. This is meant both for conference participants as well as all blog readers, giving you a flavor of what was presented today at MadWorld.

Here is a link to the PowerPoint Presentation itself (10MB).

The Content

Now, for an abbreviated version of the presentation.

When trying to take all the information that is available about styling Flare output and distilling it into a 50 minute presentation, I decided to focus on four key areas:

  • Modifying the HTML 5 skin
  • Using webfonts
  • Brief introduction to responsive layout
  • Making dramatic changes to Flare output

Let’s start with modifying the HTML 5 skin file

Because this is a presentation rated for beginners and intermediate Flare users, I want to discuss each of the tabs in the skin editor. In Flare, the skin file is the bread and butter of how the webpage is construted. The skin file controls most aspects of the framework that displays your help content. It controls the logo, the icons in the toolbars, which tabs display, the colors of the tabs and icons, etc.

Open an HTML 5 skin in Flare, and you see the skin editor which has several tabs.

I won’t discuss each tab in great detail for three reasons:

  1. This is pretty basic stuff and is covered extensively in the Flare help system.
  2. Recent versions of Flare give you a lot of contextual help in the skin editor.
  3. I want to spend the bulk of our time on some of the non-standard changes you can make.

The General tab

On this tab, I just want to point out that the term “Caption” means “HTML frame set page title.” In HTML 5 this isn’t used because instead the page title in the browser is the same as the topic that is being displayed. In standard WebHelp, this Caption is how you get a title on the frames et. In HTML 5 you can leave this field blank, and nobody will ever notice.

Flare 9 includes an option to keep or remove unreferenced images. This is because the skin file is one of the few binary files in Flare. When you add an icon (like a book icon, or a print icon, etc.) to Flare, the skin file stores the binary of the image in the skin file itself, rather than referencing the image from another location. If you add an image to the skin file, and later replace it, this option tells the skin file whether to keep the unreferenced, old image, or to delete it when you save the skin.

The Size tab

You can ignore this tab. Let your developers have control over how the help system looks when they call it.

The Setup tab

Two important things to note here. First, the Pane Position and Size options. Please choose either a left or right pane position. Nobody wants to see your tabs on the top or bottom of their help system.  The pane size is the width of the left navigation pane when it opens. Users can drag this to make it wider or narrower.

The Toolbar Tab

This tab lets you select which icons appear on the toolbar above the topic. If you aren’t connected to Feedback or Pulse, your only real options are Print, Expand All, and Remove Highlight. However, if you want you can add custom Javascript. Note, this isn’t for a specific button. This is for the toolbar page, so this javascript is loaded each time the toolbar is loaded. I haven’t found this useful yet, but if somebody uses it, I’d love to hear about it.

Also, you can click the new toolbar button button to add a new button to the toolbar. Clear as mud? I’ll show you how this works in just a minute.

The UI Text tab

Let’s jump down to the UI Text tab. This tab lets you modify the actual text that is displayed in the user interface. So, if you don’t want it to say “TOC”, you can easily change it to something else here, like “Contents”.

The Styles tab

Here is the meat of where you set up how your HTML 5 output looks.

This should feel familiar to those of you who use the advanced version of the CSS editor in Flare. This works the same way. Pick the item you want to style from the column on the left, and use the properties on the right to change the settings.

The top of this list is full of Feedback settings. I wish they were grouped together into a single top-level entry for those of us who don’t use Feedback, but just scroll down past them.

On this screen note that if you select Logo, you can use your own company logo instead of the default MadCap logo. Expand the Background section, and edit the BackgroundImage property.

Sometimes people ask whether or not they need to use an icon here. In HTML5, there is no Home button on the toolbar, so if you don’t include a logo, the users have no way of going back to your output’s start page. For this reason, I recommend you include something.

Look how items are grouped in the Styles list. Lots of the individual settings you want to create are hiding in these groups.

When I first started working in Flare, I didn’t realize that I can make settings for ALL THE ITEMS IN THE GROUP by making those settings on the parent node. I was opening each of these items and changing all the settings, trying to make them all identical. That is not necessary. Set the global properties on the parent node, and then just set the unique settings on the child nodes.

Let’s talk about editing the toolbar icons. First, note that in HTML5 there is only one image: “BackgroundImage”. In WebHelp, there were three different images, one for normal, one for hover, and one for click. HTML5 is MUCH simpler. You only have one image because there are no “hover” or “click” effects.

Ok, remember how we wanted to add a custom button? Let’s say I added a custom button to link to my Facebook page.

Notice that my custom buttons show up in the styles list, so I can add my own settings.

You need to set two things for custom buttons: (1) the BackgroundImage, and (2) the Click event. The background image is the button icon. The click event is javaScript code that is executed when users click on the button.

So that is your whirlwind overview of customizing the skin file itself. Lets move on to Webfonts.

Webfonts

What are webfonts, you ask? Webfonts are font files stored on a webserver, and they are called and used like any other online resource. They allow you to use non-web-standard fonts, with a reasonable assumption that most internet-connected users will be able to see the content in that non-standard font.

If a user loads a webpage using a webfont while not connected to the Internet (think government contractors, for example) the computer would be unable to locate the font resource, so it would fall back on the next font defined in the style sheet.

If you have a secure site, you will need to load your webfonts from a secure server, or users will get an error that some elements on the page are not secure. This is outside the scope of this particular discussion, but I wanted to point it out and let you know I found the solution by googling it.

Please be aware that you need to be very careful about posting fonts on a web server. Most fonts on your computer are covered by intellectual property laws, and you are bound by the terms of the license agreement. Most font license agreements do not permit you to post the font on a webserver. To be safe, I use fonts from a trusted source: Google Web Fonts, which can be found at google.com/fonts.

So, how do you use Google web fonts? First, visit their site, pick the font you want to use, and then review your collection. Then you add the proper code to either your CSS style sheet or your Flare MasterPage. I recommend using the CSS method, but you can do whatever works for you. Google gives pretty good directions on its site.

Once you have the URL, you paste it into the top of your CSS stylesheet.

WebFonts Now, just use the proper name of the font in the “font-family” declaration. In my site, I set the font family for my heading 1 to be “Permanent Marker,” and the font-family of the body tag to “Noto Sans.”  Note that I used the body element, so that I didn’t have to add it to every individual child element. If I hadn’t done it in Body, I’d have to do it separately in <p>, <li>, <table>, <heading(s)>, as well as the MadCap-specific elements like drop-down text. When it is in <body> it is automatically inherited by all of <body>’s child elements.

The image on the right shows the rendered result.

So, there are a couple of caveats. Webfonts work best on, you guessed it, the web. Webfonts do NOT work in PDF targets. You need to use a local font for PDF targets. (You can set this either in the Print section of the style sheet, or you can use a standard font as part of the cascade in the font-family declaration.)

You can also try downloading the font from Google. (The fonts are free.) Install the font in Windows, and then open Flare and see if you can access the font in the CSS editor. (If Flare is open when you add the font to Windows, Flare won’t be able to use it until you restart Flare.) Due to limitations of the .NET framework that Flare uses, Flare is not able to recognize all fonts on your system, so this process may be hit or miss.

Ok. Let’s talk responsive layout, then.

Responsive Layout

First, I know that there is a technical difference between responsive layout and adaptive layout. Since this is a pretty basic introduction to the concept I use the term responsive, even though it might not be the most correct term for a more technical audience.

Websites that are responsive use specific sections of the CSS style sheet depending on the conditions of the viewport. This isn’t new to Flare users, since you’ve been using the Print section of the style sheet. This is just another section of the stylesheet, but rather than being based on media type (print versus online), these styles are used based on other properties.

Here is an example of a responsive website. Open the window full screen, then reduce the size of the browser. Watch how, as you drag, the elements on the page change. Some content disappears, some of it moves to a different location. This is responsive design in action.

Responsive layouts are supported by all current browser versions, though IE has only had support since IE9. All in all, about 86% of users world-wide are using browsers that support responsive layouts. But don’t worry. The responsive section of  the CSS is just ignored by those browsers, but all your standard settings will still work — it will be no different than they get today. And since responsive design is really geared for mobile users, or users of tablets and smaller devices, you don’t need to worry too much about the older IE support.

So, how does it work?

In your style sheet, add the following code:

[code]@media (PROPERTY: SETTING) { ELEMENT { STYLE: ATTRIBUTE; } }[/code]

For example:

[code]@media (min-width:500px) { h1 { font-size: 24pt;} } [/code]

There are a lot of properties you can pick from including min-width, max-width, device orientation (portrait vs. landscape), screen resolution, etc.

Here is a link to a site that gives you a good starting point for what types of queries you could use depending on devices you were targeting. Here is an abbreviated version of the CSS I used in my Flare project to move the content from two columns to one, depending on the viewport size.

Responsive table comparison of styles

Lets take a look at some of those styles side by side. In the left column you see the standard settings set in the main section of the style sheet. These are the styles that will be used when one of the media types does not match. (In this case, anytime the viewport is 911 pixels or wider. In my case, I have a wrapper that has a nice border around it, and I specify a size setting for the wrapper.

When the viewport width is between 475 and 910 pixels, I allow the wrapper to reduce in size. When the viewport is narrower than 475 pixels I remove the drop shadow, remove the border, remove the margin, and set the width to 100% of the viewport width.

I also have a two column layout. The standard layout is to have two columns that float next to each other. However, when the window with is below 910 px, the second column drops below the first column, so the users don’t have to scroll horizontally. When the width drops below 475, I ensure the column gets 100% of the width to make it easy to see.

The second column works just like the first, but in the standard view, it floats right.

Finally, let me show you one site I worked on where I radically changed the way HTML5 output looks.

Dramatic Changes to HTML5 Output

ADVA-beforeYou are not necessarily limited to what changes you can make in the HTML5 skin file in Flare. If you are willing to get your hands a little dirty in the code, and make some post-production changes, it isn’t too hard to radically alter the way the help system looks. I had a client who wanted to dramatically alter the way HTML5 output looked, because they wanted it to more-closely match their website’s UI. The image at right represents as close as I could get making the edits in the HTML5 skin editor. However, this wasn’t exactly what they were looking for.

They wanted the search box on the left side of the screen, and their logo on the right side of the screen. The wanted corners to be more round, and they wanted text in the toolbar that is above the topic. The left column was to be a single tab, not multiple tabs, and it needed to look like a column header, not a tab.

The trick to making these changes was opening the default.htm file that was generated in the Flare output, and then making changes to that file. The changes to the styles and such in that file override any styles set in the style sheet, so I was able to get a very granular-level of control over the output’s details.

After-changesHere is what I was able to create for them with those tweaks to the default.htm file. This change requires the client to copy over the modified “default.htm” file into the output after each build, but the look and feel to the client was more important than that minor detail. The changes I made were for Flare V8. If the client were to upgrade to Flare V9, they would need to make different changes, because in Flare V9, MadCap modified the default.htm file. I’ll post my code modifications so you can see what they did, but please note that if you are using Flare V9, these modifications are not correct. They were for Flare V8 only.

Annotated default.htm fileHere is a screen shot of the source code. I’ve highlighted the sections of the document that I changed. It is also worth noting that I removed a bunch of extra code that wasn’t needed. Some of it looked like commented code that wasn’t removed before V8 was released. Other parts were for websites where the navigation panel was in a different position. So this is a simplified default.htm that only included the parts that V8 needed to display the page based on the configuration the client had chosen.

If you want to see this customization live, you can visit help.zebrazapps.com.

I hope this has provided you with some ideas on how you can modify your HTML5 output to match your company’s style. If you have questions or want clarifications, please let me know in the comments below.

, , , , , , , , ,

3 Responses to MadWorld 2013 – Customizing HTML5 and WebHelp: Modern Output Matching Your Company Style

  1. wpmnger May 15, 2014 at 10:49 am #

    Thank you Paul for sharing.

    Do you know of any way to use Flare to edit the default.htm instead of you having to manually override it each time?

    Thanks,

    • Paul May 15, 2014 at 1:24 pm #

      Hi wpmnger,

      Great question. Thanks for asking.

      You can go in and modify the default.htm file that Flare uses to generate output, but there are four important caveats to think about:

      First (and probably most importantly), you can break Flare by doing this. This is unsupported. If you go this route, make backups of all files you edit so you can restore them if things go terribly wrong. USE AT YOUR OWN RISK. If it voids your Flare warranty, causes you to lose data, makes your car stop working, or changes your first-born’s hair to purple, you can’t blame me or MadCap, because we warned you that there is potential for things to go terribly wrong. (Worst case scenario, you uninstall and re-install Flare to get everything back to the way it was, so actually the overall risk is pretty low, but don’t come back later telling me you weren’t warned! )

      Second, the steps I describe affect ALL HTML5 outputs that you create. Only make these changes if you are certain you always want to generate all HTML5 outputs with these settings forever more. If the answer is “I’m not sure” then you are better off doing post-processing to adjust the file.

      Third, we’re changing some core Flare files that WILL GET OVERRIDDEN by any Flare update. That means once you have the file adjusted to do what you want, you should back up that file as well so you can re-make the changes when Flare is updated. Related to this, write down someplace what files you changed and why. At some point, you’re going to need to go back into the bowels of Flare’s source code and re-do these changes or modify them in some way. You will be happier at that point if you have a record of what you changed and why you did it. If you are at all like me, I forget what changes I made for what specific purposes. Documentation is important even for technical writers (gasp!).

      Finally, these changes will only work on your own computer. If you are authoring in a team environment, you will need to make these changes on each machine to ensure any user generates the same output that you generate. When you replace your computer or re-image the hard drive, you’ll need to make these changes again. These changes are NOT project-specific, so they don’t live in the project files. (See the second warning, above.)

      Have I scared you sufficiently yet? 🙂

      If you’re still with me and are willing to make the changes, here is what you can do. After all that preamble, you are going to think this is relatively simple.

      The core source files Flare uses for generating HTML 5 output live in the following location on your hard drive:

      C:\Program Files (x86)\MadCap Software\MadCap Flare V10\Flare.app\Resources\WebHelp2\Desktop

      (If you have a 32-bit machine, you won’t have a “Program Files (x86)” folder, you’ll just have a “Program Files” folder. Flare is a 32-bit program, so on a 64-bit OS it installs into the 32-bit program files folder. If you don’t know if you have a 32- or 64-bit machine, just look in the C:\ directory. If you have a “Program Files (x86) folder, then you have a 64 bit machine.)

      Now you can open the Default.htm file in that location, make a backup (I like to call mine Default.htm.old or Default.htm.original so I can keep track of it). Once you’ve made the backup, you can edit the file to your heart’s content. When you generate output, Flare will use this Default.htm as the template for your HTML5 output.

      If your changes broke anything, then you’ll have to go undo them and figure out what went wrong.

      Good luck. I hope this helps!

  2. Rachana May 4, 2015 at 3:59 am #

    I would like to know how do you add feedback box in the webhelp output and append the content to the file.

    and also 1. Auto search content page from Salesforce CRM and do SEO.

    Thanks

Leave a Reply