Define New Reporters

MATLAB^® Report Generator™ allows you to define a custom reporter based on the mlreportgen.report.Reporter class or a built-in Report API reporter. Base your reporter on a built-in reporter when the built-in reporter meets most of your requirements and you want to rearrange or expand the reporter content. See Subclass Reporter Definitions. Base your reporter on the mlreportgen.report.Reporter class to define an entirely new reporter.

To create a reporter based on mlreportgen.report.Reporter, use the mlreportgen.report.Reporter.customizeReporter method. The method creates a skeleton class definition file and makes copies of the default template files for each report output type.

To complete the custom reporter definition:

• In the template file for each report output type supported by the reporter, define the fixed content and holes for the dynamic content that the reporter generates.

• In the custom reporter class, define properties that correspond to the template holes.

To use the reporter in a Report API report, create an object of the reporter class, set the property values, and append the object to the report.

Create Class Definition File and Template Copies

Create a class definition file for a custom reporter class and make copies of the default templates by calling the mlreportgen.report.Reporter.customizeReporter method. Provide the path and name of the class to be created as the input argument to the method. To create the reporter class in a class folder, precede the class name with the @ character.

For example, this code creates a class file MyTitlePage.m in the folder named @MyTitlePage:

mlreportgen.report.Reporter.customizeReporter("@MyTitlePage")

The class definition file MyTitlePage.m contains:

classdef MyTitlePage < mlreportgen.report.Reporter 

    properties 
    end 

    methods 
        function obj = MyTitlePage(varargin) 
            obj = [e-mail](varargin{:}); 
        end 
    end 

    methods (Hidden) 
        function templatePath = getDefaultTemplatePath(~, rpt) 
            path = MyTitlePage.getClassFolder(); 
            templatePath = ... 
                mlreportgen.report.ReportForm.getFormTemplatePath(... 
                path, rpt.Type); 
        end 

    end 

    methods (Static) 
        function path = getClassFolder() 
            [path] = fileparts(mfilename('fullpath')); 
        end 

        function createTemplate(templatePath, type) 
            path = MyTitlePage.getClassFolder(); 
            mlreportgen.report.ReportForm.createFormTemplate(... 
                templatePath, type, path); 
        end 

        function customizeReporter(toClasspath) 
            mlreportgen.report.ReportForm.customizeClass(... 
                toClasspath, "MyTitlePage"); 
        end 

    end  

The class includes a constructor and the hidden method getDefaultTemplatePath. The base reporter class uses the getDefaultTemplatePath method to retrieve the MyTitlePage reporter template that corresponds to the output type of the report to which the reporter is added. For example, if you add the reporter to an mlreportgen.report.Report object whose output type is PDF, the base reporter class returns the path of the PDF template that resides in the resources/templates/pdf subfolder of your reporter definition folder.

The mlreportgen.report.Reporter.customizeReporter method stores copies of the default template files for each report output type in the resources/templates subfolder of the folder that contains the class definition file. The paths of the template files relative to resources/templates are:

• docx/default.dotx

• pdf/default.pdftx

• html/default.htmt

• html/default.htmtx

For example, the @MyTitlePage folder has this structure:

Define Fixed and Dynamic Content in Templates

Customize the template files by defining the fixed content and holes for the dynamic content that the custom reporter generates. You only need to customize the template files for the report output types supported by the custom reporter. For example, if the reporter supports only Word reports, customize only the dotx template file.

If the custom reporter requires multiple templates, store the templates in a template library in the template file. If the reporter requires only one template, you can store the template content in the body of the template file or in a template in the template library. For example, for the MyTitlePage reporter, which requires only one template, you can add the template fixed content and holes for dynamic content to the body of the template file or to an entry named MyTitlePage in the template file library.

Define the styles used by the template in the style sheet of the template file.

See Create Microsoft Word Document Part Template Library, Create PDF Document Part Template Library, and Create HTML Document Part Template Library.

Define Properties and Specify Templates in Custom Reporter Classes

In the custom reporter class:

• Define a property for each of the holes defined by the templates, including holes in the headers and footers. The property corresponding to a hole must have the same name as the hole. For example, if the reporter templates define a hole named Title, the class definition file must define a property named Title.

• If the reporter uses a template stored in the template library of the template file, add a line to the constructor that sets the property TemplateName to the name of the reporter template. You do not have to specify this property in the class definition file because the customized class inherits this property from the base slreportgen.report.Reporter class.

For example, this class definition file defines Title, Author, and Version properties and specifies that the template name is MyTitlePage

classdef MyTitlePage < mlreportgen.report.Reporter 

    properties 
        Title = "";
        Author = "";
        Version = "";
    end 

    methods 
        function obj = MyTitlePage(varargin) 
            obj = [e-mail](varargin{:}); 
            obj.TemplateName = "MyTitlePage";
        end 
    end 

    methods (Hidden) 
        function templatePath = getDefaultTemplatePath(~, rpt) 
            path = MyTitlePage.getClassFolder(); 
            templatePath = ... 
                mlreportgen.report.ReportForm.getFormTemplatePath(... 
                path, rpt.Type); 
        end 

    end 

    methods (Static) 
        function path = getClassFolder() 
            [path] = fileparts(mfilename('fullpath')); 
        end 

        function createTemplate(templatePath, type) 
            path = MyTitlePage.getClassFolder(); 
            mlreportgen.report.ReportForm.createFormTemplate(... 
                templatePath, type, path); 
        end 

        function customizeReporter(toClasspath) 
            mlreportgen.report.ReportForm.customizeClass(... 
                toClasspath, "MyTitlePage"); 
        end 

    end  
end

Use Custom Reporters

To use your custom reporter:

1. Create an object of the reporter class.

2. Set the values of the properties that you defined in the class.

3. Append the object to a report.

For example:

import mlreportgen.report.*

rpt = Report("myreport","pdf");

titlePage = MyTitlePage;
titlePage.Title = "My Report";
titlePage.Author = "Me";
titlePage.Version = "1.0"
append(rpt,titlePage);

close(rpt);
rptview(rpt);