Main Content

Customization of Signoff Forms in Review Editor

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

MRE comes equipped with a selection of forms that you can customize 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 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 MRE.

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

In most cases, you can simply copy and rename this class, and then edit it according to your needs. The class definition must be on your MATLAB path.

You must give the validator a list of labels corresponding to the 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. Controls include drop-down menus, checkboxes, and containers for free-form text. Define one control for each label. The form also requires submit and cancel buttons. The layout of these labels, values, and buttons is part of the configuration. To select the form from the submit review toolstrip dropdown, you also need a method called fullName.

Configure Form Components

Layout

Control the layout of labels, controls, and buttons by using a matlab.ui.container.GridLayout object that uses the Parent object of the form as its parent container. Define a grid with 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 use.

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

Labels and Controls

Insert the labels and controls into the layout grid using 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;

Use these functions to create the labels and controls, then place them in the layout grid in arrays called this.Labels and this.Controls. For example, place the Risk rating label in the first column of the sixth row and a drop-down menu with selection High, Medium, Low, and Select values in 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');

Submit and Cancel Buttons

Define the remaining two components using helper functions of the SignoffForm base class. Place the required buttons in the third and fourth column of the eighth row of the layout grid. The helper functions also configure the buttons to trigger the appropriate events in the Review Editor app.

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

Define fullName Method

For each signoff form class, define the fullName static method, which returns the name or a short description of the implemented class. Use a concise string to identify this customized form in the signoff drop-down list of the Review Editor main toolstrip.

For this example, define a fullName method that returns the string Full review signoff.

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

Configure Signoff Form Selection Menu

The signoff forms for review submission are in the drop-down list under the Submit Review button in the Review Editor app. By default, the list contains the examples of the MRE package. You can configure the list for your needs.

Configuration File

Implement each signoff form as a class definition. Encode the list of forms shown to the user in an XML file that lists these classes. This file does not need to be on the MATLAB path.

  • The XML root node specified as a <formSelection> node.

  • Each form in the list, specified as a <formDefinition> node. These forms contain a <className> node that sets the full name of the form class to use.

For example, this XML code 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>

MRE SignoffFormsSelection Setting

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

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

If the configuration file is c:\MRE\resources\formSelection.xml, set MRE to point to this file. Querying the active value returns the location of the custom XML.

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

Reset the default setting.

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