Specify Tasks for a Component to Perform

About Component Customization

Building a component creates MATLAB^® files in the MATLAB workspace. Specify tasks that you want your component to perform by editing these MATLAB files.

Note

You must specify the format and content of your report output by editing execute.m. This file is called during report generation to invoke your component's tasks. Optionally, you can specify additional component properties and behavior by editing other MATLAB files.

For more information, see the following sections:

Required Customization: Specify Format and Content of Report Output

After you build the component, specify the format and content of your report output by editing the execute.m file.

The execute command has the following syntax:

out = execute(thisComp, parentDoc)

Where:

thisComp is a handle to the component that you are running.
parentDoc is a handle to the document that you are generating.
out is a Document Object Model (DOM) node or string to add to the report.
For information on manipulating DOM nodes, see xmlwrite in the MATLAB documentation.

One or more default lines of code within the execute.m file show each property for the component. Here is an example of a component property line within an execute.m file:

pstring = thisComp.NewStringProperty;  % New string property;

The following sections describe how to edit execute.m to create additional report elements.

Create Tables

To create a table, replace the Source property value with the name of a cell array or structure:

out = execute(rptgen.cfr_table(...
'Source', tableSrc,...
'numHeaderRows',1,...
'TableTitle','Example Title'),...
 parentDoc);

For more information, enter help(rptgen.cfr_table) at the MATLAB command line.

Create Lists

To create a list, replace the Source property value with the name of a cell vector:

out = execute(rptgen.cfr_list(...
'Source', listSrc,...
'ListStyle','orderedlist',...
'ListTitle','Example List'),...
 parentDoc);

For more information, enter help(rptgen.cfr_list) at the MATLAB command line.

Create Text

To create text, replace the ParaText property value with a character vector:

out = execute(rptgen.cfr_paragraph(...
'ParaText', paraSrc,...
 parentDoc);

For more information, enter help(rptgen.cfr_paragraph) at the command line.

Create Figures

To create figures, specify a figure in the FigureHandle property value.

figSrc = gcf;
out = execute(rptgen_hg.chg_fig_snap(...
'FigureHandle', figSrc,...
'Title', '',...
'isResizeFigure', 'manual',...
'PrintSize', [6 4],...
'PrintUnits', 'inches'),...
 parentDoc);

For more information, enter help(rptgen_hg.chg_fig_snap) at the MATLAB command line.

Run Child Components

The following code runs child components. The first line calls execute.m for child components. The second line appends the results of running the child components to the report:

childOut = thisComp.runChildren(parentDoc);
out = parentDoc.createDocumentFragment(out, childOut);

Change a Component's Outline Text in the Report Explorer Hierarchy

To change the string used to describe the component in the Report Explorer hierarchy, edit the getOutlineString MATLAB file. By default, getoutlinestring returns the display name of the component. The getOutlineString command has the following syntax:

olstring = getOutlineString(thisComp)

Where:

thisComp is the component whose description you are specifying.
olstring is a single-line that displays information about the component. It can contain a maximum of 32 characters.

Customize the string to include additional information about the component, such as information about its properties. In the following example, the truncatestring function converts input data into a single-line character vector. If the data is empty, the second argument is the return value, The third argument is the maximum allowed size of the resulting character vector.

cInfo = '';
pstring = rptgen.truncateString(thisComp.string,'<empty>',16);

Use a dash (-) as a separator between the name and additional component information, as follows:

if ~isempty(cInfo)
   olstring = [olstring, '-', cInfo];
end

Modify the Appearance of Properties Dialog Boxes

You can edit the getdialogschema.m file to control most aspects of dialog box layout, including:

Creation and placement of widgets
Organization of widgets into panes
Creation of the top-level display within which panes reside

The syntax of the command is:

dlgstruct = getdialogschema(thisComp, name)

Where:

thisComp is the instance of the component being edited.
name is a character vector that is passed to getdialogschema to build a specific type of pane. Usually, name is empty in the Report Explorer.

Note

Do not modify fields that are not explicitly included in this file. These fields are subject to change in future releases.

Specify Additional Component Properties

You can edit additional MATLAB files to customize your component further. To access these files, right-click the component in the Outline pane on the left in the Report Explorer and select Edit files from its context menu.

Outline pane with component right-clicked to bring up content menu

For more information, see the following sections:

Specify Whether Components Can Have Children Components

To specify whether a component can have children, edit getParentable.m. This command returns the value true or false. For example, if you no longer want your component to have child components, modify the value within the code as follows:

p = false;

Modify a Component Description

The description in getDescription.m is the same value as the Description field in the Report Explorer. The following example shows how to edit the compDesc value in this file to change a component's description to An example component:

compDesc = 'An example component';

Change a Component Display Name

The display name in getName.m is the same value as the Display name field in the Report Explorer. The following example shows how to edit the compName value in this file to change a component's display name to Example Component:

compName = 'Example Component';

Change a Component Category Name

The category name in getType.m is the same value as the Category name field in the Report Explorer. The following example shows how to edit the compCategory value in this file to change a component's category name to Custom Components:

compCategory = 'Custom Components';

Register Components

You can register components in the Report Explorer using rptcomps2.xml. This file also helps build the list of available components.

The content of this file must be consistent with the values in the getName.m and getType.m files. If you have changed values in either of these files, you must also change their values in rptcomps2.xml. You must restart the MATLAB software session for the Report Explorer to display new information.

Display Component Help in the System Web Browser

The viewHelp.m file displays a help file for the component in the system web browser. To display the help file, highlight the name of the component in the Report Explorer and click Help.