Action Groups with Parameters
Parameters in Action Groups work as follows:
•You declare parameters in an Action Group, and then define actions (within this Action Group) that use these parameters.
•The values of parameters are passed to the parameters when the Action Group is called via the Execute Action Group action.
Declaring parameters in Action Groups, and defining actions that use these parameters
In the Action Group, declare the parameters that are needed to generate the required result. Do this by clicking the Add Parameter icon (see screenshot below). After a new parameter has been added, double-click to the right of the parameter's $ symbol, and enter the name of the parameter.
In the screenshot below, we have an Action Group named RectangleArea, in which we have declared two parameters named $length and $width. The parameters are not marked as Optional. This means that when the Action Group is called at runtime, the action group must receive values for both these parameters (see Supplying parameter values with Execute Action Group below); otherwise an error is reported. (For information about the Action Group check box, see the section Action Groups with Action-Group Parameters.)
The Action Group in the screenshot above consists of two actions:
•An Update Node action, which multiplies the two parameters $length and $width to generate a value that updates the Area node.
•A Message Box action, which displays a message box containing the value obtained by multiplying the two parameters $length and $width.
Note that, in the Action Group, we declare parameters and define actions that use these parameters. The values of the parameters are supplied at runtime, via the Execute Action Group action.
Variables in Action Groups
You can also define variables in Action Groups, that is you can declare variables and define a value for each. Note the following key points about variables:
•They are in scope within the Action Group, and can only be used within the Action Group
•The definition of the value of a variable can use parameters and variables that have been declared earlier in the list of variables. For example: If an Action Group has parameters $a, $b, $c, and variables $x, $y, $z (in that order), then the variable $y can use the following parameters and variables to generate its value: $a, $b, $c, $x, (but not $z).
Supplying parameter values with Execute Action Group
You can define an Execute Action Group action on an event, and in the action you can define the parameter values to pass to the selected Action Group. When the event is triggered, the parameter values are passed, and the Action Group uses these values to carry out the actions defined in the Action Group.
To create an Execute Action Group action, drag and drop the relevant Action Group (from the Action Groups pane) into the definition of an event's actions. On being dropped, the Action Group will be displayed as an Execute Action Group action. In the screenshot below, we have defined an Execute Action Group action for an OnButtonClicked event. We did this by dragging the RectangleArea Action Group below the On Click event. The currently selected Action Group to execute can be changed in the Execute Action Group combo box (circled in red in the screenshot below). Click the Additional Options icon to open the selected Action Group. Alternatively, you can use an XPath expression to select the Action Group. Using an XPath expression enables you to select the Action Group dynamically (for example, by getting the name of the Action Group from a page-source node). The XPath expression must return a string that is the name of an Action Group defined in the project.
If parameters have been declared in the currently selected Action Group, then these parameters are displayed in the Execute Action Group action. This is where you supply the values to pass to parameters at runtime. In the screenshot above, it can be seen that the RectangleArea Action Group has two parameters: $length and $width. We have entered simple static values (3 and 4) in the XPath expressions that are used to generate the values of these two parameters. But you can also obtain values from XML tree sources dynamically, or specify complex XPath calculations. If, in the Action Group, the parameters were declared as mandatory (not optional), then they will be displayed here in red if no values are supplied.
At runtime, the following happens:
1.When the event is triggered, the parameter values (as specified in the Execute Action Group action) are passed to the respective parameters in the Action Group.
2.The Action Group's actions are processed. Where these use the Action Group's declared parameters, the supplied parameter values are substituted.
Types of parameter values
In the Execute Action Group action, parameter values can be of the following types, either entered directly or generated dynamically (by using XPath expressions):
•Atomic values: for example, strings such as "Altova" or numbers such as 1 or 2.56
•Arrays: for example, [(2010,2019), ("StartYear","EndYear")]
•Maps: for example, map{"StartYear":2010, "Offices":("Boston","Vienna")}