PDF and HTML Document Parts and Holes

This example shows how to:

Define a document part template that has holes.
Insert a document part into the report programmatically and fill holes.
Insert a TOC document part.

This example uses a PDF template and report. However, you can use this same process for HTML reports. Replace the document type information with the corresponding HTML information throughout the example.

Add Templates to PDF Document Part Libraries

In this example, start with the default PDF template package.

Create a copy of the default template package.

mlreportgen.dom.Document.createTemplate('myPDFtemplate','pdf');

Unzip the template package.
```
unzipTemplate('myPDFtemplate.pdftx');
```

In the current folder, open the unzipped template folder myPDFtemplate. Open docpart_templates.html in an HTML or text editor.

The dplibrary element defines a document part library. The dptemplate element defines each document part template. This document part library has two document part templates:

rgChapter, which defines a part template for chapters
ReportTOC, which defines the table of contents

<html>
<body>
   <dplibrary>

	  <dptemplate name="rgChapter">
      <h1 class="rgChapterTitle">
      <hole id="rgChapterTitlePrefix" default-style-name="rgChapterTitlePrefix" />
        <span> </span>
      <hole id="rgChapterTitleNumber" default-style-name="rgChapterTitleNumber" />
        <span>. </span>
      <hole id="rgChapterTitleText" default-style-name="rgChapterTitleText" />
      </h1>
      <hole id="rgChapterContent"/>
     </dptemplate>
    
   <dptemplate name="ReportTOC">
       <TOC number-of-levels ="3" leader-pattern="dots" />
   </dptemplate>

   </dplibrary>

</body>
</html>

Create a document part template named Author. A document part can contain any combination of fixed text and holes. This document part template contains the fixed text Author and a hole for the author name.
```
<dptemplate name="Author">
      <p class="Author">
      <span>Author: </span><hole id="AuthorName" />  
      </p>
            
 </dptemplate>
```

Add the new document part template to the library. Because you refer to the document part by name when you call it from the API, you can put the templates in any order within the library. Use a unique name for each document part template.

 <dplibrary>
        
	  <dptemplate name="rgChapter">
      <h1 class="rgChapterTitle">
      <hole id="rgChapterTitlePrefix" default-style-name="rgChapterTitlePrefix" />
        <span> </span>  
      <hole id="rgChapterTitleNumber" default-style-name="rgChapterTitleNumber" />
        <span>. </span>
      <hole id="rgChapterTitleText" default-style-name="rgChapterTitleText" />
      </h1>
      <hole id="rgChapterContent"/>
   </dptemplate>
   <dptemplate name="ReportTOC">
      <TOC number-of-levels ="3" leader-pattern="dots" />
  </dptemplate>
  <dptemplate name="Author">
      <p class="Author">
      <span>Author: </span><hole id="AuthorName" />  
      </p>
  </dptemplate>

</dplibrary>

Repackage the template to a new template called myPDFtemplate2.pdftx.
```
zipTemplate('myPDFtemplate2.pdftx','myPDFtemplate');
```

Use Document Part Templates in Report Programs

Use mlreportgen.dom.DocumentPart to use the document part template. You need:

The name of the template package that contains the document part. In this example, the template package name is myPDFtemplate2.
The names of the document part templates to call and the order of any holes you want to fill. In this example, you call:
- The document part template rgChapter and fill the first three holes in the order of prefix, number, and title
- The ReportTOC document part template, which inserts a table of contents
- The Author document part template you created and fill its one hole

import mlreportgen.dom.*
d = Document('myDocPartEx','pdf','myPDFtemplate2');
open(d);

% Assign the rgChapter document part template to the variable dp
dp = DocumentPart(d,'rgChapter');

% Move to each hole in this document part and append content 
moveToNextHole(dp);
append(dp,'Chapter');
moveToNextHole(dp);
append(dp,'5');
moveToNextHole(dp);
append(dp,'Creating Document Part Templates');

% Append this document part to the document
append(d,dp);

% Append the document part ReportTOC to the document
append(d,DocumentPart(d,'ReportTOC'));

% You can append any allowable object between document parts or holes
append(d,Paragraph('Append any allowable object or a document part.'));
append(d,Paragraph('Append a document part next:'));

% Assign the Author document part template to the variable dp2
dp2 = DocumentPart(d,'Author');

% Move to the next hole and fill it
% Append the document part to the document
moveToNextHole(dp2);
append(dp2,'Charles Brown');
append(d,dp2);

close(d);
rptview(d.OutputPath);

The Author document part template includes fixed text that precedes the hole. moveToNextHole appends any fixed content in the template between the previous hole (or the beginning of the document part) and the current hole to the document.