Customization of Signoff Forms in Review Editor

This example uses:

Modelscape for MATLAB Modelscape for MATLAB

This example shows how to customize review sign off forms using Review Editor app in the Modelscape™ Review Environment (MRE).

MRE comes equipped with a selection of forms that can be customized to sign off on a given review to match your validation processes. You can also create your own signoff forms using MRE.

The customization consists of two parts: formatting of the signoff forms and configuring the list of forms available to the validators.

Format Signoff Forms

Implement customized signoff forms as subclasses of an abstract interface class modelscape.review.app.signoff.SignoffForm. Begin by opening an example form in the Model Review Environment.

edit modelscape.review.app.signoff.forms.FullReview

In most cases, you can simply copy and rename this class, and edit it as required. The class definition must be on your MATLAB path.

You must give the validator a list of labels corresponding to various steps of the validation work, and a list of controls that allow users to input their comments. Labels are strings such as "Approved?", "Materiality" or "Known weaknesses", whereas controls include drop-down menus, checkboxes, and containers for free-form text; there should be one control for each label. The form also requires submit and cancel buttons. The layout of these labels, values, submit and cancel buttons is part of the configuration. To select the form from the submit review toolstrip dropdown, you also need a method called fullName().

Configure Components of the Form

This section shows you how to configure the components of the form.

Layout

Control the layout of labels, controls and buttons by a matlab.ui.container.GridLayout object that uses the Parent object of the form as its parent container.

this.UIGrid = uigridlayout(this.Parent, [8 4],...
    'ColumnWidth', {'1x','1x','1x', '1x'}, ...
    'RowHeight', {25, 50, 50, 50, 50, 25, 25, 25});

In this case, the grid has one row per label-control pair and one row for the submit and cancel buttons. Row heights vary depending on the type of control to be used.

Labels and Controls

Insert the labels and controls into the layout grid using utility functions in the MRE package.

import modelscape.review.app.signoff.helpers.formatLabel;
import modelscape.review.app.signoff.helpers.formatDropDown;
import modelscape.review.app.signoff.helpers.formatTextArea;
import mmodelscape.review.app.signoff.helpers.formatCheckBox;

These helper functions create the labels and controls, and place them in the layout grid. Placed them in arrays called this.Labels and this.Controls. For example, place a label "Risk rating" into the first column of the 6th row and a drop-down menu with selection "High", "Medium", "Low" (and default value "Select") into the second column of that row.

this.Labels{6} = formatLabel(this.UIGrid, 'Risk rating', 6, 1);
this.Controls{6}= formatDropDown(this.UIGrid, 6, 2, ...
                {'Select', 'High', 'Medium', 'Low'}, 'Select');

Use the other two helper functions in a similar way.

Submit and Cancel Buttons

Define the remaining two components using the following helper functions of the SignoffForm base class.

createSubmitReviewButton(this, 8, 3);
createDiscardReviewButton(this, 8, 4);

These will place the required buttons in the 3rd and 4th column of the 8th row of the layout grid. The helper functions also configure the buttons to trigger the appropriate events in the Review app.

fullName()

For each signoff form class, define a static method fullName(), which returns the name, or a short description, of the implemented class. Use a concise string to identify this customized form in the signoff dropdown list of the MRE main toolstrip.

An example of this method definition is as follows:

methods (Static)
    function fn = fullName()
        fn = "Full review signoff";
    end
end

Configure the Signoff Form Selection Menu

The signoff forms for review submission are in the dropdown list under the Submit Review icon in the Review Editor app. By default, the list contains the examples of the MRE package. This section explains how to configure the list.

Configuration File

Implement each signoff form as a class definition. Encode the list of forms shown to the user into an XML file that lists these classes in the following syntax.

The XML root node is called <formSelection>.
Define each form in the list by a <formDefinition> node. These will contain a <className> node that sets the full name of the form class to be used

For example, the following XML defines the forms shipped with the MRE package:

<formSelection>
    <formDefinition>
        <className>modelscape.review.app.signoff.forms.FullReview</className>
    </formDefinition>
    <formDefinition>
        <className>modelscape.review.app.signoff.forms.ReducedReview</className>
    </formDefinition>
</formSelection>

This file need not be stored in the MATLAB path.

MRE SignoffFormsSelection Setting

To point the MRE to the correct XML configuration file, use MATLAB settings. To see the current value of this setting, run:

s = settings;
s.modelscape.review.Signoff.ConfigFile.ActiveValue

The default value of this setting is the empty string.

If the configuration file is saved as c:\MRE\resources\formSelection.xml, set MRE to point to this file.

s.modelscape.review.Signoff.ConfigFile.TemporaryValue = "c:\Modelscape\resources\formSelection.xml";

Querying the active value as shown above should then return the location of the custom XML.

To reset the default setting, run:

s.modelscape.review.Signoff.ConfigFile.TemporaryValue = s.mrmreview.Signoff.ConfigFile.FactoryValue;