This article covers the concept of forms and how everything related to forms work. The Form builder tool is described in this article.

Concept

A Form is an action that can be added to a Button's condition/actions blocks that brings up a form with fields configured by the Mapsly administrator using the Form builder, to gather data from a user and execute further actions.

If the Button that brought up the Form was clicked for certain record(s), the Form will have access to these records through the Context as well.

To use data entered into a Form, add actions to form event handler.

IMPORTANT NOTE: form data cannot be used in actions of the Button that brought up the Form because that Button's actions continue to execute after the Form is brought up and that execution session completes while the Form is still open. You can use data from the form fields only in the form event handlers. Learn more about execution sessions and how they work with forms.

Form structure: body and action buttons

A Form has a body and the line of action buttons at the bottom.

You may add any available fields to the Form's body.

In the line of action button, there will always be a standard Cancel button that closes the Form without performing any actions (you may not execute actions when the Cancel button is clicked), and you may add more actions buttons to execute actions that use the form data, for example a Check In button that creates a check-in record with the form's data.

Action buttons VS non-action buttons

You may add a button both to the form's body and to the line of actions buttons, and add actions to their OnClick event handler - these actions will be executed when the button is clicked.

Actions buttons - those you place in the line of actions buttons - will be arranged horizontally to the right of the Cancel button.

By default, pressing an action button will close the Form when the execution of actions in its OnClick event handler completes. At the same time, by default, when a button added to the form's body ("non-action button") is clicked, the form will not close when its OnClick handler's execution completes.

Use form.close Context key to close Form or prevent it from closing at runtime

You may override the behavior of buttons and close the Form when a non-action button is clicked, or - on the contrary - prevent the Form closing when an action button is clicked (except for Cancel, which will always close the Form) by setting the form.close key to true to close the Form, or to false to leave it open in any form event handler. Or may do it in any of the handler's action or a Code action:

Available form elements and their properties

You may add the following types of fields to a Form's body:

  • Label (static text)

  • Text

  • Number

  • Date or Date/time

  • Picklist, single- or multi-choice

  • Checkbox

  • Button

  • File

All fields have a visible name and the API name that you may use in the event handlers to access fields' data.

All fields except buttons also have optional description and the current value, both of which can be set to particular values when the Form is designed, or be defined with Twig templates that will be resolved when the Form is loaded.

A Picklist field also has a list of picklist items in its properties, which can also be either set to fixed values when the Form is designed or be defined by a Twig templated that will be resolved when the Form is loaded.

A File field also has the following additional parameters:

  • Minimum and maximum number of files: how many files a user must upload. If the minimum number is 0, a user will be allowed to not upload any files.

  • Allowed file types (any combination can be selected):

    • Document: allows uploading files of any type.

    • Image: allows uploading JPEG, HEIC/HEIF, PNG, GIF (non-animated), BMP, TIFF images. To conserve storage space, during upload all images are converted to JPEG.

      • Optionally, to conserve storage space you can also specify the target max size of the image — and Mapsly will auto-resize the image being uploaded to fit into this rectangle.

      • [Coming soon] Allowed image source: From camera, From gallery and Drawing.

        This setting is useful to force a user to take a new photo using their camera directly in Mapsly as opposed to uploading an existing image taken earlier.

        When Drawing is selected, when a user opens a form with such a field, turning the mobile device into the landscape mode automatically activates the Drawing board mode.

        A Drawing-type File field is also useful as a signature field used in check-in forms — to allow the recipient to sign the delivery on the courier's mobile device.

    • [Cooming soon] Video

  • Do not disable action buttons while file(s) are uploading box.

See the Working with files section below to learn more about uploading, viewing and accessing files in Mapsly.

Form events, their handlers and accessing the Form's data

Supported form events: OnClick and OnChange

Two event types of form events are supported:

  • when a button is clicked ("OnClick"),

  • when a selection changes in a field ("OnChange").

OnClick events are supported only for buttons.

OnChange events are supported only for Date, Picklists and Checkboxes (but not for Text and Number fields).

A form event handler is executed in a new session. Every time - a new session.

As described in detail in the article about Contexts and Sessions, the execution session of the Button that brought up the Form continues to execute after the Form opens and completes without waiting for user's actions on the Form. And each time a form event handler is executed, Mapsly spawns a new execution session that use the same Context that was created when the Button was clicked.

All these sessions will appear as a separate sessions in the Execution log.

For example, if a user clicked a Button, then twice changed the value of a picklist with the OnChange handler and then pressed the Check In form button, you will see 4 separate sessions in the Execution log.

Accessing form data in event handlers

When a form event happens for which the handler contains condition/actions block(s), Mapsly saves the current state of the form and its fields including their current values under the form object in the Form action's context with the fields' properties stored in keys with their respective API names:

In the example above, the current value of the picklist field with the API name followup can be accessed as

form.fields.followup.value; and the current Notes - the value of the Text field with the API name notes - can be accessed as

form.fields.notes.value.

In case of the OnChange event, a form field's oldValue will contain the previous value while the value key will contain the new value. In the example above, the user selected the call item in the picklist field; ealier, no item was selected in the picklist (oldValue is null).

Also, in case of the OnChange event, the new and the old values of the field that was changed are saved in oldValue and newValue keys in the Forms' context:

So, for example, in the followup's OnChange event you can access:

  • the new value as newValue instead of form.fields.followup.value;

  • and the old value as oldValue instead of form.fields.followup.oldValue.

Use Update form action to updating form fields in event handlers

You can show or hide form fields and change their current value, as well as a picklist's items, by calling an Update form action in form event handlers.

If necessary, the same Update form action can be used with different forms as long as it all the field API names if references are present in all those forms.

Did this answer your question?