Template-Based Output Types

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.

Templates Versus XSL and DSSSL Style Sheets

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:

Component Styles

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 rgParagraph style.

Component Templates

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 template.

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.

Component Holes

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.

Template Cache

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

>> rptgen.db2dom.TemplateCache.getTheCache(true);

at the MATLAB command line.