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.

4 comments:

  1. Anonymous12:41 PM

    Hello,
    I have struggled implementing this in oXygen 16. I finally figured out the solution: the link to the favicon should now be inserted in the template with the attribute name="create-index-file".
    Hope this will help others...

    ReplyDelete
    Replies
    1. You are right, if you use the index_frames.html main page you need to add the two <link> tags in the template with the attribute name="create-index-file". The post mentioned the location only for the index.html main page. Thank you for posting it.

      Delete
    2. It works well with oxygen author application but it is not working when I publish web help from plugin (using web help script) why?

      Delete
    3. If you make the same code modifications in the same createMainFiles.xsl file so that the same favicon image from the same location is added, you should get the same result in the WebHelp pages, regardless of how the WebHelp pages are generated: in the Oxygen application or from a command line.

      Please send us to support(AT)oxygenxml.com your code modifications for testing them in a WebHelp transformation both in the Oxygen application and from a command line.

      Delete