<RULE/> Defining rule constraints and a rule execution time

Within a rule definition (<RULES>...</RULES>), several independent rules can be defined for a form. Each rule is defined within a <RULE/> tag and must always contain at least one value determination and one handling instruction.

By default, rules are executed whenever the editor makes an entry, i.e., presses a key. If a rule is to be executed less often than this, the when attribute can be set:

"when" attribute

The optional when attribute can be used to specify that the respective rule:

• will be executed once on saving: when="ONSAVE"
• will be executed once when the user switches to Edit mode or creates elements (page, section, dataset): when="ONLOCK"

Example:

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

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

ONSAVE: Rule checked on saving

If when="ONSAVE" is defined, the rule is checked (once) when the element is saved, i.e.,

• In SiteArchitect, it is checked when the user selects:
  • The “Save” icon on the horizontal tool bar (for “for temporary saving”)
  • The keyboard shortcut Ctrl+S (“for temporary saving”)
  • The “Switch to View mode” icon on the horizontal tool bar (“for final saving”)
  • The keyboard shortcut Ctrl+E (“for final saving”)
  • The “Edit mode on/off” entry from the context menu (“for final saving”)
• In ContentCreator, it is checked when the user selects the
  • The “Save” button

This configuration is recommended, for example, if the rule concerned is likely to be violated as soon as a new element is created or as soon as the user switches to Edit mode.

The use of ONSAVE is primarily intended for a combination with handling instructions (<DO/>) tag) without <VALIDATION/>. This is because when ONSAVE is combined with <VALIDATION/>, it is important to remember that due to the once-only check, a rule violation continues to be displayed even if the editor makes a correction which results in the rule no longer being violated.
Combinations involving INFO or RELEASE with ONSAVE should also be avoided

Example:

<RULE when="ONSAVE"> 
      <IF> 
             <PROPERTY name="EMPTY" source="st_text"/> 
      </IF> 
      <WITH> 
             <TEXT>Noch keine Eingabe</TEXT> 
      </WITH> 
      <DO> 
             <PROPERTY name="VALUE" source="st_text"/> 
      </DO> 
</RULE>

Canceling the display of a rule violation: If, in spite of this, ONSAVE is used with <VALIDATION/>, the display of a rule violation can be canceled by specifying the rule twice – once for a valid state and once for an invalid state, for example:

<RULES>
    <RULE when="ONSAVE">
        <WITH>
            <NOT>
                <PROPERTY name="EMPTY" source="st_text"/>
            </NOT>
        </WITH>
        <DO>
            <VALIDATION scope="save">
                <PROPERTY name="VALID" source="st_text"/>
                <MESSAGE lang="*" text="Please enter text here"/>
                <MESSAGE lang="DE" text="Bitte geben Sie einen Text ein"/>
            </VALIDATION>
        </DO>
    </RULE>
    <!-- Reset -->
    <RULE>
        <IF>
            <NOT>
                <PROPERTY name="VALID" source="st_text"/>
            </NOT>
        </IF>
        <WITH>
            <NOT>
                <PROPERTY name="EMPTY" source="st_text"/>
            </NOT>
        </WITH>
        <DO>
            <VALIDATION scope="save">
                <PROPERTY name="VALID" source="st_text"/>
                <MESSAGE lang="*" text="Please enter text here"/>
                <MESSAGE lang="DE" text="Bitte geben Sie einen Text ein"/>
            </VALIDATION>
        </DO>
    </RULE>
</RULES>

In this example, a check is being made to ascertain if the text input component “st_text” is empty. If it is, the message “Please enter a text here” is displayed and the component cannot be saved. The message does not disappear and the component cannot be saved until text is entered (and “st_text” is thus no longer empty).

Note: Rules with the ONSAVE execution time cannot be tested in the form preview of the template concerned (integrated preview, “Form”) tab.

ONLOCK: Rule checked when user switches to Edit mode

If the rule is to be checked as soon as the user switches to Edit mode or creates a new element, when="ONLOCK" can be used. Once the rule has been configured as appropriate for the template type concerned, it is executed as follows:

• In SiteArchitect when (for example) the following actions are performed:
  • When the user selects the “Switch to Edit mode” icon on the horizontal tool bar
  • When the user selects the keyboard shortcut Ctrl+E (if the element is in View mode)
  • When the user selects the “Edit mode on/off context menu entry” (if the element is in View mode)
  • When the user creates new pages (e.g., using the “New – Insert new page context menu entry”)
  • When the user creates new sections (e.g., using the “New – Insert section” context menu entry)
  • When the user creates new datasets in data sources (e.g., using the “New – Create dataset” context menu entry) or creates input components (e.g., in FS_DATASET)
• In ContentCreator when (for example) the following actions are performed:
  • When the user selects “Edit” icons
  • When the user creates new sections
  • When the user creates new datasets

This means that the rule is executed before the element is even edited. In this way, it is possible to pre-assign values to input components, for example. The value is displayed in the component when the user switches to Edit mode or creates a new object, but it is only actually saved in the component when the user performs a save operation.

In the example below, a date component (“st_endDate”) is populated when the user switches to Edit mode by taking a date value from another date component (“st_startDate”) and adding on two weeks:

<RULES>
    <RULE when="ONLOCK">
        <WITH>
            <ADD value="2 weeks">
                <PROPERTY name="VALUE" source="st_startDate"/>
            </ADD>
        </WITH>
        <DO>
            <PROPERTY name="VALUE" source="st_endDate"/>
        </DO>
    </RULE>
</RULES>

The <VALIDATION/> tag cannot be used in conjunction with when="ONLOCK".

Note: Rules with the ONLOCK execution time cannot be tested in the form preview of the template concerned (integrated preview, “Form” tab).