The Report Explorer allows you to use templates to format your reports. A template is an HTML or Word document that specifies the fixed content, format, and layout of your report. You can use Microsoft® Word templates to format Word and PDF reports and HTML templates to format HTML and PDF reports. The MATLAB® Report Generator™ comes with a default set of Word templates for PDF and Word reports and HTML templates for PDF and HTML reports. You can create your own templates by copying and customizing these default templates.
The Report Explorer provides a set of template-based report output types. These output types appear in the File format drop-down list in your report generator’s root Form or Reporter component. Selecting a template-based output type populates the adjacent drop-down list with the templates available for that output type, including the Report Explorer’s built-in templates and any templates that existed on the MATLAB path or in the current directory a the start of your MATLAB session. By default the Report Explorer uses a default template to format a report for the specified output type. You can specify another template by selecting from the adjacent list.
Template-Based Output Types
|Name on Form Component||Name on Report Component||Generates|
|Formatting Objects (FO) representation of a report’s content and format based on an HTML template with PDF-specific extensions. The Report Explorer uses the Apache Formatting Objects processor (FOP) to convert the FO representation to PDF.|
|Microsoft Word report from a Microsoft Word template and then uses Microsoft Word to convert the Word report to PDF. This output type is available only on Windows. Report size is limited by Word’s pagination capacity, typically about 500 pages.|
|Microsoft Word report from a Word report.|
Besides templates, the Report Explorer supports use of XSL or DSSSL style sheets to format reports. An XSL style sheet is a program, written in a dialect of XML called XSL, that converts and formats your report’s intermediate XML content to HTML or PDF output. A DSSSL style sheet is a program, written in a dialect of Lisp, that converts your report’s intermediate XML content to Microsoft Word output. The Report Explorer supports style-sheet-based formatting to provide backward compatibility with report generators developed with the Report Explorer in releases that preceded availability of templates. You should use templates exclusively for new report generators that you develop with the Report Explorer. This is because templates have significant advantages over style sheets:
Formatting: XSL and DSSL style sheets have limited formatting options. For example, all titles and all body paragraphs in your report must have the same format. By contrast, templates allow you to use all formatting options available in Microsoft Word and HTML documents.
Scalability: The Report Explorer uses a MATLAB-based file converter, called
db2dom, to convert reports based on templates. The Report Explorer uses
Java-based file converters,
JADE, to convert
reports based on XSL and DSSSL style sheets. The
db2dom converter is
typically an order of magnitude faster than
JADE and uses no Java memory for Word and HTML output and much less
memory for PDF output. As a result, the Report Explorer can generate much larger reports with
templates than with style sheet-based output.
Every report template contains a style sheet. This style sheet, not to be confused with an
XSL or DSSSL style sheet, is a document that defines named sets of text, paragraph, list, and
table formats called styles. During report generation, the Report Explorer’s file converter,
db2dom, copies the template style sheet into the generated report and
assigns the style names to paragraphs, text, lists, and tables generated by your report
generator’s components. The program that you use to display or print your report, such as an
HTML browser or Microsoft Word, uses the styles to
format your report.
The Report Explorer’s default templates defines all the styles needed to format a report
generated by the Report Explorer from your report setup file. To distinguish them from other
styles, the names of these styles begin with the prefix,
rg, for example,
rgParagraph. You can modify the appearance of a report by customizing the
definitions (but not the names) of these styles in a copy of a default template and using the
copy to generate the report.
You can also define your own styles in a customized template and assign them to components
whose dialogs contains a StyleName property. Components that have a
StyleName property include the Text and
Paragraph components. In this way, you can customize the appearance of
individual instances of a component. For example, the default style of a
Paragraph component is
rgParagraph. By creating and
assigning your own style, for example,
myParagraph, to a particular
Paragraph component, you can differentiate the appearance of this
component’s output from that of paragraphs that have the default
The Report Explorer’s default templates contain a component template library. A component
template library is a document that defines templates for Report Explorer components, such as
the Title Page component and the Chapter/Section
component. Each template in the library has a name, for example,
rgRectoTitlePage, which enables the Report Generator to locate the component
template in the library. The component library allows a single template, called the main
template, to contain all the templates needed to format a report generated from the main
You can change the format of a report component, such as a title page, by customizing its template in a copy of a default template and using that customized template to generate the report. You can also create and store templates for Subform components in a Form component’s main template. In this way, you can create custom report components with custom content and custom formats. For example, you can create a custom title page template and use it with a Subform component to generate a title page that contains content not defined by the Title Page component, such as a sign-off block.
The Report Explorer’s default component templates contain placeholders, called holes, that designate where to insert generated content relative to the template’s fixed content and other generated content. For example, the Title Page component’s templates contain holes for a report’s title, subtitle, author, abstract, etc. The Report Explorer replaces these holes with generated content during report generation. For example, it replaces the title hole in the Title Page template with the title specified by the Title Page component’s Title property.
You can alter the layout and content of a component that specifies content by rearranging or deleting its holes. For example, you can delete or adjust the location of a title page’s subtitle by moving or deleting the subtitle hole in the Title Page component’s template. You can also include holes in the templates that you create for Form and Subform components and fill those holes using Template Hole components in your report generator setup file. In this way, for example, you can generated a title page that exactly fits your title page layout and format requirements.
The first time you open the Report Explorer in a MATLAB session it searches the MATLAB path for templates. It stores all the templates that it finds in a cache. It also adds any templates that you create in the session to the cache. Subsequently it searches the cache for any template that you specify that is not in the current directory. This avoids the need to search the MATLAB path every time the Report Explorer needs to generate a report based on a template. If you try to use a template that is not on the MATLAB path at the beginning of the MATLAB session, the Report Explorer indicates that it cannot find the template. In this case, you can either change MATLAB working directory to the directory to the template directory or you can add the directory to the MATLAB path and refresh the cache. To refresh the cache, execute
at the MATLAB command line.