All Collections
Automation
Forms
'Form' action
'Form' action

Use Forms to gather information from users in various scenarios and use it in further actions along with the record data

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

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

  • HTML

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 an 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 template 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.
      ​

      • To conserve storage space, we recommend that you specify the target max size for the image — and Mapsly will auto-resize the image being uploaded to fit into this rectangle while preserving the original aspect ratio.
        ​

      • Image source: From camera/gallery and Drawing.
        ​
        When Drawing is selected, when a user opens a form with such a field, turning the mobile device into 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.
        ​

    • Audio and Video: allows uploading audio and video of various formats.
      ​

      • For audio and video files, Mapsly can generate a transcription and, optionally, analyze it using the OpenAI GPT 4 API based on your custom prompt.
        ​

      • For videos — to conserve storage space — we recommend that you specify the target max size of the video — and Mapsly will auto-resize the video being uploaded to fit into this rectangle while preserving the original aspect ratio.
        ​

  • Do not disable action buttons while file(s) are uploading box. When unchecked, Mapsly will automatically disable the Form's action buttons when user started uploading a file and re-enable them when the uploading of all files into this Files field has been completed.
    ​
    When this box is checked, Mapsly will NOT disable the action buttons when a file uploading starts, so the user may submit the form while a file has not yet been fully uploaded, and to programmatically determine if an upload is in progress, check the form.uploadInProgress boolean key.

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

HTML form field

An HTML field allows you to render custom HTML content, like reports or summaries of complex data.

NOTE: Currently, HTML fields can only be added to your forms by a Mapsly solution engineer (their services are included in your Mapsly subscription at no extra charge), so feel free to contact us in chat or at [email protected] to ask to add HTML content to your forms.

HTML content is rendered from the HTML field's Twig content field in an iframe inside the Form.

To insert images into the HTML field's Twig content, use GetFileURL() function which will generate a temporary direct link to your Mapsly image file.

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.

Recipient's hand-drawn signature on courier's device

Your recipients may sign their deliveries using their delivery agent's mobile device — the courier will need to simply rorate their phone or tablet to the landscape mode (or press Draw) — and a drawing board will automatically open to allow the recipient to draw their signature.

To implement this, follow these steps:

  • add a Files field to your delivery Form (it may have any name, for example Signature),

  • check the Drawing box and uncheck From camera/gallery,

  • to make the signature optional, set the Min allowed number of files to 0; to make it compulsory — set it to 1;

  • set Max allowed number of files to 1.

Setting up conditional visibility of form fields

You may set up conditional visibility for some of your form fields in order to show or hide those fields depending on the value of another form field. Below we will explore an example of how this can be done and why this can be useful.

In this example, we have a Picklist form field that has some options, including the "Other" option:

We also have the "Other" text field and want it to show up only if the Picklist field value is "Other." You can achieve this by setting up a conditional visibility:

In the condition, you need to use the API name of your form field, for example:

{{ Picklist == "Other" }}
Did this answer your question?