Customize Chapters

You can customize the content and format of chapters generated by the Report API Chapter reporter, mlreportgen.report.Chapter. You can perform some customizations by setting properties. For example, you can use the Chapter reporter Layout property to change the chapter layout from portrait to landscape. For more information on chapter customizations that are available by setting properties, see mlreportgen.report.Chapter.

For other customizations, you must modify the Chapter reporter template, class definition file, or both the template and class definition file. To customize only static content, such as a logo in a page header, modify the Chapter reporter default template and use the modified template with the reporter. To customize dynamic content or both dynamic and static content, create a custom Chapter reporter and modify its template and class definition file.

For an example that customizes chapter page headers with fixed and dynamic content, see Customize Chapter Page Headers.

Customize Static Content

If your chapter customization includes only static content, create a copy of a chapter template, edit the copy, and use the new template when you generate a report.

Create the Template

Create a copy of the chapter template for the type of report that you plan to generate. For example, to copy the template for a PDF chapter to the file mychapter.pdftx in the folder mytemplates, enter:

mlreportgen.report.Chapter.createTemplate('mytemplates/mychapter','pdf');

Edit the Template

The way that you edit a chapter template depends on the type of report that you are generating:

Use the Template

In your report generation program:

Define a chapter reporter.
Set the TemplateSrc property of the reporter to the path of the custom template.

For example:

chapter = mlreportgen.report.Chapter;
chapter.TemplateSrc = 'mytemplates/mychapter.mychapter.pdftx';

Customize Dynamic Content

If your chapter customization includes dynamic content, you must create a skeleton custom reporter class so that you can define properties for the dynamic content. When you create the skeleton custom chapter reporter, the chapter templates for all report types (PDF, Word, and HTML) are copied to a resources/templates folder. Edit the chapter template to contain the content that you want to generate. Add holes for the dynamic content. When you generate a report, use the custom chapter reporter and assign values to the properties that correspond to the holes.

Create a Skeleton Custom Reporter Class

Use the mlreportgen.report.Chapter.customizeReporter method to:

Create a skeleton reporter class.
Copy the default templates for each type of report to a resources/templates folder.

For example, this code creates a class named Chapter and copies the templates to the resources/templates folder in the folder +myCompany/@Chapter:

mlreportgen.report.Chapter.customizeReporter('+myCompany/@Chapter')

Edit the Template

The way that you edit a chapter template depends on the type of report that you are generating:

Define the Properties for the Dynamic Content

In the custom reporter class, define a property for each hole that you added to the template. For example:

classdef myChapter < mlreportgen.report.Chapter 

    properties 
        Project = ''
        Date = ''
    end 
    ...
end

A property name must match a hole ID in the PDF template or a hole Title in the Word template.

Use the Custom Reporter Class

In your report generation program:

Create a chapter reporter from the custom chapter reporter class.
Assign values to the reporter properties that correspond to the holes in the template.

For example:

chapter = myCompany.Chapter();
chapter.Project = 'ABC Project';
chapter.Date = date;

Edit a PDF Template

The PDF chapter template file is a zip file. To modify the template, unzip the template file, edit docpart_templates.html in a text editor, and package the extracted files back into the zip file. See Chapter Templates.

Locate the Template File

If your template file was created by using mlreportgen.report.Chapter.createTemplate, the packaged template file is in the location that you specified. For example, this code creates the template file mychapter.pdftx in the mytemplates folder:

mlreportgen.report.Chapter.createTemplate('mytemplates/mychapter','pdf');

If your template file was created by using mlreportgen.report.Chapter.customizeReporter, the template file has the name default.pdftx and is in the resources/templates/pdf subfolder of the folder that contains the chapter reporter class definition file.

Unzip the Template File

Unzip the package file by using the unzipTemplate function. For example, this code extracts files from the template file mytemplates/mychapter.pdftx into the folder mychapter:

unzipTemplate('mytemplates/mychapter.pdftx','mychapter');

The extracted files include:

docpart_templates.html
root.html
Folders for images and stylesheets

Edit the Markup

Open docpart_templates.html in a text editor and edit the markup.

To define a hole for dynamic content, use the hole element. When you add a property for the hole in the custom chapter reporter, the property name must match the hole id value.

Modify a header or footer by editing the header or footer template in the dptemplate element with the name Section1. The templates for headers and footers are SectionFirstPageHeader, SectionFirstPageFooter, SectionDefaultPageHeader, SectionDefaultPageFooter, SectionEvenPageHeader, and SectionEvenPageFooter.

To specify the same header or footer for all chapter pages, provide only the SectionDefaultPageHeader or SectionDefaultPageFooter in the list of header and footer templates. Remove the other headers and footers from the list.

Note

Use the existing dptemplate elements. Do not create your own dptemplate elements or change the values of the Name attribute of the dptemplate elements.

Package the Template Files

Package the files back into the template file by using the zipTemplate function. For example, if mytemplates/mychapter contains the unzipped files, this code packages the files into mychapter.pdftx in the mytemplates folder.

zipTemplate('mytemplates/mychapter.pdftx','mytemplates/mychapter');

Edit a Word Template

To edit a Word template:

Open the template file in Word.
Create a temporary copy of the Section1 template in the template document,. The Section1 template, which is used for both chapters and top-level sections, is in the Quick Parts gallery of the template document.
Edit the temporary copy and save the copy to the Quick Parts gallery.
Delete the temporary copy from the template document and save the template file.

Locate the Template File

If your template file was created by using mlreportgen.report.Chapter.createTemplate, the template file is in the location that you specified. For example, this code creates the template file mychapter.dotx in the mytemplates folder:

mlreportgen.report.Chapter.createTemplate('mytemplates/mychapter','docx');

If your template file was created by using mlreportgen.report.Chapter.customizeReporter, the template file has the name default.dotx and is in the resources/templates/docx subfolder of the folder that contains the chapter reporter class definition file.

Open the Template File in Word

Open the template file by using one of these methods:

In MATLAB^®, in the Current Folder pane, right-click the template file and click Open Outside MATLAB.
Outside of MATLAB, right-click the template file and click Open.

Note

Do not double-click a Word template file to open it. Double-clicking the file opens a Word document file that uses the template.

The template document opens to an empty page.

Show the Formatting Symbols

To make the paragraph and formatting symbols visible, on the Home tab, click the Show/Hide button.

Copy the Section1 Template into the Template Document

Position the cursor in front of the paragraph in the template document.
On the Insert tab, in the Text group, click Quick Parts, then click the Section1 building block.
Word inserts a copy of the Section1 template and a dummy Section2 section. The dummy section is ignored when you generate a report. The cursor is positioned in the body of the dummy section.
Scroll up to the Section1 first page template.
Edit the template to contain the content that you want to generate. To add holes to a Word template, see Add Holes in Microsoft Word Templates.
To modify headers and footers, see Tips for Editing Headers and Footers in a Word Template.

Note

Use the existing templates in the Quick Parts gallery. Do not create your own templates or change the names of the existing templates.

Save the Template in the Quick Parts Gallery

If the header or footer is open, close it by double-clicking the page outside of the header.
Select all of the content in the template by pressing Ctrl+A.
On the Insert tab, click Quick Parts, and then click Save Selection to Quick Parts Gallery.
In the Create New Building Block dialog box, in the Name field, enter Section1. Set Gallery to Quick Parts, Category to mlreportgen, and Save in to the name of the template file.

Save the Template File

It is a best practice to delete the content from the body of the template document before you save the template file.

Tips for Editing Headers and Footers in a Word Template

Here are some tips for editing headers and footers in a Word Template.

To control whether headers and footers on the first page differ from headers and footers on the following pages, double-click a header. Then, under Header and Footer Tools, on the Design tab, select or clear the Different First Page check box.

To control whether even page headers and footers differ from odd page headers and footers, select or clear the Different Odd and even Pages check box.
To see the headers and footers for pages that follow page one, add empty paragraphs to page one until a second Section1 page is created. Double-click the header on the new page.
The default first page header includes a horizontal rule, which is the bottom edge of a small paragraph. To make the rule invisible, select the small paragraph. Then, on the Home tab, in the Paragraph group, Borders > No Border.