How to use parameters in section rules
Section rules created in V5.4SP2+ have a Parameters tab and can accept parameter values. The parameter values can be accessed in specific situations within the section. Values for parameters can be set in other rules — during application developement — or dynamically at runtime.
This topic presents an example parameterized section.
Like the HTML Property rule form, Activity form, and report forms, the Section form has a Parameters tab. In V5.4SP2, you can reference the parameter values in any of three places:
- As label text
- As button caption text
- As the source of a parameter value to an HTML Property rule.
Parameterization promotes sharing and reuse, and so may allow you to build your application with fewer section rules to maintain. Values for parameters may be supplied either during development, or dynamically at runtime (if computed by an activity.)
Step 1. Define parameters
Create a section rule. Leave the Auto-generated? check box (on the HTML tab) selected.
Complete the Parameters tab. This tab on the Section form is similar to that tab on other rule forms. Choose a name for each parameter that starts with a letter and uses only letters and digits.
Enter a text description and select a type (
Integer). Other columns are optional.
Step 2. Reference parameters within the section
Within the section rule, use the notation param.name to reference the parameter value, where name is the parameter name.
For example, this section — for demonstration purposes only — has one example of each use.
The second row contains a property formatted with the CurrencyAmount HTML property rule, which accepts a parameter Size:
Finally, you can set a button caption to the value of parameter.
Save the Section rule form. At this point, you can test operation of the parameters using the Run toolbar button.
Step 3: Supply parameter values during development
You can specify parameter values for section rules in other rules — such as harness, section, or flow action rules — that include the section. For example, if the parameterized section is included within a dozen flow action rules, a button caption can be unique for each flow action.
For demonstration purposes, the example section ThreeParams is added to a flow action named SectionParameters. Click the magnifying glass on the Section tab of the Cell properties panel to enter parameter values.
In this example, the literal constant values for the three parameters are "The Label", "The Caption", and "15". If the same section is included in a different flow action, other parameter values can be supplied.
At runtime, the user of the flow action sees the effect of parameter values:
Or Step 4: Supply parameter values at runtime
Alternatively, your application can compute values for parameters at runtime with an activity, saving them to the parameter page of the activity by identifying them as
Out in the In/Out column.
The activity must execute before the section appears, so that the parameter values are set. For a flow action, you can ensure this by identifying the activity in the Before this action.. Run Activity field, on the Action tab.
To simplify the example, this activity simply sets the Out parameters to other literal values:
To pass the activity's parameter page to the section, check the Pass current parameters page check box on the parameters panel of the flow action form.
At runtime, the
Out parameter values computed by the activity are passed to the section (and to the HTML property rule referenced on the section.) While this activity is very simple, other activities can use whatever calculations are appropriate to compute the
Out parameter values.