CHM and HTML templates can define template variables in the template.info file. Those variables will be presented in a user-friendly way in the documentation generation dialog and will be saved within the project file. The template can request for user-defined values and act upon them to customize itself based on user input. Possible template variables usages include:

  • Making a section optional. This is done in the default CHM and HTML templates with the breadcrumbs line which can be hidden from generated documentation
  • Customizing the documentation appearance. In the HTML template, it is possible to specify a base color, an icon set, default tree expansion status...
  • Provide localized texts. The default HTML template defines the captions for the "Index", "Search" and "Content" tabs as variables so that it is possible to translate them from within HelpNDoc

Defining template variables

Template variables are defined as sections in the template.info file. Those sections' name must begin with the var_ keyword followed by a unique variable identifier. Let's consider the following sample variable section:

[var_BaseColor]
name=Base color
kind=color
default=#EFEFEF
description=Customize the documentation's base color.

This defines a new variable with the following information:

  • Identifier is BaseColor
  • Name is Base color
  • Kind is color
  • Default value is #EFEFEF
  • Description is Customize the documentation's base color.

This will be displayed in the HelpNDoc template settings dialog as follows:

Variables section attributes

The following attributes should be defined in a variable sections:

Attribute

Description

Remarks

name

Name of the variable

Will be displayed to identify the variable in the settings dialog

kind

Kind of variable

Can be bool, color, enum, int, libitem, memo, string. See kinds of variables

default

Choose between multiple values

Default value for this variable if not set in HelpNDoc

values

Possible values for this variable

Only for enum variables, using the pipe character as a separator. Example: "blue|red"

description

Explanation for this variable

Will be displayed to explain the purpose of this variable

Kinds of variables

A variable can be set as one of the following kinds depending on its purpose:

Kind

Description

Remarks

bool

Conditional Yes/No value

Often used for a conditional section which will be displayed or not based on its value

color

Standard color value

Can be used to define the color of a specific element

enum

Choose between multiple values

Use the "values" attribute to specify the possible values. Example: "values=chm|folder|vista"

int

Integer value

libitem

Select a library item

Gives the ability to select an item from the library

memo

Memo value

string

Character, word or sentences

Setting-up template variables

Variables are set-up from within HelpNDoc's document generation dialog. CHM and HTML templates provide a "Customize" link which show the template customization dialog. This dialog lists all the variables for this template, and provides a way to customize them. Customized variable values will be saved with the current project.

Requesting template variables

To request the value of a template variable from within the template itself, use the HndGeneratorInfo.GetCustomSettingValue method specifying the variable identifier. As an example, the BaseColor value will be requested as follows:

HndGeneratorInfo.GetCustomSettingValue('BaseColor');