Template variables

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: