XMetaL Tips and Tricks
Su-Laine Yeo February 12, 2010 at 9:56 pm
Tutorial: Customizing XMetaL WebHelpFebruary 12, 2010 at 9:56 pmParticipants 7Replies 8Last Activity 12 years, 4 months ago
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
- 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.
- Open a sample DITA map file by clicking Help > Samples > XMetaL Reviewer Help (DITA).
- Click File > Generate Output for DITA Map.
- From the Deliverable Type drop-down, choose WebHelp. Click OK.
- 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:
- Back up the following folder: C:Documents and Settings
Application DataSoftQuadXMetaL SharedDITA_OT.
- Click Tools > Configure Output
- Click the Advanced tab.
- Change the parameter cmd_dita_ot_per_user_version =
to make the 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.
Output should look like this:
- Download and unzip the attached WebHelp_Customization.zip package.
- Open the following folder on your local machine: C:Documents and Settings
Application DataSoftQuadXMetaL SharedDITA_OTdemowebhelpcustomization. Back up this folder.
- Copy the common folder in the customization package you downloaded, into the C:Documents and Settings
Application DataSoftQuadXMetaL SharedDITA_OTdemowebhelpcustomizationfolder on your local machine. Accept prompts to replace files.
- In XMetaL Author Enterprise, generate WebHelp output.
Here are the some things that you can change in WebHelp output by editing files in the DITA_OTdemowebhelpcustomizationcommon 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 xmwebhelpimagesheader_bg.gif file.
Alternatively, you could edit the #whHeader selector in the xmwebhelpwebhelp.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 xmwebhelpimagesbutton_bg.gif file.
Alternatively, you could edit the #whHeader li selector in the xmwebhelpwebhelp.css file.
Fonts used in the top and left navigation pane xmwebhelpwebhelp.css URL that the “Home” button links to xmwebhelpcommon_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.
Output should look like this:
- 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.
- Open the My Documents folder on your local machine.
- Copy the WebHelp_Custom folder in the customization package you downloaded, to your My Documents folder.
- In XMetaL Author Enterprise, click File > Generate Output for DITA Map.
- Click Configure Output.
- In the list of Deliverable Types, select WebHelp.
- Click Edit.
- 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
My DocumentsWebHelp_Custom tutorial_custom.cssfile.
- Click the Browse button next to the Page footer (FTR) field. Browse for and select the C:Documents and Settings
My DocumentsWebHelp_Custom tutorial_custom-ftr.htmlfile.
- Click the Advanced tab.
- In the Other output parameters field, type ANT_PARAM_args.copycss = yes .
- Click OK three times to save your changes and generate WebHelp output.
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 changeNote: When you generate WebHelp output, the following files are copied from the C:Documents and Settings
Application DataSoftQuadXMetaL SharedDITA_OTdemowebhelpCustom_Assetsfolder to the webhelp_out folder:
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.
[/html]Su-Laine Yeo April 26, 2010 at 10:28 pm
Reply to: Tutorial: Customizing XMetaL WebHelpApril 26, 2010 at 10:28 pm
The forum software keeps deleting my screenshots, so here is how WebHelp output will look after going through the tutorial:
[img]http://img148.imageshack.us/img148/7987/webhelpcustomizedsmall.png[/img]MathieuHarvey July 27, 2011 at 3:36 pm
Reply to: Tutorial: Customizing XMetaL WebHelpJuly 27, 2011 at 3:36 pm
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!Derek Read July 27, 2011 at 7:49 pm
Reply to: Tutorial: Customizing XMetaL WebHelpJuly 27, 2011 at 7:49 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.htmljlm05 May 22, 2012 at 6:38 pm
Reply to: Tutorial: Customizing XMetaL WebHelpMay 22, 2012 at 6:38 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?
JaniceDerek Read May 22, 2012 at 8:28 pm
Reply to: Tutorial: Customizing XMetaL WebHelpMay 22, 2012 at 8:28 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?jlm05 May 23, 2012 at 1:47 pm
Reply to: Tutorial: Customizing XMetaL WebHelpMay 23, 2012 at 1:47 pm
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.
JaniceDerek Read May 23, 2012 at 4:30 pm
Reply to: Tutorial: Customizing XMetaL WebHelpMay 23, 2012 at 4:30 pmDerek Read May 23, 2012 at 4:32 pm
Reply to: Tutorial: Customizing XMetaL WebHelpMay 23, 2012 at 4:32 pm
I'm assuming you mean this one?
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.
- You must be logged in to reply to this topic.