ENTRY property
Using the selected value of a selection list
FirstSpirit recognizes two types of complex selection lists (in which only a single entry can be selected):
The “values” of these selection lists are complex objects (of the OPTION data type).
The ENTRY property is used to read out a text version of the selected value from a selection list in a form and to evaluate it using a dynamic form. Thus, for instance, rules can be defined for displaying or hiding additional input components in the form, depending on the value selected from the selection list.
The expression <PROPERTY source='combobox' name='ENTRY'/> can be used in the value determination area of the rule definition (or for the definition of a precondition) and supplies a text version of the value from the selection list (not the value itself).
In addition to defining a complete condition for value-dependent validation, for example:
- “Was entry A selected from the selection list?” or
- “Was an entry not equal to A selected from the selection list?”
a text comparison value (for example, <TEXT>A</TEXT>) and the <EQUAL/> operator must be specified. In this case, the expression returns a Boolean value.
 |
Values selected in a CMS_INPUT_CHECKBOX type input component cannot be evaluated using the ENTRY property. |
|
If the number of values contained in a CMS_INPUT_CHECKBOX (dynamically populated using a database query) are to be read out or set using a rule, then the “query” prefix in the <PROPERTY/> tag must precede the database query identifier (FILTERPARAM) For an explanation, see: Exception: setting dynamic values using a database query For an example, see: Determining the dish/supplier and substitute |
Using the selected value of a dynamically populated selection list
Using the ENTRY property, not only is it possible to provide the text version of the selected value in a selection list, but the OPTION key value can be provided as well. The ENTRY property also makes it possible to evaluate values within selection lists that are dynamically populated (with the help of the CMS_INCLUDE_OPTIONS data element).
The selection quantity can be populated, for instance, with project languages, template sets, datasets from an external table, etc. To check these values using a dynamic form, usable key information must be present. For instance, the template developer must provide a suitable key column for datasets (for a number of values filled using datasets from an external table). The key column for the CMS_INCLUDE_OPTIONS (DATABASE type) data element is defined via the optional KEY tag (the primary key typically returned here cannot be used with dynamic forms).
The suitable key value can also be used to check other types of CMS_INCLUDE_OPTIONS via a dynamic form:
- DATABASE type: Checking the value from the key column is possible.
- LANGUAGE type: Checking the language code is possible.
- TEMPLATESET type: Checking the UID of the template set is possible.
- PUBLIC type: Checking the key value provided by the relevant GomIncludeValueProvider is possible.
Examples
Example 1) Displaying or hiding form components depending on the selected value in a selection list
The following form contains a (CMS_INPUT_COMBOBOX type) “selection” selection input component with the statically defined selection quantity (0,1,2) and three additional (CMS_INPUT_TOGGLE type) input components. A dynamic form is used to display different input components in the form, depending on the value selected in the selection list:
- No selection = display input component “st_all”
- Value 0 selected = display input component “st_all”
- Value 1 selected = display input component “st_all” and “st_A”
- Value 2 selected = display input component “st_all” and “st_B”
In the case of the “st_all” input component, no rule is defined, and therefore this input component is always displayed in the form. In the case of input components “st_A” and “st_B”, the VISIBLE property is defined in the rule definition. This means that the components are only displayed if the condition defined in the rule applies. In all other cases, the component is not displayed:
<RULES>
<RULE>
<WITH>
<EQUAL>
<PROPERTY source="selection" name="ENTRY"/>
<TEXT>1</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY source="st_A" name="VISIBLE"/>
</DO>
</RULE>
<RULE>
<WITH>
<EQUAL>
<PROPERTY source="selection" name="ENTRY"/>
<TEXT>2</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY source="st_B" name="VISIBLE"/>
</DO>
</RULE>
</RULES>
Example 2) Checking a value from a dynamically populated selection list
The following form contains an “st_combobox” input component (of the CMS_INPUT_COMBOBOX type) with the dynamically populated selection quantity (A,B,C). The number of values is populated dynamically via datasets from an external table. The <KEY/> tag is used to define the “Name” column of the content source:
<CMS_INPUT_COMBOBOX name="st_combobox" hFill="yes" singleLine="no" useLanguages="no">
<CMS_INCLUDE_OPTIONS type="database">
<KEY>Name</KEY>
<TABLE>mytable</TABLE>
</CMS_INCLUDE_OPTIONS>
<LANGINFOS>
<LANGINFO lang="*" label="COMBOBOX (DB-Include)"/>
</LANGINFOS>
</CMS_INPUT_COMBOBOX>
The selected value (stored within the “Name” column of the database table) can now be accessed within the rule definition using the ENTRY property:
<RULES>
<RULE>
<WITH>
<EQUAL>
<PROPERTY source="st_combobox" name="ENTRY"/>
<TEXT>A</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY source="st_value_a" name="VISIBLE"/>
</DO>
</RULE>
</RULES>