Table of Contents

n2pdf has a feature to automatically generate a table of contents and add it to the PDF file. You can even make the individual entries within the table of contents clickable, integrate page numbers and configure the table of contents using text templates (see N2PDFVALUE_TOC_PARAGRAPH_NAME ).

Content must have a certain formatting in order for n2pdf to recognize it as an element of the table of contents. These elements work on the same principle as the variables, but have a fixed name and defined syntax.

If there are wildcards with the format "[TOC:?]" included in the main text, then those sections of the text which they precede will be interpreted as an entry for the table of contents. In this case this section's text is accepted as an entry for the table of contents. The wildcard "?” stands for the table of content's level, i.e. which numerical level this entry should occupy. The specific number that a given entry is assigned depends on the entries' order of appearance.

The existing wildcard [TOC:?] can be supplemented by a further parameter. It must be separated with the "|" (pipe) symbol from the existing content. The new expression then appears as follows: [TOC:?|<Text for TOC>]. This makes it possible to use an alternative text for the TOC/outline entry. You may also choose to leave the entry blank. This makes it possible to have a different text for the chapter heading, for example.

Example: From the following text ...

[TOC:1]Getting Started

Welcome to Lotus Notes! Lotus Notes gives you instant access to all the information that is …

[TOC:1] What is Lotus Notes?

Lotus Notes is powerful, multi-faceted software for …

[TOC:2] Getting Help

Online Help is available for most views and dialog boxes. You can ...

... will be created this table of contents:

1.        Getting Started

2.        What is Lotus Notes?

2.1.        Getting Help

You can write these wildcards for creating a table of contents directly into the text of a Rich Text field and then add the table of contents to the PDF file using N2PDFAddRTContent or, for example, you can use the function N2PDFAddContent to apply the content from an unformatted field.

Example: In the document there exists a field with the name "ChapterLevel" for the level and "ChapterTitle" for the title. The additional content is then read from the RichText field "Body".

TOCText = "[TOC:" + Trim$(CStr(doc.ChapterLevel(0)))+"]" +_

CStr(doc.ChapterTitle(0)) + Chr(13)

Call N2PDFAddContent ( JobID, N2PDFVALUE_CONTENT_BODY,_

N2PDFVALUE_CRLF_AFTER, TOCText )

Call N2PDFAddRTContent ( JobID, N2PDFVALUE_CONTENT_BODY, PageBreak,_

db.Server, db.FilePath, doc.UniversalID, "Body")

Example: In contrast to the example above, the field "ChapterTitleTOC" is used for display in the TOC and the field "ChapterTitle" is used for the display as the chapter header.

TOCText = "[TOC:" + Trim$(CStr(doc.ChapterLevel(0)))+"|" + CStr(doc.ChapterTitleTOC(0)) +"]" +_

CStr(doc.ChapterTitle(0)) + Chr(13)

The function N2PDFSetOption is used to control the appearance of the table of contents. Below is a listing of all the setting options for the table of contents that can be selected using <OptionID>. You can set the individual values for the options using <OptionString> and <SubOptionStr>.

N2PDFOPTION_TOC

Use this parameter to turn the "create table of contents" function on or off.

Example for creating a table of contents:

Call N2PDFSetOption ( JobID, N2PDFOPTION_TOC, N2PDFVALUE_True, "" )

N2PDFOPTION_TOC_PAGENUMBER

With this parameter you can specify the page on which the table of contents is to be created within the PDF. You can assign the page number as the value under <OptionString> or you can set the value to N2PDFVALUE_TOC_DEFAULT_PAGE if you want to use the default page number one.

Example – Create table of contents on page 5:

Call N2PDFSetOption ( JobID, N2PDFOPTION_TOC_PAGENUMBER, "5", "" )

N2PDFOPTION_TOC_CREATE_LINKS

Use this parameter to control whether or not hyperlinks in the PDF will be clickable, i.e. if the hyperlinks depicted as text (http://www.svd-online.com) will be converted into genuine clickable links.

Example – Convert hyperlinks:

Call N2PDFSetOption ( JobID, N2PDFOPTION_TOC_CREATE_LINKS,_

N2PDFVALUE_True, "" )

N2PDFOPTION_TOC_HEADER

N2PDFOPTION_TOC_FOOTER

You can use these two parameters to render additional text before and after the table of contents. Here you can input content that might contain variables, which in turn can be filled with RichText content. You can input the content using the value <OptionStr>.

N2PDFOPTION_TOC_NUMBERSTYLE

N2PDFOPTION_TOC_NUMBERCHAR

The type of numbering is yet another configuration feature for the table of contents. You can choose from the following different types:

You can also specify the kind of separators used between the individual characters. These varieties are available:

Examples for specifying "A)"

Call N2PDFSetOption ( JobID, N2PDFOPTION_TOC_NUMBERSTYLE,_

N2PDFVALUE_TOC_NUMBERSTYLE_LARGE_A, "1" )

Call N2PDFSetOption ( JobID, N2PDFOPTION_TOC_NUMBERCHAR,_

")","1" ) )

The latter parameter of the N2PDFSetOption function denotes here the level in the table of contents where this depiction is set to be used.

N2PDFOPTION_TOC_OUTLINE_ENTRY

This parameter allows the creation of an entry for the TOC in the outline. The text specified via N2PDFOPTION_TOC_HEADER is used for the outline.

Example:

Call N2PDFSetOption ( JobID, N2PDFOPTION_TOC_OUTLINE_ENTRY,_

N2PDFVALUE_True, "" )        

N2PDFOPTION_TOC_HEADLINE_INDENT

This option allows the spacing between the pagination and the following text to be set. The spacing is defined as an indent relative to the left margin of the text (not that of the paper margin). The first parameter contains the value of the indent, the second the level of the TOC headline (1-9).

Sample: 5 cm indent for the TOC headline of the level 2 (e.g. "2.3. Headline")

Call N2PDFSetOption ( JobID, N2PDFOPTION_TOC_HEADLINE_INDENT, "5", "2" )

N2PDFOPTION_TOC_TEXT_KEEP_NEXT

This parameter keeps headlines (the chapter text for the TOC) and the following text together. It is possible, when a PDF file is created, that a page break may occur between a headline and the following text. This may lead to unwanted effects. If this option is activated, then n2pdf will always attempt to keep the headline and the following text together and will place a page break before the headline, if one is needed.