Pages: 1
Print
Author Topic: Tutorial: Customizing XMetaL WebHelp  (Read 12450 times)
Su-Laine Yeo
Solutions Consultant
Member

Posts: 260


« on: February 12, 2010, 03:56:39 PM »

This tutorial will help you understand what files to modify in order to customize WebHelp output for DITA documents.

You can publish DITA content in a variety of output formats, including browser-based WebHelp. The WebHelp output format is new in XMetaL 6.0. JustSystems considers it to be a "preview" of a feature as it is not as thoroughly tested or documented as other features in XMetaL. However, people are finding it useful and we have had many requests for documentation on how to customize it, so this tutorial aims to fill some of that need and to help people get around known issues.

In this tutorial, you will customize WebHelp output to make it look like the example here.

Making sure the WebHelp plug-in is installed

  1. Ensure that XMetaL Author Enterprise 6.0 or later is installed. See http://forums.xmetal.com/index.php/topic,498.0.html for instructions on finding your XMetaL version number.
  2. Open a sample DITA map file by clicking Help > Samples > XMetaL Reviewer Help (DITA).
  3. Click File > Generate Output for DITA Map.
  4. From the Deliverable Type drop-down, choose WebHelp. Click OK.
  5. When prompted, click Open File.

You should see a WebHelp system open in a web browser as shown below:

If you get an error message saying "Target 'dita2webhelp' does not exist in this project", follow the procedure below:

  1. Back up the following folder: C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL Shared\DITA_OT\.
  2. Click Tools > Configure Output
  3. Click the Advanced tab.
  4. Change the parameter cmd_dita_ot_per_user_version = <number> to make the <number> a higher number.

Then the next time you generate output you need to say "yes" when asked if you want to redeploy the DITA Open Toolkit. The redeployed version will be the updated version that ships with 6.0 and that includes WebHelp. Note that if you previously customized files in the DITA_OT folder, you will have to re-integrate those changes from your backup after redeploying the DITA Open Toolkit.

Customizing the WebHelp navigation panes

In this exercise, you will customize the top and left navigation panes of WebHelp, by replacing the configuration files in a particular folder.

  1. Download and unzip the attached WebHelp_Customization.zip package.
  2. Open the following folder on your local machine: C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL Shared\DITA_OT\demo\webhelp\customization. Back up this folder.
  3. Copy the common folder in the customization package you downloaded, into the C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL Shared\DITA_OT\demo\webhelp\customization folder on your local machine. Accept prompts to replace files.
  4. In XMetaL Author Enterprise, generate WebHelp output.
Output should look like this:

Here are the some things that you can change in WebHelp output by editing files in the DITA_OT\demo\webhelp\customization\common folder:

To change this: Edit this file:
Color of the background in the top navigation pane In this tutorial, you made the change by changing the xmwebhelp\images\header_bg.gif file.

Alternatively, you could edit the #whHeader selector in the xmwebhelp\webhelp.css file.

Text and tooltips for buttons in the top navigation pane index.html
Color of the buttons in the top navigation pane In this tutorial, you made the change by changing the xmwebhelp\images\button_bg.gif file.

Alternatively, you could edit the #whHeader li selector in the xmwebhelp\webhelp.css file.

Fonts used in the top and left navigation pane xmwebhelp\webhelp.css
URL that the "Home" button links to xmwebhelp\common_param.js

The above changes require knowledge of HTML and CSS, but do not require knowledge of scripting. With advanced web development skills, you could make further customizations to the WebHelp navigation system.

Changing topic fonts and adding a custom footer

There are several ways to organize the files for changing the styling of topics within a WebHelp system. This tutorial covers one possible approach.

In this exercise, you will create a folder containing a new CSS file and a custom footer file, and configure XMetaL's WebHelp deliverable type to use those files.

  1. If you have not already done so, download and unzip the attached WebHelp_Customization.zip package. Note that you must be logged into the XMetaL Community Forums in order to download files. Registration is free.
  2. Open the My Documents folder on your local machine.
  3. Copy the WebHelp_Custom folder in the customization package you downloaded, to your My Documents folder.
  4. In XMetaL Author Enterprise, click File > Generate Output for DITA Map.
  5. Click Configure Output.
  6. In the list of Deliverable Types, select WebHelp.
  7. Click Edit.
  8. In the Edit Deliverable Type Dialog, click the Browse button next to the Specific CSS field. Browse for and select the C:\Documents and Settings\<username>\My Documents\WebHelp_Custom\ tutorial_custom.css file.
  9. Click the Browse button next to the Page footer (FTR) field. Browse for and select the C:\Documents and Settings\<username>\My Documents\WebHelp_Custom\ tutorial_custom-ftr.html file.
  10. Click the Advanced tab.
  11. In the Other output parameters field, type ANT_PARAM_args.copycss = yes .
  12. Click OK three times to save your changes and generate WebHelp output.
Output should look like this:

When each DITA topic is converted to HTML, the processor normally inserts a reference to the commonltr.css file into the HTML file for the topic. The above procedure makes the output processor insert references to both the commonltr.css file and the tutorial_custom.css file. The statements in the tutorial.custom.css file override the statements in the commonltr.css file.

The above procedure also makes the output processor append the contents of the tutorial_custom-ftr.html file to the end of the HTML file for each topic.

What not to change

Note: When you generate WebHelp output, the following files are copied from the C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL Shared\DITA_OT\demo\webhelp\Custom_Assets folder to the webhelp_out folder:
  • custom.css
  • custom-ftr.html
  • custom-hdr.html
  • custom-meta.html
  • custom_files\bg.gif

None of these files affects how output looks unless you specifically configure XMetaL to use them, so don't bother changing them. They are only samples of what can be put into files for configuring WebHelp output.

 

* WebHelp_Customization.zip (19.07 KB - downloaded 524 times.)
« Last Edit: February 16, 2010, 01:43:12 PM by Su-Laine Yeo » Logged

Su-Laine Yeo
Solutions Consultant
JustSystems Canada, Inc.
Su-Laine Yeo
Solutions Consultant
Member

Posts: 260


« Reply #1 on: April 26, 2010, 04:28:04 PM »

The forum software keeps deleting my screenshots, so here is how WebHelp output will look after going through the tutorial:

Logged

Su-Laine Yeo
Solutions Consultant
JustSystems Canada, Inc.
MathieuHarvey
Member

Posts: 2


« Reply #2 on: July 27, 2011, 09:36:46 AM »

Hi!

I followed the instructions for the "Customizing the WebHelp navigation panes" example, but it doesn't seem to work: the header is still green, not grey.

I also tried to modify the URL, but the change was not taken into account.

Can this be related to the fact that I installed XMetaL on a 64-bit computer?

I have encountered similar problems while trying to customize PDF output... I can change the text color of prereq sections of task topics, but cannot do the same for context sections.

Thanks a lot in advance for your help!
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2452



WWW
« Reply #3 on: July 27, 2011, 01:49:59 PM »

It sounds most likely like you have a system where the DITA OT has already been deployed and that you will need to redeploy the version you have modified. Please see the following post (and those it links to) regarding DITA OT "deployment":
http://forums.xmetal.com/index.php/topic,237.0.html
Logged
jlm05
Member

Posts: 79


« Reply #4 on: May 22, 2012, 12:38:46 PM »

We have someone testing the WebHelp customization on XMetal 7. They followed the instructions to add the customized files from the .zip file, but the output did not generate correctly (parts missing).

Should these instructions and files work out-of-the-box with Version 7?

Thanks,

Janice
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2452



WWW
« Reply #5 on: May 22, 2012, 02:28:13 PM »

I don't see anything in there that would break the WebHelp produced by XMetaL Author Enterprise 7.0.

Perhaps instead of overwriting existing files (and leaving everything else) you have removed something?
Logged
jlm05
Member

Posts: 79


« Reply #6 on: May 23, 2012, 07:47:29 AM »

I saw a reference elsewhere on the forum about a Webcast that you did with Scriptorium on customizing WebHelp.

Is that available anywhere? It's not on the Scriptorium site, and when I asked them about it I was referred back to you.

Thanks,

Janice
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2452



WWW
« Reply #7 on: May 23, 2012, 10:30:45 AM »

I'm not familiar with that one and it isn't listed here: http://na.justsystems.com/webinars.php

We record most things and link to them from that page, but perhaps this was done a long time ago? I'll check with our marketing people.
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2452



WWW
« Reply #8 on: May 23, 2012, 10:32:39 AM »

I'm assuming you mean this one?
http://forums.xmetal.com/index.php/topic,744.msg2364.html#msg2364

That doesn't look like a meeting we hosted and so it is unlikely we would have access to a recording of it. The meetings we host use WebEx. We do record those and post a link to the recording.
« Last Edit: May 23, 2012, 10:34:20 AM by Derek Read » Logged
Pages: 1
Print
Jump to:  

email us