Themes

When it comes to customizing help files, Help Producer themes offer you ultimate flexibility. If you want to automatically create content, post-process the HTML topic files so that they meet your corporate standards, etc, then themes are for you. Since this is a very powerful and complex feature, you need to have a working knowledge of HTML, XML, CSS, and JavaScript in order to work with themes. If you never programmed in JavaScript or another scripting language, you will have to seek help from a software developer skilled in writing web applications.

What’s a Theme Anyway?

A Help Producer theme is a collection of scripts, HTML files, and images that will allow you to change the looks of your help file in a programmatic way. When you export, compile, or display a help document, Help Producer will invoke the scripts of the theme. What happens then is really up to the programmer that created the theme.

Help Producer comes with a complete programming framework with over 100 objects tailored for making help systems. The possibilities are virtually unlimited.

Contents of a Theme

At a minimum, a theme consists of three files:

A theme configuration file. The name must always be named theme.xml.
A build script, named build.js.
A project configuration file, named project.hpprj.

The configuration file theme.xml instructs Help Producer about the name of the theme, and where to find other files. A simple configuration file may look like the following:

<?xml version="1.0" encoding="utf-8" ?>
<HelpProducerTheme Version="1.1">
      <FileInfo Name="The theme name" Description="The theme description." />
      <Script Path="build.js" />
      <Settings Path="project.hpprj" />
</HelpProducerTheme>

In the example above, a script and a settings file is referenced. The script can include event handlers, which are invoked by Help Producer when the theme is loaded, or when the help project is exported, compiled, or viewed.

For instance, you could override the Application.ProjectExport event, because you need to do some post-processing of the HTML files when they are exported. A simple event handler for the Application.ProjectExport in JScript could look like this:

function Application::ProjectExport(wordDocument)
{
   Project.Filter.ParseDocument(wordDocument);

   // Do some post-processing of the topics.
   PerformMagicOnMyTopicFiles();

   Project.Filter.ResolveHyperlinks();
   Project.Filter.GenerateTopicFiles();
   Project.Filter.GenerateProjectFiles();
}

In the example above, when you click the Export toolbar button, Help Producer would parse the current Word document, and then call a function that performs some post-processing on the HTML files. For instance, you could insert a few HTML tags around the content generated by Help Producer, or make whatever change you desire.

Creating a Self-Contained Theme

A self-contained theme is a collection of input files, compiled into a single file. To create a self-contained theme, use the Help Producer Theme Make Utility mkthm.

The syntax for mkthm is

mkthm -o <outputfile> inputfiles

For instance, to create the theme ‘mytheme.hpthm’ from the files theme.xml, project.hpprj, build.js, and all files from the misc sub-folder, run the following command:

mkthm -o mytheme.hpthm theme.xml project.hpprj build.js misc\*

To use the theme, copy the .hpthm file to the Help Producer theme directory, located at “ProgramFiles\MGTEK\Help Producer\Themes”, and select the theme in your Help Producer project.

What’s a Theme Anyway?

Contents of a Theme

Creating a Self-Contained Theme

Further Reading

See Also