Wednesday, April 16, 2014

How to set a favicon in Webhelp pages

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Small additions or customizations are frequently needed or desirable in the WebHelp pages generated by the DITA Map WebHelp transformation in Oxygen. This need will prompt a serial of blog posts with specific WebHelp customizations and the required source code modifications.

In the first installment let's see how we can add one of those small but significant details which lend a mark of distinction and help to increase the consistency with the overall website design theme: setting a favicon.  [ BTW the upcoming version of Oxygen will introduce a set of built-in WebHelp skins (design themes) and also a small WebHelp Skin Builder web app for visually building your own WebHelp skin/theme. Sounds like an interesting topic for a future blog post! ]

The recent versions of all the mainstream browsers (by that I mean the Web browsers with more than 3% Web usage share) will know how to interpret the following link XHTML elements:


<link rel="icon" href="/favicon.ico" type="image/x-icon"/>

<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"/>



The href attribute obviously must point to the favicon file available on the server which hosts the Webhelp pages.

These two elements must be inserted in the file:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl
in the template with the attribute name="create-toc-common-file", in the head element, after title:


<title> 
    <xsl:value-of select="$title"/>
</title>

<link rel="icon" href="/favicon.ico" type="image/x-icon"/>
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"/>


That's it! Repeating the WebHelp transformation will add the favicon to the title of the browser tab.

It would be nice to have a customization mechanism for separating the built-in WebHelp files and the custom code files, but that is an enhancement for a future version of Oxygen.