Switching to the new syntax in FirstSpirit version 5.2

Starting with FirstSpirit version 5.2, the syntax which can be used on the “Rules” tab, has been optimized. This page shows differences and innovations concerning the syntax.

Existing rule definitions from earlier FirstSpirit versions are still valid in FirstSpirit version 5.2 and will be interpreted accordingly. However, the old syntax will become invalid and will cease to be supported at some point in the future. Therefore, the new syntax should be adopted as soon as possible.

What has changed?

Restriction levels

The restriction levels that were previously defined by means of the

• <ON_EVENT/>
• <ON_SAVE/>
• <ON_RELEASE/>

tags are now mapped via the “scope” parameter in the VALIDATION tag. These parameters can be set to the following values

• INFO
• SAVE
• RELEASE

The default setting (i.e., if the “scope” parameter has not been specified) is INFO.

Example old:

<RULES>
 <ON_SAVE>
   <VALIDATION>
                     <PROPERTY name="VALID" source="st_startDate"/>
                     <MESSAGE lang="*" text="Start date must be set"/>
                     <MESSAGE lang="DE" text="Startdatum muss gesetzt werden"/>
   </VALIDATION>
 </ON_SAVE>
</RULES>

Example new:

<RULES>
 <RULE>
   <VALIDATION scope="SAVE">
                    <PROPERTY name="VALID" source="st_startDate"/>
                    <MESSAGE lang="*" text="Start date must be set"/>
                    <MESSAGE lang="DE" text="Startdatum muss gesetzt werden"/>
   </VALIDATION>
 </RULE>
</RULES>

"RULE" tag

Whereas the rule definition of a template is enclosed by the <RULES>...</RULES> tags, each rule must be enclosed by an opening and a closing <RULE> tag from FirstSpirit version 5.2 on. See also page The structure of a rule.

Example old:

<RULES>
    <ON_SAVE>
        <WITH>
            <NOT>
                <PROPERTY name="EMPTY" source="st_text"/>
            </NOT>
        </WITH>
        <DO>
            <VALIDATION>
                <PROPERTY name="VALID" source="st_text"/>
                <MESSAGE lang="*" text="The editor must not be empty!"/>
                <MESSAGE lang="DE" text="Der Editor darf nicht leer sein!"/>
            </VALIDATION>
        </DO>
    </ON_SAVE>
</RULES>

Example new:

<RULES>
    <RULE>
        <WITH>
            <NOT>
                <PROPERTY name="EMPTY" source="st_text"/>
            </NOT>
        </WITH>
        <DO>
            <VALIDATION scope="SAVE">
                <PROPERTY name="VALID" source="st_text"/>
                <MESSAGE lang="*" text="The editor must not be empty!"/>
                <MESSAGE lang="DE" text="Der Editor darf nicht leer sein!"/>
            </VALIDATION>
        </DO>
    </RULE>
</RULES>

You also have the option of including the “when” parameter in the <RULE> tag with the values

• ONLOCK
• ONSAVE

See below.

Summary of changes

What is new?

The following tags and parameters are new in FirstSpirit version 5.2:

"RULE" tag

Each rule is enclosed by an opening and a closing <RULE/> tag.

<RULES>
     <RULE>
           [Rule 1]
     </RULE>
     <RULE>
           [Rule 2]
     </RULE>
</RULES> 

You also have the option of including the when attribute for each rule (see following section).

"when" attribute

By default, rules are executed whenever the editor makes an entry, i.e. every time a key is pressed. The optional when attribute in the <RULE/> tag can be used to specify that the respective rule

• should be executed once on saving: when="ONSAVE"
• should be executed once when the user switches to Edit mode: when="ONLOCK"

Example:

<RULES>
	<RULE when="ONLOCK">
...

By default (i.e., if the when attribute has not been specified), the rule is executed whenever the editor makes an entry.

See also page <RULE/> tag.

Negation of Boolean values ("NOT")

Previously, the only way to negate Boolean values from value determination (<WITH/> or <SCHEDULE/>) was to perform the negation within the value determination itself. With the release of FirstSpirit version 5.2, it can now also be performed in the <DO/> tag. This involves using the <NOT/> tag in conjunction with the following tags:

• <PROPERTY/>
• <VALIDATION/>
• <NOT/>

Examples:

With <PROPERTY/>:

<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>

In this example, the template contains three text fields (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 displayed if text field 1 is empty, and text field 3 is displayed if text field 1 is not empty.

With <VALIDATION/>:

<RULES>
   <RULE>
      <WITH>
        <PROPERTY name="EMPTY" source="st_headline"/>
      </WITH>
        <DO>
             <NOT>
              <VALIDATION scope="SAVE">
              <PROPERTY name="VALID" source="st_headline"/>
                <MESSAGE lang="*" text="The editor must not be empty!"/>
                <MESSAGE lang="DE" text="Der Editor darf nicht leer sein!"/>
              </VALIDATION>
                 </NOT>
        </DO>
   </RULE>
</RULES>

With <NOT/>:

<RULES>
       <RULE>
          <WITH>
        <PROPERTY name="EMPTY" source="st_text"/>
          </WITH>
      <DO>
        <NOT>
             <NOT>
                 <VALIDATION>
            <PROPERTY name="VALID" source="st_text"/>
            <MESSAGE lang="*" text="Nicht leer!"/>
                 </VALIDATION>
                 </NOT>
        </NOT>
          </DO>
   </RULE>
</RULES>

See also page Determining values <WITH/>.

Property "SELECT" / "DESELECT"

The properties SELECT and DESELECT can be used for manipulating the selection in option based types of input component, in fact in

• CMS_INPUT_CHECKBOX
• CMS_INPUT_COMBOBOX
• CMS_INPUT_RADIOBUTTON

Property "SIZE"

The property SIZE checks how many entries have been selected within an input component and can now be used for CMS_INPUT_LIST and CMS_INPUT_CHECKBOX. This property can be used as well with FS_CATALOG and FS_INDEX.

Operator "CONTAINS"

The comparative operator CONTAINS can be used within the Determining values area of the rule definition (or for defining a Precondition) and allows to compare the content of input components of the types

• CMS_INPUT_CHECKBOX

with

1. a textual comparative value or
2. the property of the form.

Operator "NULL" / "NOT_NULL"

Input components can contain a value or can be “empty”. If no value is stored within the input component, it can – depending on the type of input component – return:

• an empty value (z. B. CMS_INPUT_TEXT) or
• NULL (z. B. CMS_INPUT_NUMBER)

The <NULL/> tag can be used in the Determining values area of the rule definition (or for defining a Precondition) and checks if an input component contains a value or not.

See also page <NULL/>/<NOT_NULL/>.

Property "SECTION"

You can use the SECTION property to check whether a section has been selected in a FS_REFERENCE component or not.