Form builder

Learn how to use the Form builder to create forms and add actions to their event handlers

Sergey Shurygin avatar
Written by Sergey Shurygin
Updated over a week ago

This article covers specifically the Form builder tool. The concept of forms and how their fields and event handlers work are covered in detail in the Form action article.

The Form builder allows you to configure your Form's fields and buttons and add condition/actions block(s) to their event handlers:

  • For a record in (optional): this read-only field shows the object that was selected when the Form was created.

    When you select an particular object when creating the form, this object will only be used to show fields in the Insert field function of the Twig template editor.

  • Form caption: text that will appear in the caption of the form.

  • Fields: fields that will be shown on the form including buttons. Click the + button to add a field.

    Note. As mentioned in the 'Form' action article, here you may also add non-action buttons that by default will not close the form (although you can close the Form in a non-action button's handler by setting the closeForm key to true).

  • Action buttons: here you may add buttons that will appear at the bottom of the form and will normally execute actions and close the Form.

    Note. As mentioned in the 'Form' action article, when necessary - for example in case your custom validation detected a user error in the form data - you may prevent the Form from closing in the action button's OnClick handler by setting the closeForm key to false).

Field properties

The common properties for all field type are:

  • Label: the field name visible to the user on the form.

  • API name: the key (JSON-object name) under which the field's properties will be available to form event handlers in the form object in the Context.

  • Hidden: when checked, this field will created when the form opens but will be invisible by default, which is useful when creating dynamic forms with fields that are shown or hidden using Update form actions, in response to user actions on the form.

A few additional properties that common for all fields except buttons are:

  • Description (optional): a smaller text that appears under the field's label. Useful to add instructions for filling in the field.

  • Default value (optional): you may set a value that will appear in the field when the form opens.

Picklist properties

A picklist field has the following unique properties:

  • Multiple: defines whether the picklist is single- or multi-choice:

    • when unchecked, the user will be able to select only one item from the picklist, and the field's value property will contain the item's value property.

      In the example above, if the user selects Email from the picklist, form.fields.followup.value will contain email.

    • when checked, the user will be able to select multiple items from the list, and - regardless of how many items the user selected - the value property will contain a JSON-array with the list of the selected items' values.

      For example, if the user selects only Email from the picklist, form.fields.followup.value will contain [ "email" ]; and if the user selects Email and Call, form.fields.followup.value will contain [ "email", "call" ].

      Note. Use Twig filter join to format values of this JSON-array as a list of values with the required separator. For example, form.fields.followup.value|join(',') will produce email,call

  • Picklist items can be entered as fixed label/value pairs, where label will be visible to the user in the picklist and value will be passed to event handlers if the user selects this item, or as a Twig template that produces a valid JSON-array of objects each containing the label and the value of a picklist item:
    [ {"label":"Email","value":"email"},{"label":"Call","value":"call"},{"label":"","value":"visit"} ]

Event handlers

Fields of several types and execute condition/actions block(s):

  • a form button can execute actions when it is clicked;

  • a picklist, checkbox or date (date/time) field can execute actions when the user chances its current value (selects another item in a picklist or clears selection, checks/unchecks a checkbox or selects another date/time).

You may add condition/actions block(s) in the field's properties:

Note. As covered in detail in the Context & Sessions article, each event that execute condition/action block(s) creates a new execution session but within the same Context, so as the user triggers more and more events, data accumulates in the Context and can be used in subsequent executions of event handlers.

Learn more about form event handlers in the Form action article.

Did this answer your question?