<WITH/> Determining values
Determine values that are available in the current context
Every rule initially determines a value (in the current context of rule execution), that can be based on one or more properties of the form (“In which editorial language is the form edited?”) or an individual form element (“Is the value of the component NULL?”). The desired properties are taken into consideration in the value determination of the rule definition.
A value determination is defined with a <WITH/> section. This section must be defined before the tags that initiate a handling instruction. Insofar as a precondition is defined for the rule, the value determination is defined according to the precondition.
In the process, the following applies for the definition of a value determination:
- For each rule, a value determination must be defined.
- In the simplest case, the template developer can define a constant (<TRUE/>, <FALSE/>, <TEXT/>, <NUMBER/>) within the <WITH/> section.
- The value determination, however, can also be considerably more complex and refer to values or properties of the form or a form element. The specification of a <PROPERTY/> tag is then necessary within the value determination tag. Through
- logical (<AND/>, <NOT/>, <OR/>),
- comparative (<EQUAL/>, <GREATER_THAN/>, <LESS_THAN/>, <NULL/>/<NOT_NULL/>, <CONTAINS/>), or
- regular expressions (<MATCHES/>),
- The result of the value determination (Boolean value, text, date, etc.) is passed on by the FirstSpirit framework during the execution of the rule and can be linked with the appropriate handling instruction by the rule developer.
- If the result of the value determination is a Boolean value, a negation can be achieved using the <NOT/> tag, in conjunction with
Determine values that are available outside the current context
In addition to values that are available in the current context of a rule execution, i.e. that affect the current form or FirstSpirit element in which the rule is executed, it is also possible to access FirstSpirit elements that are outside the current context.
This means that information from other forms, e.g.:
- form data from another page,
- from metadata forms, or
- from the project settings
can be retrieved.
This value determination is executed in a rule definition via the <SCHEDULE/> tag using the services FormDataValueService or MetaDataValueService:
For documentation and examples see Accessing information from other forms.
Examples
Example 1) Determining the Boolean value and link it to a validation
A form has one entry field each for a creation date (“st_creationDate”) that is automatically assigned and an expiration date (“st_endDate”) that is entered by the editor. A dynamic form should guarantee that the expiration date entered by the editor should lie after the creation date.
Within the <WITH/> section, the values of both input components are first retrieved through a <PROPERTY/> tag and then a simple <GREATER_THAN/> check is performed on both values. The result of this check is a Boolean value that is then linked with a validation in the <DO/> section. As long as the condition (“expiration date lies after the creation date”) is not fulfilled, the <VALIDATION/> section of the rule is executed.
<RULES>
<RULE>
<WITH>
<GREATER_THAN>
<PROPERTY source="st_endDate" name="VALUE"/>
<PROPERTY source="st_creationDate" name="VALUE"/>
</GREATER_THAN>
</WITH>
<DO>
<VALIDATION scope="RELEASE">
<PROPERTY source="st_endDate" name="VALID"/>
<MESSAGE lang="*" text="Please enter a valid date"/>
<MESSAGE lang="DE" text="Bitte geben Sie ein gültiges Datum"/>
</VALIDATION>
</DO>
</RULE>
</RULES>
Example 2) Determine the values and link them to a handling instruction
Instead of a Boolean value (see example 1), the value determination can return a result quantity.
The following form contains two input components of the type CMS_INPUT_COMBOBOX, whose value quantity is automatically from a database table. The dynamic form should now guarantee that only the products of the selected supplier are displayed after it is selected from the “st_supplier” selection list when the “st_dish” combo box is opened. The selection from the first selection list thus influences the selection quantity of the dependent, second selection list.
Within the <WITH/> section, the value of the first input component is retrieved through a <PROPERTY/> tag. The result of this value determination is then linked to a handling instruction in the <DO/> section of the rule. In this case, no validation is executed, but rather the value quantity of the “st_dish” input component is filled dynamically with values from a database table through an additional <PROPERTY/> tag (cf. CMS_INCLUDE_OPTIONS). In the process, the determined value from the “st_supplier” combo box acts as the key.
<RULES>
<RULE>
<WITH>
<PROPERTY source="st_supplier" name="VALUE"/>
</WITH>
<DO>
<PROPERTY source="st_dish" name="query.supplier_id"/>
</DO>
</RULE>
</RULES>
If you would like to reset the selection from the second input component if the selection of the first input component is reset, this can be realized using another rule using the EMPTY property:
<RULE>
<IF>
<PROPERTY name="EMPTY" source="st_supplier"/>
</IF>
<WITH>
<TRUE/>
</WITH>
<DO>
<PROPERTY name="EMPTY" source="st_dish"/>
</DO>
</RULE>
Example 3) Negation
The template contains 3 text fields in this example:
- Text field 1: “st_text_1”
- Text field 2: “st_text_2”
- Text field 3: “st_text_3”
Text field 1 is always displayed, text field 2 is shown if text field 1 is empty, and text field 3 is shown if text field 1 is not empty.
<RULES>
<RULE>
<WITH>
<PROPERTY name="EMPTY" source="st_text_1"/>
</WITH>
<DO>
<PROPERTY name="VISIBLE" source="st_text_2"/>
<NOT>
<PROPERTY name="VISIBLE" source="st_text_3"/>
</NOT>
</DO>
</RULE>
<RULES>