Scripting and Dependencies |
|
|
|
|
|
Scripting and Dependencies |
|
|
|
|
Scripting and Dependencies |
|
|
|
|
|
Scripting and Dependencies |
|
|
|
|
|
|
||
A major advantage of using the Avoka Transact environment — rather than writing your forms from scratch in HTML, Javascript and other scripting languages and writing the server-side process — is that the bulk of the form's implementation is taken care of for you.
But this means that you still have enormous scope to specify how the form behaves and to inject scripts into the form. In this topic, we will discuss the general principals for scripting.
There are two ways to script in Composer:
1.Where available there is also a Rule Editor
2.A point-and-click Script Editor window
3.Writing a script yourself in a text editor
The first, the Rule Editor, is for performing simple logic operations. This editor is rather limited.
The second is for Javascript scripts. The editor is far more capable, but requires a knowledge of Javascript.
The third way is covered in the advanced topic Scripting and these scripts can be complex.
In either case, the language used is JavaScript, but with slightly modified function calls, documented here.
Scripts and Rules go in the Rules Tab. This has LH Menu items and depending, on the nature of the field, can have from none to 7. Here is an example of a Rules tab with a full LH Menu:
Within each panel there are several types of properties:
•"Rule" properties
•"Policies"
•"Messages"
•"Actions"
•and some checkboxes in, for example, "Mandatory" rules
•and "Responsive Rulesets" which are exclusive to the Responsive Rules.
This type of property has a dropdown menu:
•Script Based (always available in all "Rules" properties)
•Rule Based (available in only some "Rules" properties
•Always (available in "Editable Rules" and "Mandatory Rules")
•Never (available in "Editable Rules" and "Mandatory Rules")
•No Validation (only for "Validation Rules")
•Regular Expression Pattern (only for "Validation Rules") for pasting in a regular expression for validation
•Fixed Length (only for "Validation Rules")
The "...based" items bring up an "Edit..." button, which takes you to the rules editor or script editor..
These are always dropdown menus and the choices are restricted to only those that appear in the menus.
The types of policy are:
•Editable Policy
i.e. whether the field (or fields) and its children are writable or read-only
Determines what happens when the field is not editable according to the rule in the Edibility panel. Options:
oDisable and gray out text
oDisable
oGray out
•Editable Clearing Policy
for more, see Privacy.
•Visibility Policy
oWhen hidden exclude from layout
(i.e. the hidden fields disappear entirely)
oWhen hidden don't exclude from layout
(i.e. leave space for the hidden fields)
oWhen hidden gray out
•Initial Visibility (Policy)*
see below.
oVisible
oInvisible
(i.e. the invisible fields are not excluded from the layout)
oHidden
(i.e. the invisible fields do not appear and their allocated space in the form does not appear as a blank area)
•Validation Policy
(see Validation as there is rather more to this than just the following 2 options)
oShow error dialog
oNot show error dialog
Note: The intent Initial Visibility settings is meant to speed up the initial rendering of the form. If the form is taking a long time to render, visibility rules and visibility policies may be the issues. You can sidestep these by setting the Initial Visibility policy for the relevant fields so that the form will render first up without having to test these rules and policies.
These are text fields, whose contents are displayed when the rule type — usually "Mandatory" or "Validation" — fails (though you also have the option of displaying the message if the rule passes instead).
These are exclusive to "Click" LH Menu item. The Click panel only has the "Edit..." button for providing a script. The Rules editor is not available. The script will run only when the field (either a button or a link) is clicked on.
The checkboxes in the Rules tab panels are for simple either-or options, such as whether the mandatory asterisk will display for mandatory fields.
These apply only to Responsive Layout settings for the field. See Responsive Layout for more on this.
You build up a rule with the Rule Editor a "term" (or line in the editor) at a time with a maximum of 10 terms. Each term compares 2 fields on the form, which you select using the two magnifying icons, each of which brings up a "Select a field" dialog containing a mini Structure Panel, as shown.
On the left-most column of each term, there is a dropdown in which you select whether the two fields in the term are strings, numerical or Boolean. Between the two fields is the relationship between the two: "Equals", "Not Equals", "<", "<=", ">" or ">=".
Add more terms as required and then select the relationship between all the terms. You can only nominate one relationship for all the terms. They are:
•"AND", meaning that the rule is true only if all the terms are true
•"OR" where the rule is true only if all the terms are false.
The Specification tab is a text area where, if you
If you know something of Javascript, you can do far more with the Script Editor.
Using this editor requires some knowledge of JavaScript. In this section of the guide, we will only be using very simple sample scripts. The script editor facilitates integration of your JavaScript code with the fields on the form.
The script editor can accomplish much more than the Rule Editor;
•Calculations such as summing the values of fields together, or multiplications, averages and so on
•Write more complex scripts involving "if" statements, loops and so on
•In fact, virtually anything the JavaScript is capable of.
Just to be clear, though the scripting language of Composer is JavaScript with some minor differences. One of these allows Composer's JavaScript to use the fields in the form as variables. This makes Composer's scripting capabilities very powerful indeed.
More ground on this will be covered in Scripting in the Advanced Topics. For now, we will be content to just demonstrate how you use the editor to integrate a script into the form.
To make the editor work, you need some working knowledge of JavaScript. We have already given an example of a total in the footer of a table. That example is a sum of repeating elements. The following is a simple multiplication of two non-repeating fields, just to illustrate how scripting works in Composer on a simple level.
Here is a very simple form where we take the first writable field "Amount1" (a dollar value currency field) and multiply it by the second writeable field "Amount2" and display it in "total" a read-only currency field to the right.
We made a few tweaks to "Amount2" and "total" and the "times" and "equals" texts to get the layout as shown below in Edit Properties for each of these fields:
•For all, "Properties -> Layout -> Layout Constraints -> Keep on same line (checked)"
•For "total", we made it read-only by "Rules -> Editability -> Editablity Rule -> Never Editable"
We could have saved ourselves the trouble of changing each widget by creating a containing block of the 3 widgets and the plain text objects "times" and "equals" and then setting the Layout Constraints.
So, to see the calculation in action, we need to preview the form. Here is what it looks like after inputting a couple of arbitrary values into Amount1 and Amount 2
The JavaScript in the example is only one line, which is the reason the line doesn't end in a semi-colon (";").
If want someone else on your team to do the scripting or work the Rules Editor, use the Specification tab to describe the behavior you require. That description will then attach to the field or block.
When a user loads a form, fills in its various sections, uploads any attachments and eventually submits it, the form has triggered many events, which Composer groups into "phases", covered in more detail in Business Rules and Advanced Scripting.
Some of these triggers are the dependencies between fields created by scripting. In the above simple example, the "total" field listens to "Amount1" and "Amount2" and when "total" sees that the other 2 now have values, it will calculate and display the value of the calculation. The user does not have to click on a special button to get the total, the form does not have to be reloaded, nor does the user's browser (in this case) have to send anything to the server in this phase. The calculation happens autonomously.
When a form is complex, though, having very many dependencies can create performance issues. Composer has many strategies to tune such forms. One of them is to tune the triggering in the form so that it does not grind to a halt every time the user changes a value in any of the fields. In Composer 4, for the first time, you can inspect triggers and dependencies on the form.
When you paste script into the text area of the Script Editor, remember that you still have to associate the fields on the form, using the same point-and-click method shown above and setting the field references.
The triggering conditions of the above simple demo script are listed in the "Triggering Conditions" tab of the Script Editor. We will discuss the advanced settings of the radio buttons in the lower half of the tab later in Advanced Scripting.
Additional events will be covered in the Business Rules widget discussion.
Use "Edit Properties -> Dependencies" to inspect the dependencies feeding into the script (in the "My Rule Dependencies: panel) and the outgoing triggers in the "Triggered Rules" panel.
