zammad/doc/developer_manual/standards/how-to-use-forms.md

How to Use Forms

Basics

Forms in Zammad are based on FormKit and the documentation is referenced in the following paragraphs.

They are defined by the schema. The schema data describes the form containing all needed form fields, e.g. the ticket creation screen. For more information, please see the Formkit schema essentials description.

Usage of Reactivity

The forms provide reactivity to modify the form and form fields on events, e.g. user input or data manipulation.

Schema Data

In addition to the static schema, the Form component can also include a schemaData prop. Values from the data object and properties can then be referenced, and your schema will maintain the reactivity of the original data object.

To reference a value from the data object, you simply use $ followed by the property name from the data object. References can be used in the schema attrs, props, conditionals, and as children. Please have a look at the FormKit references page.

In our implementation, the current form values are always available as $values.

Example:

const schemaData = reactive({
  securityIntegration: false,
})

Example (excerpt of static schema)

{
  if: '$securityIntegration === true && $values.articleSenderType === "email-out"',
  name: 'security',
  label: __('Security'),
  type: 'security',
}

Change Fields

The changeFields is a reactive extension for the form implementation.

This is our preferred way of changing the state of fields after a user interacts with the form. This should be manipulated with the changed event of the form.

A simple use case is to mark some fields as mandatory after a user selects the value Support Request in the field Category.

Handlers

This is the most powerful way to influence the behavior of the current form's reactivity.

If you need to share code between multiple forms that relate to reactivity, you have to use form handlers.

The form handler supports two execution types:

• Initial
• FieldChange

For a working example of a handler, please have a look at the ticket signature code.