Start page / Template development / Rules / Time of execution ONSAVE / ONLOCK

<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>
Important 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).

© 2005 - 2022 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2023.1 | Data privacy