Main Content

Define Components

Required Component Data

You must specify the following information when you create a component:

  1. The path where you want to put the folder that contains all files for the component. For information on how to specify this folder, see Specify the Location of Component Files.

  2. Properties of the component. For more information, see Specify Component Properties.

  3. Display options for the component, including its display name, category, and description. For more information, see Set Component Display Options.

Specify the Location of Component Files

You can create components that perform similar functions and group them in Namespace Directories. Each namespace folder must have a Parent Directory that is in the MATLAB® path. When you build a new component, the MATLAB Report Generator™ software creates files that make up the component. These files are stored in the folder structure <parent>/@namespace_name/@class_name.

Specify these directories in the following fields in the Component File Location area of the Properties pane:

  1. Class Directory field. Specify a class name for your component. The build process creates a folder with the name you specify and places the component's files in it. The class folder name must be unique for each component in the namespace. By convention, component class names begin with an uppercase or lowercase letter c; for example, cUserDefinedComponent.

  2. Namespace Directory field. Specify the folder in which to store files for groups of components you create. Files for each component are stored in a subfolder with the name you entered into Class Directory Field.

  3. Parent Directory field. Specify this folder when you create a namespace for the first time. This folder is the parent folder of the Namespace Directory.

Set Component Display Options

You can specify how you want your component to appear in the Report Explorer by entering data in the Component Display Options area of the Properties pane. Enter the following information:

  1. Display Name. Specify a display name for the component to appear in the list of components for its associated category. Component categories and display names appear in the Options pane in the middle of the Report Explorer.

    For information on specifying component categories, see step 3, Category Name.

    The following example shows how to create a component called My First Component in a category called My Category.

    Component Display Options area of the Properties pane. Display name is set to My First Component, Description is set to The first component, and Category name is set to My Category.

  2. Description. Enter a description for the component. This description appears when you click the component name or category name in the Options pane in the middle of the Report Explorer. Make the description informative, but brief.

  3. Category Name. Specify the category of components to which the new component belongs. The component appears under this category in the Options pane in the middle of the Report Explorer.

    Predefined choices appear in the Category name list. Select a component category from this list.

    Component Display Options area of the Properties pane. Category name drop-down is expanded and shows MATLAB selected.

    To create a custom component category, type the name for the category into the Category name field. This category name appears in the list of available categories in the Report Explorer.

    Category name with custom name My category displaying

  4. child components.

    Select the Component may contain children check box if you want the component to have child components. Child components appear under the component in the Report Explorer hierarchy. During report generation, the component runs all child components and includes their output in the report.

Specify Component Properties

Component properties determine how a component behaves and what information it inserts into a report. To see the current value of a component's property, double-click it in the Outline pane on the left in the Report Explorer. For example, the figure shows the property values for New_String_Property.

Report Explorer with New_String_Property selected in the Outline pane on the left, and New_String_Property selected in the Options pane in the middle, with the corresponding properties listed in the Properties pane on the right

Add Properties to Components

You add properties to a component from the properties list. Each property has a default value that you can modify as needed.

There are several ways to add properties to components:

  1. Right-click the name of the component to which you want to add properties in the Outline pane on the left. Select Add new property from its context menu.

    Outline pane with context menu that displays upon right-click

  2. Right-click the name of a predefined property in the Options pane in the middle. From the context menu, select Add property.

    Outline pane with Add property button that displays upon right-clicking the name of a predefined property

  3. Left-click the name of a property in the Options pane, and then drag it on top of a component in the Outline pane on the left.

  4. Double-click the property name in the Options pane in the middle. The property is added to the component and property values appear in the Properties pane on the right.

    Report Explorer showing the property New_String_Property when dragged to the Outline pane

  5. Click the Add Property button on the Properties pane on the right.

    Properties pane that displays in the right pane of Report Explorer

Specify Component Properties

  1. Property Name. Create a name for the new property. A property name must be a valid MATLAB variable name, and must be unique within a component.

  2. Data Type. Specify the property's data type. Options are:

    • Double

    • Enumeration

    • Integer

    • Character vector

    • Character-vector vector

    • %<ParsedString>

      Use this data type to include the value of a variable in the MATLAB workspace in a component.

    • True/False

  3. Default Value. Set a default value for the property. The default value must be compatible with the data type. If incompatibilities exist between the default value and the data type, the component might not build.

  4. Dialog Prompt. This text appears next to the widget on the component's dialog box. It indicates what the property does and how it affects report generation.

    Note

    When the component builds, a colon is appended to your entry in the Dialog prompt field. Your entry appears in the Properties pane with the colon appended.

Modify Existing Components

Report components are modifiable. You can derive a new component from an existing component by double-clicking the name of the component and modifying its values and properties.

Build Components

After you have entered all data required for defining the component, you build it by clicking the Build Component button. The build process creates all files needed for the component and stores them in the specified folder. For more information about specifying where components are stored, see Specify the Location of Component Files.

Note

Existing files in this location are overwritten.

Rebuild Existing Components

To add, remove, or change properties of an existing component, use the Rebuild Constructor button. This button becomes active only after you have previously created a component using the Build Component button. To activate the Rebuild Constructor button, specify the Package name and Class name for an existing component. These fields are located in the Component File Location area of the Properties pane.

If you select a component using Tools > Create component from, the component's fields are filled in automatically and the button becomes active.

After you have finished modifying the component, click the Rebuild Constructor button to rebuild the component. Writable files in the component's folder location are not overwritten.

Remove a Component

To remove a component:

  1. Delete its class folder, <root>/@namespace_name/@class_name. If the component you want to remove is the only component in the namespace, delete the entire namespace.

  2. Edit <root>/@namespace_name/rptcomps2.xml to remove the XML element that registers the component.