Occasionally while developing Maestro forms you may see a behavior that doesn't seem right and you can't figure out why. This usually occurs in relation to rules that you've created using the script editor.
The following sections describe some advanced debugging techniques that you can use to find out what is going on in your script and in the form data.
This article is focused on functional aspects of the form - debugging of CSS and styling issues is not covered.
The architecture of a form consists of 3 main elements:
These 3 elements are all closely related. Form items appear in the Form View and have Data elements associated with them:
The form view is a hierarchical structure that consists primarily of horizontal rows, each containing one or more components. The hierarchical structure represents the layout of the form and all components within it.
Being hierarchical, rows in the view can be containers for lists of more rows in a recursive manner.
Each form item in Maestro is uniquely identified by a field Id. Maestro generates these field Ids based on the name of the field but also allows you to override the generated value and manually specify a field Id so long as they are unique in the context of the form.
Having guaranteed unique field Ids for all items within a form allows us to have a flat list (array) representation containing all items in the form, making access to these items much simpler than having to navigate a view hierarchy to find them.
Items can contain UI elements, but also have properties and rules associated with them. By way of demonstration, consider a mandatory first name field that has a maximum length of 120 characters and a visibility rule:
All data in the form is stored in a single object called the Form Data object. Like form items, each form data element must have an id that is unique in the context of the form. If a data element exists with the same Id as a form item, that form item will read and write its data to that data element. Data elements can exist without being bound to a form item.
Depicted below is 4 data elements, 3 of which are bound to fields (items) and one that is un-bound (verifyStatus). The middleName data element is blank suggesting that nothing has been entered into the middleName field.
Data elements that are not bound to form items (verifyStatus in this example) will not be Saved/Submitted with the form data and so only exist for the duration of the session.
Note that the Data Field component type can be used to bind data elements without having to display them in the visual layout so that they get persisted with the form data.
When you publish a Maestro form there are a number of options available to you.
Some of these are very relevant to debugging, these are:
Deselect this option.
Code minification is the process of compressing code to reduce the size and therefore load time, but does not affect the operation of the code.
The process removes unnecessary characters from the code,white space, new line, comments etc...
The result of minification is a single line of code that is very long and difficult to read and debug so ensure that this option is deselected for debugging.
|Remove Automation Framework|
Deselect this option.
The automation framework built into Maestro forms facilitates UI driven automated tests such as those that would be run from test tools like Selenium.
in order to start a debugging session you should:
While debugging forms you may need to republish your form with changes multiple times and you need to refresh the page with your published form on it each time. The following keyboard shortcuts are available for you to use to streamline this process:
Refreshing the page with the republished form on it should leave the browser developer tools active so you should not need to reactivate them each time.
In the Maestro framework, the Form object contains everything else you might need to access for debugging including the View, Items and Data (see Maestro Form Architecture), so to access any of these elements you need to scope the Form object. There are a number of ways to do this from the Console tab in the browser developer tools:
Enter one of these directives into the Command prompt in the Console tab and press Enter to scope the Form object:
Opening up this object you will see a long list of sub elements but among those you will find the 3 key elements to the Maestro Form Architecture, the Form Data object,
the Form Items,
and the Form View.
There is a handy Util function to generate a printable representation of an item and log it to the console as follows:
$scope.Util.logItem($scope.Form.items.personalDetailsBlock) "personalDetailsBlock ┌ firstName └ middleNames ─ lastName ─ dateOfBirth ┌ day │ month └ year ─ date ─ daysData ─ emailAddress ─ mobileNumber "
The following codes represent the types of rules used by the Maestro foundation widgets:
|Rule Type Code||Description|
|sh||Short for show, this is the code for a visibility rule that controls whether the field is presented on screen. The result of this rule should be a boolean value where true = visible, false = read-only.|
|us||Short for usable, this is the code for an editability rule that controls the read-only status of a field. The result of this rule should be a boolean value where true = editable, false = read-only.|
|md||Short for mandatory, this is the code for a mandatory if rule that controls the required state of an item. The result of this rule should be a boolean value where true = mandatory, false = optional.|
|ok||Interpreted as OK, this is the code for a validation rule that controls the error state of the field. The result of this rule should be a string that is either blank (for valid values) or contains the error message (for invalid values).|
|chok||Interpreted as Change OK, this is the code for a validate after change rule that augments the standard validation rule to provide support for dynamic data validations. The result of this rule can either contain the error message (like the standard validation rule) or a promise.|
Short for equals, this is the code for a calculation rule. The result of this rule should be the calculated value of the field.
Warning: In Maestro, calculation rules are not triggered if the field they belong to is not visible.
|click||A click rule is an action rule triggered by clicking on a clickable UI item.|
|blur||A blur rule is an action rule triggered when the focus leaves a field.|
|focus||A focus rule is an action rule triggered when a field acquires the focus in the browser window.|
|change||A change rule is an action rule triggered when the value of a field changes.|
|dc||An acronym for dynamic class, this rule can be used to apply a css class to a field dynamically based on logic.|
|load||An action rule that is triggered at the time the form is loaded.|
|presubmit||An action rule that is triggered prior to form submit.|
|postsubmit||An action rule that is triggered after the form submit event.|
|onSuccess||This rule type is specific to the Dynamic Data Button and is an action rule that is executed upon successful completion of the dynamic data function.|
|onFailure||This rule type is specific to the Dynamic Data Button and is an action rule that is executed upon failure from a dynamic data call.|
Note: widget developers can create additional rule types for their widgets.
|sh_previousAddress||A visibility rule on the previousAddress block|
|eq_totalIncome||A calculation rule on the totalIncome currency field|
|ok_emailAddress||A validation rule on the emailAddress field|
|click_verifyIdentity||A click rule on the verifyIdentity button|
|load_AvokaSmartForm||A load rule on the form|