Rules – Creating dynamic forms

A template developer can defined rules within the (form) template that affect certain elements or properties of the form and in so doing create a “dynamic form”. Rules can be used wherever FirstSpirit forms are used and indeed in both SiteArchitect and in ContentCreator, e.g., in:

• Forms for the page store and content store
• Metadata forms
• Forms for workflows
• Forms for scripts
• Forms for link templates

Dynamic forms are used to:

• Detect invalid states in the content of forms. It is possible to check, for example, whether a date is in the future (e.g., deadlines that have not yet arrived) or the past (e.g, press releases) based on the requirement of the corresponding input component
• Hide individual form fields in a form under certain conditions. This makes it possible, for example, to prevent certain user groups from displaying and editing content or to only allow specific fields to be edited in certain stores
• Establish logical relationships between form elements which automatically generate changes in a dependent field. Selecting one of two suppliers in a checkbox, for example, can affect a dependent combo box which will only list certain products based on the supplier selected

The rules on the corresponding form element can be analyzed at various stages of the editorial work process:

• directly during editorial work (with every input)
• when saving or
• when switching to edit mode or creating a new element

(See also <RULE/> tag.)

A rule violation (<VALIDATION/> tag) is displayed in a uniform manner for all elements. Of course, the display is clearly different from the usual layout of the workspace so that incorrect inputs are obvious. As well as color-coding dependent on the underlying restriction level, the display also includes text in the relevant language explaining why the state is invalid. The creator of the dynamic form (i.e., the template developer) can then decide how to proceed with the editing of elements in this state (whether they are to be taken into account during a generation run, for example).

Note: You can use the option “Validate language” within the properties of the desired project in FirstSpirit ServerManager in the “Languages” area to deactivate the validation for single languages. See also Languages (→Documentation for Administrators).

Supplements to this document

Examples

• Example project for dynamic forms (Version 2024.12) (project with many examples of rule definitions)
• ValueService example (Version 0.1) (example module)

FirstSpirit API

Access API documentation:

• Interface SaveOperation
  This interface can be used to save store elements and datasets programmatically. Saving an element or dataset may be carried out even if the object to be saved contains erroneous or invalid data, e.g. due to a rule infraction, by using the method setValidationEnabled(false).
• Interface Language
  You can use the methods setIgnoreValidation() to define if validation should be used for a language or not.
• Interface ValidationAgent
  This interface provides access to functions to validate the data in the form against the rules defined in it. This validity status is needed in workflows, for example, to check whether an element can be released.

Restrictions

Validation of referenced datasets in FS_INDEX

For input components that reference and display datasets, general validation of all internal objects is not always desirable either from an editorial point of view or for performance reasons.

For validation of an FS_INDEX input component, the following applies:

• Errors caused by rule violations in referenced datasets are no longer taken into account in the input if the corresponding subform is not visible However, a rule violation in a referenced dataset will not prevent the entire form from being saved or released. This procedure only affects associated datasets.