Building a single page HTML template

In this section, we will create a new HTML template from scratch. This template will create a single-page HTML documentation where all the topics are grouped on that single page. The final version of this template is installed with HelpNDoc and can be found in the "My Documents\HelpNDoc\Templates\html\SinglePage" directory.

Template directory

First we need to create a directory for the new template. Custom templates are located in the "My Documents\HelpNDoc\Templates" directory. As we are creating an HTML template which we'll call "SinglePage", we will create the following directory for our new template: "My Documents\HelpNDoc\Templates\html\SinglePage".

The template.info file

Each template must include a "template.info" file with basic template information. Let's create one in the template directory with the following content:

[config]
name=Single page HTML template
extension=html

Template code file

It's time to go to the heart of our template by creating a new file which will contain the code to instruct HelpNDoc on how to generate our HTML file. To be interpreted by HelpNDoc, the file must contain the ".pas" text before its extension, which means it will contain Pascal code. So let's create a file named "index.pas.html" in the template directory and edit using any text editor.

Any text which is added to that file will be written as is in the final output, except if it is included in the <% %> tags, which are used to insert special instruction code. The steps involved to create the initial code are:

Instruct the template system to output the HTML file BOM (Byte Order Mark). This is only necessary for HTML files in Internet Explorer on Window with some languages (1)
Instruct the template to output to the user defined file as we are only generating a single file (2)

So the "index.pas.html" file now contains:

<%
begin
// 1. Output BOM for HTML UTF8 files
HndGeneratorInfo.BOMOutput := True;
// 2. Instruct the generator to generate the desired output file
HndGeneratorInfo.CurrentFile := ExtractFileName(HndGeneratorInfo.OutputFile);
%>

<html>
<head>

</head>

<body>
Sample HTML Code
</body>
</html>

<%
end.
%>

Get the topics list

Templates have access to a number of functions, objects and variables to help them generate an output. We first need to get a list of topics available in the current project. To do so, we create a new variable before the "begin" keyword and request the topic list (3). The "index.pas.html" file now contains:

<%
// Variable declarations
var
// List of topics available in the current project
aTopicList: THndTopicsInfoArray;

begin
// 1. Output BOM for HTML UTF8 files
HndGeneratorInfo.BOMOutput := True;
// 2. Instruct the generator to generate the desired output file
HndGeneratorInfo.CurrentFile := ExtractFileName(HndGeneratorInfo.OutputFile);
// 3. Get the list of topics available
aTopicList := HndTopics.GetTopicList(False);
%>

<html>
<head>

</head>

<body>
Sample HTML Code
</body>
</html>

<%
end.
%>

Output the topics' content

Now that we have a list of topics, we can output their content by looping through that list. The steps involved are:

Create an iteration variable (4) - This variable will be used by the loop
Loop through the topics (5) - The topics are treated one by one in that loop
Notify the template system about the current topic being generated (6) - The template system can't know which topic is currently treated, that's why we notify it using the HndGeneratorInfo object
Output the topic content (7) - We ask for the HTML content of the topic and we output it

The "index.pas.html" file now contains:

<%
// Variable declarations
var
// List of topics available in the current project
aTopicList: THndTopicsInfoArray;
var
// 4. Current topic index
nCurTopic: Integer;

// Main program
begin
// 1. Output BOM for HTML UTF8 files
HndGeneratorInfo.BOMOutput := True;
// 2. Instruct the generator to generate the desired output file
HndGeneratorInfo.CurrentFile := ExtractFileName(HndGeneratorInfo.OutputFile);
// 3. Get the list of topics available
aTopicList := HndTopics.GetTopicList(False);
%>

<html>
<head>

</head>

<body>
<%

// 5. Loop through all the topics
for nCurTopic := 0 to length(aTopicList) - 1 do
begin
// 6. Notify about the topic being generated
HndGeneratorInfo.CurrentTopic := aTopicList[nCurTopic].id;
// 7. Output the topic content
print(HndTopics.GetTopicContentAsHtml(HndGeneratorInfo.CurrentTopic));
end;

%>
</body>
</html>

<%
end.
%>

Add the titles

The template now display the whole content of all the topics in a single page. However, no title is displayed. Let's add the topic titles before the topics as well as an HTML anchor to be able to link to that topic later on. The steps involved are:

Declare a new variable nTopicLevel (8) - This variable will be used to get the level of the topic and output the correct HTML heading to the topic title
Output an HTML anchor (9) - This anchor will be used to link to that specific topics afterwards
Get the topic level (10) - We request the level of the current topic so we can output the correct HTML heading
Output the topic title (11) - We can now correctly output the title of the topic

Between steps (6) and (7) we now add the following lines in the "index.pas.html" file:

// 9. Add an anchor to be able to link to that topic
printf('<a name="%s"></a>', [aTopicList[nCurTopic].helpid]);
// 10. Get the topic level
nTopicLevel := HndTopics.GetTopicLevel(HndGeneratorInfo.CurrentTopic);
// 11. Add the topic title
printf('<h%d>%s</h%d>', [nTopicLevel, HndTopics.GetTopicHeaderTextCalculated(HndGeneratorInfo.CurrentTopic), nTopicLevel]);

Adding some style

The output now contains all the content from our documentation but it doesn't look like what we've designed in HelpNDoc. That's due to the fact that we didn't add any style coming from HelpNDoc. This can be done in a single step, by requesting for the style content and adding it into the HTML's head section (12). To do so, we add the following lines in the "<head>" section of the "index.pas.html" file:

Fixing the links

The output looks as we designed it now but links to topics are not working correctly. This is due to the fact that by default, HelpNDoc assumes that each topic will be generated in its own file which will be named "%helpid%.html" where "%helpid%" is the help id of that topic, as explained in the "Handle the generated topic links" topic. This can be customized: to change this default behavior, we need to edit the template.info file and add the following key/values in the config section. They define the format for topic links and anchor links:

linkformattopic=#%helpid%
linkformatanchor=#%anchorname%

Final touches

As we have seen, the possibilities are endless: we could add some custom-made CSS file in the assets folder to customize the HTML headings, add the title of the project, the copyright, completely modify the look and feel of our web-page, split it in sections... Some of those ideas are added in the final sample file which is installed with HelpNDoc and can be found in the "My Documents\HelpNDoc\Templates\html\SinglePage" directory.