In this guide you'll learn how to add a table of contents to a PDF using Muhimbi PDF Converter for SharePoint and Muhimbi PDF Converter API.
Object Model
This section explains the generation of a Table Of Contents via our API. You can also use this functionality from a SharePoint Workflow as well. You can also use our XML based workflow syntax to generate a table of contents from SharePoint Designer, Nintex and K2 based workflows.
The classes relevant to dealing with TOCs are displayed below and are as follows:
- MergeSettings: When merging multiple files and generating a single table of contents, follow the normal procedure for merging files (sample code) and populate the MergeSettings.TOCSettings property as per the sample code below.
- ConversionSettings: To generate a table of contents for a single document, follow the normal procedure for converting or processing a single file (sample code) and populate ConversionSettings.TOCSettings as per the sample code below.
- TOCSettings: All settings related to the generation of the table of contents can be found in this class. The available properties are as follows:
- Bookmark: The TOC itself can have its own PDF bookmark to aid with navigation. Specify the text in this property.
- Location: TOCs can be added to the Front or Back of the document. Enter the relevant option here.
- MinimumEntries: For certain, simple, documents that only have one or two bookmarks, it may not be beneficial to add a table of contents. Specify the minimum number of entries here before a TOC is generated. The default value is ‘0’, which will always create a TOC regardless of the number of entries.
- PageMargins: Page margins in the format set out below. It defaults to a uniform half inch margin.
"#{dim}"- for a uniform margin or"#{dim},#{dim},#{dim},#{dim}"- for individual margins where#is numeric value{dim}is dimension. Either empty (meaning inches) or "mm", "in", "in.", "inch" or "inches".
- PageOrientation: The orientation used by the TOC. Portrait, Landscape or Default. The Default option uses the same orientation as the page following (or preceding) the TOC depending on the value specified in Location.
- PaperSize: A named paper size such as A4 or Letter (See MSDN) or a custom size in "{width}{dim}{sep}{height}{dim}" format where:
- {width} and {height} are numerical values (please use a colon '.' as the decimal separator).
- {dim} is the dimension which can be 'mm', 'in.' or 'inches'. (It defaults to inches when nothing is specified)
- {sep} separates the width and the height, either 'by', comma (,) or the letter 'x' Example: "8.5 in. by 6 in."
- Properties: Optional properties to pass to the XSL template for display or processing purposes. For details see below.
- Template: The XSL template (details below) to use for formatting purposes. This can either be a string containing all the XSL, a path - local to the server running the conversion service - to the location of the XSL file, or a URL to the XSL file on a web (or SharePoint) server.
- NameValuePair: A single value that can be passed into the XSL using TOCSettings.Properties.
- TOCLocation: Used by TOCSettings.Location to determine where the TOC should go.
- BookmarkGenerationOption: As explained under the XML Source Data section below, the TOC system is based on the content and structure of PDF Bookmarks. It is therefore essential that during the conversion of the source documents ConversionSettings.GenerateBookmarks is set to Automatic.
Based on the previously described list of classes and properties, adding a TOC may sound complex, but nothing could be further from the truth. The easiest way to get started is to take our sample code, add the following code and then pass tocSettings into either ConversionSettings.TOCSettings or MergeSettings.TOCSettings.
You can certainly use your own code, and even pass the tocSettings to both ConversionSettings.TOCSettings AND MergeSettings.TOCSettings to generate TOCs for each individual document in a merge operation, and then add an overall TOC for the entire merged document.
XML Source Data
To determine what entries to include in the TOC, the conversion service looks at the PDF Bookmarks present in the PDF. If the source file is not already in PDF format, it will be converted to PDF and where possible, it will generate PDF bookmarks based on the internal structure of the document. For example, when converting a MS Word file, the various headings determine the structure of the PDF Bookmarks.
Although in most cases it is not important for our customers to have any knowledge about the internals of the Muhimbi Conversion Service, in this particular case and by design it is advisable for our customers to understand this. Internally, an XML document is generated that represents the content and structure of the PDF Bookmarks, and this XML document is then transformed using XSL into HTML. It is this HTML, which is the language that underpins every website on the internet, that determines the formatting of the TOC. Developers have full control over the XSL, providing an enormous amount of flexibility.
Let’s take our comprehensive Administration Guide as an example. When converted to PDF a set of nested PDF bookmarks is generated, which internally generates the following XML:
Generated XML
The generated XML is fairly straight forward, and a number of nested topic elements make up the structure. Each element has a descriptive title attribute, a level attribute (which matches the nesting level), a page attribute containing the page number, and a target attribute which is used for internal processing purposes.
Note: All page numbers in the TOC reflect the physical page number of that page in the generated PDF, including the addition of the TOC page itself. If the source document(s) already contain page numbers, then these may no longer be the same as the page number listed in the TOC or their actual page number in the generated PDF. If you wish to change the page numbers displayed in the footer of a document then please use our watermarking facilities.
The list of topic elements is followed by a properties section (Line 84 onwards in our example above). This section, and its contents, consists of a number of optional values that may have been passed into the request. This allows, for example, the addition of information to the TOC to display the document's status, author, title or any other kind of information. In this example we are passing the title of the document.
XSL Transformation
Although the XML document’s content may differ between requests, the structure is always the same. As a result we can use the XSL industry standard to convert the XML into an attractive looking HTML document. Although XSL may look daunting to the uninitiated, the following sample (download) is a good starting point and can be amended to suit your particular needs (or used as is).
Although this is a standard XSL file, the following sections are of particular interest:
- Lines 12-56: Standard HTML CSS style sheet which controls the look of the generated HTML.
- Line 60: Insert a custom property passed into the conversion request. In our example the document’s title.
- Line 76: An empty template for the properties element to prevent this information from being displayed as a plain list.
- Lines 78-97: XSL template for generating HTML associated with all Level 0 topics. If you wish to control the generated HTML for a specific level then copy the topic[@level=’0’] template and change the level number to match to appropriate nesting level.
- Lines 99-118: XSL Template for all topic levels that do not have an explicit template defined.
If you find it difficult to create, you can just use the XSL sample provided above and use it in your project. An example of generated file is given below.
Testing & Troubleshooting
Although not the most attractive looking application, the PDF Converter comes with a handy Diagnostics Tool (including full source code) to test the Table Of Contents facility. While this might be merely a handy test tool, not the official user interface for the TOC facility, it can be incredibly helpful in quickly testing various XSL template designs before integrating them into your solution.
To test the XSL and TOC output, enable the Table of Content as per the screenshot above, modify the XSL template if needed, specify any optional properties, select a file or folder in the WS Convert tab and choose either the Convert or Merge button.
