Reporter Templates

This reference describes the templates used by these reporters:

• Section (see Section Templates)

• Chapter (see Chapter Templates)

Use this information to create custom templates for use with one of these reporters or from a reporter derived from these reporters.

Section Templates

The Section reporter uses six sets of templates for each of the three output types supported by MATLAB^® Report Generator™: docx, pdf, and html. Each set corresponds to the six levels of section hierarchy that the Section reporter can generate. The first set corresponds to a top-level section, the second set to a second-level subsection of a top-level section, and so on.

Each level set contains three templates:

• A section body template named SectionN, where N is the level of a section (see Section1 Template and Section2 – Section6 Templates).

• A numbered section title template named SectionNumberedTitleN (see Numbered Section Title Templates).

• An unnumbered section title template names SectionTitleN (see Unnumbered Section Title Templates).

A Section reporter determines which set to use when your report program adds the reporter to a report object. For example, when your report program adds a Section reporter to a Report object, the Section reporter uses the top-level template set. A Section reporter uses the second-level template set when the report's add method adds it to the report as part of the content of a top-level section reporter. A Section reporter uses the third-level template set when the report add method adds it to the report as part of the content of a second-level reporter, etc.

Section1 Template

The Section reporter's Word, PDF, and HTML Section1 templates specify the format of a top-level section generated by the Section 1 reporter in a Word, PDF, and HTML report, respectively. All three templates specify the location of the holes and the default styles for the Section reporter's Title and Content properties.

In addition, the PDF and Word templates specify the page layout properties of a top-level section, including page orientation, margins, page headers, and page footers of a top-level Word or PDF section. The Word and PDF templates specify a different header for the first page of a section and for the pages that follows. The header of the first page contains only a rule. The header of subsequent pages, called default header, contains the section title. The first page footer and subsequent page footers are identical.

A top-level section starts on a new page having the properties specified by the top level Section reporter's template. All subsequent pages needed to accommodate the top-level section content have the same page layout, unless the content itself specifies a new page layout, in which case, the page layout of subsequent pages changes. Default lower-level section templates do not specify a page layout. As a result, adding subsections to a section does not change the page layout. The content of subsections has the same layout as the top-level sections.

• Word Section1 Template

  The Word Section1 template resides in the QuickParts gallery of the Section reporter's default.dotx template file. The QuickParts gallery serves as the Section reporter's Word template library. To view or edit the Section1 template, you must open the default.dotx file in Word and create an instance of the template in the default.dotx template. The Section1 template appears as follows in Word:

  

  Note

  When you display a copy of the Word Section1 template, it scrolls to the default page header on the second page, which displays an error message. Refer to the note below for an explanation of this error message. To see the template holes, scroll to the top of the template.

  The Section1 template specifies a header for the first page of a section that differs from the header of succeeding pages. The header of all but the first page is called the default header. The first page header contains a rule but is otherwise empty.

  

  Note

  The rule is implemented as an empty paragraph with a bottom border. The font size of the paragraph is set to a very low value to minimize the paragraph's height.

  The first page footer contains a Word page number field. When this template or a report generated from it is opened in Word, Word replaces the field with the number of the page on which the footer appears.

  

  The Section1's default page header contains a Word SectionRef field that references the section's title style (that is, SectionTitle). When the template or a report generated from the template is opened in Word, Word replaces the SectionRef field with the content of the first paragraph in the section that has the SectionTitle style. In a report, that paragraph contains the section's title. Thus, the section's title appears in page headers that follow the first page. (This is called a running head in document design.)

  Note

  The Section1 template occupies less than a page. Thus, when you copy the Section1 template from the Section reporter's QuickPart's gallery (that is, template library) to the body of the default.dotx template, only the first page of the section appears. However, Word creates a page with a new section (Section 2) that inherits the Section1 template's page headers. Word replaces the SectionRef field in the header of this new section with an error message because there is no paragraph in the new section with the referenced style.

  

  The Section1 template specifies a default page footer that is identical in content and format to the first page footer.

  Note

  To view or edit the default page footer, you must insert a page in the Section1 template as follows:

  1. Copy the template from the Section reporter template's QuickParts gallery (that is, its template library) to the body of the reporter template.

  2. Insert a paragraph after the Content hole in the template.

  3. Enable the paragraph's Page Break Before property.

  

• PDF Section1 Template

  The PDF Section1 template resides in the template library of the Section reporter's PDF template file (default.pdftx). The template file is a zip file. It stores the template library in a file named docpart_templates.html. To view or edit the Section1 template:

  1. Unzip a copy of the default.pdftx file using the Report API unzipTemplate command.

  2. Open the docpart_templates.html file in the MATLAB editor or any other text editor.

  3. When you are finished editing the Section1 template, save the docpart_templates.html file.

  4. Rezip the default.pdftx file, using the Report API zipTemplate command.

  For more information, see Create PDF Document Part Template Library.

  The PDF Section1 template uses the following HTML markup to define the page layout of a top-level PDF section generated by the Section reporter. The markup also defines the location of the holes to be filled with the content of the Section reporter's Title and Content properties.

  

  The pheader and pfooter elements in the Section1 layout specify templates used to define the content and layout of a top-level section's page headers and footers. The header and footer templates reside in the same template library file (docpart_templates.html) as the Section1 template itself. The Section reporter uses only the first page and default page templates.

  The first page header and footer templates are

  

  The header template specifies an empty paragraph followed by a horizontal rule. The empty paragraph specifies the style SectionTitleHead. It is defined in the template's style sheet (see below). The first page footer template specifies a horizontal rule followed by a page number.

  The default page header template

  

  specifies a paragraph containing a styleref followed by a horizontal rule. During report generation, the Report API replaces the styleref element with the content of the top-level section's title paragraph, thereby creating a running head.

  The default page footer template

  

  specifies a horizontal rule followed by an automatically generated page number.

  The styles for the header and footer templates are in the pdf/stylesheets/root.css file.

  

• HTML Section1 Template

  The Section1 document part template in the default.htmt file specifies the Title and Content holes.

  

Section2 – Section6 Templates

The Section2-Section6 templates specify the format of subsections generated by the Section reporter. Each template contains hole elements that specify the location of holes to be filled with the content of the Section reporter's Title and Content properties, respectively. The Title hole in each template specifies a default title style specific to the subsection level defined by the template.

• Word Section2 – Section6 Templates

  As an example, this image shows the Section2 template.

  

• PDF and HTML Section2 – Section6 Templates

  As an example, this image shows the Section2 template.

  

Section Template Holes

All of the Section templates (Section1 – Section6) have the holes described in this table.

Hold ID	Hole Type	Description
Title	Block	The Section reporter fills this hole with content based on the type of the content of its Title property as follows. If the Title property content is an inline object, such as a string or mlreportgen.domText object, the Section reporter uses a SectionTitle reporter to format and generate the inline content as a title. It then adds the generated content to the Title hole. The SectionTitle reporter use templates to format the inline content. If its Title property content is a paragraph or other block-level object, the Section reporter adds the paragraph to the Title hole. If its Title property content is another reporter, the Section reporter adds the content generated by the reporter to the Title hole.
Content	Block	Content of the section

Section Template Styles

The Section templates use styles to format some content. The Word templates define the styles they use in the style sheet in the default.dotx template file. The PDF and HTML templates define the styles in the stylesheets/root.css file in the default.pdftx and default.htmt files, respectively. The following table describes the styles used by the Section templates.

Style Name	Style Type	Description
SectionContent	Character	The Content hole in the Section1-Section6 templates specify this style as the default text style for content that fills the hole. The content can specify styles or formats that override the default style.
SectionTitle1 - SectionTitle6	Character	The Title hole in the corresponding section template specifies the corresponding style name as the default style for the section's title. For example, the Title hole in the Section1 template specifies SectionTitle1 as the name of the default style for the title of a top-level section. Content added to the Title hole can specify formats or styles that override the default style.
SectionTitleHeader	Character	The Section1 page headers use this style to center the header content.
SectionTitleFooter	Character	The Section1 page footers use this style for the footer content.

Section Title Templates

If the content of the Section reporter's Title property is a string, Text, or other inline object, it uses a SectionTitle reporter to generate the content used to fill the Title hole in its section level templates. The SectionTitle reporter in turn uses templates to format the inline content as a title. The SectionTitle reporter use two sets of templates for each output type, one to create hierarchically numbered titles (1.1, 1.2, 1.2.1, and so on), the other to create unnumbered titles. Each set contains six templates corresponding to the six levels of sections that the Section reporter can generate. The templates reside in the template libraries of the Section reporter's Word, PDF, and HTML template files, default.dotx, default.pdftx, and default.htmt, respectively.

Numbered Section Title Templates

If a report or Section reporter specifies that its titles be numbered, the SectionTitle reporter uses automatically numbered templates to format the inline content of the Section reporter's Title property. The titles are named SectionNumberedTitleN, where N is the section level to which the template applies. For example, the name of the template for a top-level section title is SectionNumberedTitle1. Each template contains a paragraph element that specifies the same style as is specified by the Title hole in the corresponding section level template, for example, SectionTitle1 for a top-level section title. See Section Template Styles.

The title paragraph contains the following holes.

• NumberPrefix hole to be filled with the content of SectionTitle reporter's NumberPrefix property (empty by default)

• Autonumber markup that is replaced by a hierarchical number during report generation. The autonumber markup differs for each level template so as to generate the hierarchical number appropriate to that level.

• NumberSuffix hole to be filled with the content of the SectionTitle reporter's NumberSuffix property (empty by default).

• Content hole to be filled with the content of the SectionTitle reporter's Content property.

The following images show the Word, PDF, and HTML SectionNumberedTitle1 templates, respectively. Lower-level templates are similar.

• Word SectionNumberedTitle1 Template

  

• PDF SectionNumberedTitle1 Template

  

• HTML SectionNumberedTitle1 Template

  

During report generation, the Section reporter sets the Content property of the SectionTitle reporter to the inline content of the Section reporter's Title property. It does not set the NumberPrefix and NumberSuffix properties. As a result, the title generated by the SectionTitle reporter consists by default of a hierarchical number followed by the title text.

The SectionTitle reporter provides the NumberPrefix and NumberSuffix holes to facilitate labeling of titles by derived reporters. For example, the Chapter reporter, which is derived from the Section reporter, sets the NumberPrefix property to Chapter in English locales. In some East Asian locales, the Chapter reporter sets the NumberSuffix to the character designating chapter.

Note

If you customize a numbered section template, do not remove or replace the SEQ fields in a Word template or the autonumber markup in a PDF or HTML template. To generate unnumbered sections, use the Unnumbered Section Title Templates.

SectionNumberedTitle Template Holes

All of the SectionNumberedTitle templates (Section1 – Section6) have the holes described in this table.

Hole ID	Hole Type	Description
NumberPrefix	Inline	Prefix to display before the section number.
NumberSuffix	Inline	Suffix to display after the section number.
Content	Inline	Content of the title

Unnumbered Section Title Templates

If the report specifies that the current section uses unnumbered titles, the SectionTitle reporter uses unnumbered templates to generate section titles. The unnumbered templates are named SectionTitleN where N is the level of the section whose title is to be generated. For example, the template for a top-level section is named SectionTitle1. Each template contains a paragraph element that specifies the same style as is specified by the Title hole in the corresponding section level template, for example, SectionTitle1, for a top-level section title. See Section Template Styles. The title paragraph contains a hole to be filled by the content of the SectionReporter's Content property (set by the Section reporter during report generation).

The follow images show the Word, PDF, and HTML versions of the SectionTitle1 templates. Lower-level templates are similar.

• Word SectionTitle Template

  All levels of the Word SectionTitle templates have the same content hole.

  

• PDF and HTML SectionTitle1 Template

  

• PDF and HTML SectionTitle2 – SectionTitle6 Templates

  These section title templates include a Content hole, as in SectionTitle1 template. Each of these sections specifies its title style.

  

SectionTitle Template Hole

All of the SectionTitle templates (Section1 – Section6) contain the hole described in this table.

Hole ID	Hole Type	Description
Content	Inline	Content of the title

Chapter Templates

The Chapter reporter, a subclass of the Section reporter, uses the Section reporter's top-level template set to generate its content. This is because a Chapter-generated section is nearly identical to a Section-generated section. However, the two types of sections differ in two respects:

• The title of a chapter section contains the word Chapter in English locales or the equivalent in other locales supported by the Report API. The Chapter reporter includes the word Chapter in titles by setting the NumberPrefix or NumberSuffix properties of the SectionTitle reporter used to generate the chapter title.

• All Section-generated top-level sections start on page 1. By contrast, only the first chapter generated by a Chapter reporter starts on page 1. Succeeding chapters continue page numbering from the previous chapter. The Chapter reporter implements this behavior programmatically, thus avoiding the need to use a modified version of the Section top-level template.

See Section1 Template, Numbered Section Title Templates, and Unnumbered Section Title Templates