Chapter 3. Drag and Drop Apps

3.1. Creating Forms Using the Forms Builder

Overview

The Forms Builder allows you to manage existing forms and create new forms from a template.

3.1.1. Creating a Form

All forms are created from templates.

When creating a form, you have the option to create an empty form using the Blank Form template. There are also pre-populated form templates for different scenarios that may be more convenient to customize.

You can preview a template to see all its fields. Once you select a template, you can enter a form name, and an optional description.

Note

The form preview is for illustration purposes only. To submit forms or save drafts, you need to create a new forms project or associate forms with an existing project.

When the form has been created using the Create Form button, you are taken directly to the Edit Form screen to customize the form.

3.1.2. Adding Fields to a Form

Forms are created through the inclusion of fields. There are a variety of different fields that can be added, each with a different purpose. Listed below are the fields that can be added to a form, along with a brief description. Fields have a variety of different configuration settings. Depending on the field selected, different field configuration settings will be available.

Fields are split into two categories:

  • content fields — take user input (text, number, file, etc.)
  • structure fields — auxiliary fields which help you create the form layout

Fields can be added to a form by:

  • Drag & Drop — Drag the field type anywhere on the form to place the form. When dragging the field, you will see a dotted outline of where the field will be placed when finished dragging.
  • Clicking a field type — Single-clicking on a field will add the field after the currently selected field already in the form.

After fields have been added to a form, they can be repositioned by dragging them to the desired place in the form.

3.1.2.1. Structure Fields

3.1.2.1.1. Section Break

Section Breaks are used to group fields into sections. In the default template, sections are collapsible groups of fields. Sections can contain a name and description to identify the section to the form user.

Not all pages have to contain section breaks. It is possible to have a form with some pages containing section breaks and some that do not.

Note

If a page contains a section break and there are fields between a page break and section break, those fields will automatically be grouped into a section.

3.1.2.1.2. Page Break

Page Breaks are used to indicated where a new page of a form begins. Any fields after a page break will be contained in the next page of the form. Like sections, pages can contain a name and description to identify the page to the form user.

3.1.2.2. Content Fields

Content fields are fields that users will enter data into.

Each field, as described below, can contain type-specific configuration settings. However there are a number of settings that are universal to all fields.

  • Required — A required field must be submitted when completing a form.
  • Validate Immediately — This option allows the value entered into the field to be validated when the value is entered. Otherwise the field is validated when the user clicks Submit on the last page of the form.
  • Admin Only — Admin Only fields are visible only on the submission editor in the Studio. Admin Only fields will not appear in the form in the Client App. In addition, Admin Only fields cannot be the subject of any field or page rules.
  • Repeating — Repeating fields contain a configurable number of entries between Min and Max. Repeating fields cannot be the subject of field or page rules.
  • Field Code — Fields can be assigned a user-defined code that identifies the field. This must be unique within the form. This is useful for adding data to a field from external sources (for example, CSV files).
3.1.2.2.1. Text Field

A text field allows users to enter a single line of text. Valid input includes letters, numbers or special characters.

There are two validation options for text fields:

  • Length Limit — The Min or Max number of characters that must be present in the field. If left blank, no validation will be performed on the length of the text input.
  • Field Format — the format of the text field, defined as a combination of letters and numbers represented by c and n characters, respectively, or a regular expression to be matched to the field.
3.1.2.2.2. Paragraph Field

Similar to the text field, the Paragraph field also accepts all types of input, including letters, numbers, and special characters. Additionally, the Paragraph field spans across multiple lines.

There is one validation option for paragraph fields:

  • Length Limit — The Min or Max number of characters that must be present in the field. If left blank, no validation will be performed on the length of the text input.
3.1.2.2.3. Number Field

The Number field is a single line field that allows the user to enter a numeric value. Only numbers can be entered in the number field. Letters or special characters will not be accepted.

There is one validation option for number fields:

  • Min/Max Value — The range of numbers that can be entered into the field. If left blank, no validation will be performed on the size of the number input.
3.1.2.2.4. Email Field

The Email field allows the user to input an email address. Both @ and a . characters must be found. At least one character must also be entered for the domain. For example, test@example.com is valid.

3.1.2.2.5. Website Field

The Website field allows the user to enter the URL of a website.

3.1.2.2.7. Radio Buttons

The Radio Button field allows users to select a single option from a list of radio buttons.

Options can be added by adding inputs into the Options section of the field configuration tab. Pre-selected values can also be added by selecting the check box beside the added option.

3.1.2.2.8. Check boxes

The Check box component allows the user to select any, all, or none of the options from a list.

Options can be added by adding inputs into the Options section of the field configuration tab. Pre-selected values can also be added by selecting the check box beside the added option.

There is one validation option for the check boxes field:

  • Selected Options Limit — The Min and Max number of options that can be submitted.
3.1.2.2.9. Map

The Map field uses the Google Maps API to calculate and display the user’s current position. The user’s position on the map is indicated by a marker.

3.1.2.2.10. Location

The Location field lists the coordinates of the user’s location as displayed in the Map field. Co-ordinates can be displayed in either Latitude/Longitude or Eastings/Northings format.

3.1.2.2.11. File

The File field allows the form user to attach a file to a submission.

There is one validation option for the file field:

  • Max File Size — The maximum size, in kilobytes, of the file that can be uploaded using this field. If no value is entered, then the file size will not be validated.
3.1.2.2.12. Photo Capture

Allows the end user to upload an image. The user has an option to either take a photo and upload it, or to choose from a library.

There are several options available when defining a Photo Capture field:

  • Max Height — The maximum height of the photo taken, in pixels.
  • Max Width — The maximum width of the photo taken, in pixels.
  • Quality — The quality of the photo. Note: Modern smart phone cameras can take very high-resolution photos. This can increase the file size of the photo submitted.
  • Photo Source — Source of the photo can be limited to camera, library or both.
  • Photo Type — Photos can be taken as either JPEG, or PNG files.
  • Save To Photo Album — Allows any photo taken by a camera to be saved to the photo library for future use.
3.1.2.2.13. Signature Capture

This field is used to capture the user’s signature.

3.1.2.2.14. Datestamp

Allows the user to enter a date and time.

There are three options when defining a Datestamp field:

  • Date and Time — Allows the user to enter the date and time. The format of the input is configurable. The default is YYYY-MM-DD HH:mm.
  • Date Only — Allows the user to enter a date value only.
  • Time Only — Allows the user to enter a time value only.

3.2. Managing Forms Projects

3.2.1. Overview

The Forms Projects screen allows you to view any projects that are associated with forms or themes and create a new forms project.

Projects can be searched by name in addition to viewing the number of forms related to each project.

You can create a Forms Project in one of two ways:

  • Create the project from scratch.
  • Add a form to an existing project.

For more information, see the How to create a Forms Project guide.

Requirements

To manage forms projects, the user must be a member of one or more teams with the following permissions:

  • Domain — Drag & Drop Apps (View & Edit)
  • Domain — Projects (View & Edit)

3.2.2. Creating a Forms Project

You can create a new Forms project in one of two ways.

3.2.2.1. Creating a New Project

To create a new forms project, click Create New Project button, enter a name for the new project and select the Next button. The new project will contain a single forms client and Cloud App to immediately interact with the associated forms. When the new forms project is created you will be directed to configure the project with forms and a theme.

3.2.2.2. Associating with an Existing Project

Forms can be associated with any project in the Studio. To associate forms with an existing project, click Use Existing Project, select the project you wish to associate forms with, and click Next.

When the existing project is selected, you will be directed to configure the project with forms and a theme.

3.2.3. Adding Forms and Themes to a Project

The Project Forms & Themes screen allows you to associate forms and a theme with the project.

You can associate a theme by selecting a theme from the drop-down list. To preview a theme, select the theme in the Project Theme list and click one of the forms in the Forms list. This will render the form into the preview area.

To add forms to the project, click into the forms list. You will be presented with a list of available forms. Typing part of the form name will filter the list. When you have found the form, select it from the list. You will now see it in the forms associated with the project.

When you are finished adding forms, click on the Save button to update the project.

3.2.4. Configuring a Forms Project

The Advanced Config screen allows you to configure Client and Cloud Apps.

Note

Any updates to these settings will update live Client and Cloud Apps in this project.

3.2.4.1. Client Options

Client options are available to the forms Client App and affect the operation of forms on the client.

These settings provide the default values for the Client App, however app users can be allowed to change these setting by adding the device id to the Admin Users section described below.

Note

In the forms template app, the Settings section contains a Show Device Id button that will display the current device id to the app user.

3.2.4.1.1. Camera Settings

Camera setting affect the operation of the Photo Capture field. This section allows you to edit the height, width and quality of the photos taken.

Note

These settings are overridden by any height, width or quality settings set on the Photo Capture field.

3.2.4.2. Submission Settings

This section allows you to define some parameters for when apps are submitting form data:

  • Max Retries – The maximum number of times that a Client App will try to submit a form before alerting the user to a submission error.
  • Timeout – The number of seconds that will cause a submission upload to report an error if exceeded.
  • Min Sent Items To Save – A list of options the client user has when selecting the number of sent form items to keep on-device.

3.2.4.3. Client Logging

This section allows you to define some parameters of client logging. These settings are useful if there is an issue with submitting forms.

  • Logging Enabled – If this check box is checked, all Client Apps will store logs on-device.
  • Logging level – Allows you to set the level of verbosity of client logging. debug will have the most logs whereas error will only log errors on the client.
  • Log Limit – The maximum number of log entries that are permitted on the client before logs rotate.
  • Log Email – The email address the client can send logs to if required.

3.2.4.4. Admin Users

Admin users are client device IDs that are permitted to alter configuration on device.

To add a device ID to the list, click into the text box and enter the device ID.

Note

In the forms template app, the Settings section contains a Show Device Id button that will display the current device ID to the app user.

3.2.4.5. Cloud Logging

Enabling cloud logging will enable logging for any Cloud App related to this project. This is useful when there is an issue with submitting forms.

3.3. Dynamically Displaying Form Fields and Pages

3.3.1. Overview

Fields in a form can be hidden or displayed dynamically based on values of one or more other fields.

Pages can also be hidden or displayed based on a predefined set of rules. When applying rules to pages, the 'object' affected by the rule will always be a page. This means that although the subject of the rule will be a field, a page will always be affected. Rules are applied in the same way they are applied to fields.

3.3.2. Defining Rules

For example, a rule could be applied to an age field, where if the input is an age of 17 or older, a text field asking the user to list previous jobs appears. If the user is too young to have had a job, the field is hidden.

  • Subject — This is the field to which the rule is applied.
  • Comparison — The comparison determines how the subject’s value is compared to the given value. The comparisons include contains, does not contain, begins with, ends with, and others.
  • Value — This is the value that the rule will be tested against.
  • Action — The action to be taken if the condition is satisfied. The action can be either show, or hide.
  • Object — The field or page that will be shown or hidden if the condition of the rule is met.

When constructing rules, different comparisons can be selected depending on the type of field the rule is being applied to. For example, a text field and a number field will have different comparison options. When applying a rule to a text field, a rule can be constructed based on whether an input begins with a particular letter, contains certain letters, or ends in a particular letter, whereas when applying a rule to a number field, rules are constructed based on whether or not input to a particular field is greater than, less than, or equal to a particular value.

Different types of fields have different rule comparisons available for selection.

  • textfield — is, is not, contains, does not contain, begins with, ends with
  • paragraph — is, is not, contains, does not contain, begins with, ends with
  • number — is greater than, is less than, is equal to
  • email — is, is not, contains, does not contain, begins with, ends with
  • web — is, is not, contains, does not contain, begins with, ends with
  • dropdown — is, is not, contains, does not contain, begins with, ends with
  • radio buttons — is, is not, contains, does not contain, begins with, ends with
  • checkbox — is, is not
  • date stamp — is at, is before, is after
Note

Map, Photo capture, Signature capture, File upload, and Location fields can not have rules applied to them, however they can be displayed or hidden based on input to other fields.

3.4. Using Data Sources

3.4.1. Overview

To make your forms applications more dynamic, you can set certain field types in Forms to have values loaded dynamically. The values can be loaded from a database, from an external web service, from a back-end system, or any other source accessible through an MBaaS service.

Data sources are the mechanism which binds a form field to an MBaaS service which provides the values.

The following field types can have values loaded from a data source:

  • Dropdown
  • Check boxes
  • Radio Buttons
  • Read Only

For a step-by-step guide to defining and using a data source, follow the guide Dynamically Populating Form Fields From an MBaaS Service.

3.4.2. How it works

The data source acts as a binding layer between the form field, and the MBaaS service endpoint. When a form definition is accessed, the data for fields backed by a data source are not retrieved directly from the MBaaS service. Instead, the data source always returns a version of the data cached in the environment.

For example, when a data source is invoked from a form deployed in a Dev environment, the associated MBaaS service must also be deployed in a Dev environment, and the data is cached only for the Dev environment.

3.4.2.1. Refresh Period

The cached data from the MBaaS service is refreshed periodically on the cloud side, according to the configured period – from as little as one minute, up to seven days.

If a data source refresh fails for any reason, a back-off algorithm will progressively increase the refresh period to a maximum of seven days. Any successful update to the data source in that time, either from an automatic or manual refresh, will allow the data source to resume the configured period.

3.4.3. Requirements

  • The MBaaS service used as a data source must use fh-mbaas-api version 5.8.1 or higher
  • The Cloud App associated with a form, which uses a data source, must use fh-mbaas-api version 5.0.0 or higher

3.4.3.1. JSON Format

The HTTP endpoint of the MBaaS service used as a data source must return a JSON response in the following format:

  • For Dropdown, Check boxes, and Radio Buttons field types:

    A list of objects with three keys:

    • key – (Optional) internal identifier, used as the name attribute in the HTML form field
    • value – the user-friendly display text
    • selected – (Optional) used to preselect a single option in case of Radio Buttons and Dropdown, or multiple options for Check boxes
    [
      {
        "value": "January",
        "selected": "true"
      },
      {
        "key": "02",
        "value": "February"
      },
      {
        "value": "March"
      },
      ...
    ]
    Note

    There is no limit on the number of objects returned by the service, and all returned objects get rendered in the form as options. Using too many options can make the form difficult to navigate.

  • For Read Only text field type:

    [
      {
        "value": "<b>Note:</b> You can use <i>HTML</i> in the Read Only field."
      }
    ]

    A subset of HTML is supported in the value and will be rendered in the form.

    If the list contains more than one object, the values of the value fields from all objects are separated by newlines and concatenated.

3.4.3.2. MBaaS Service Endpoint

You can use any MBaaS service as a data source, as long as it uses the required version of fh-mbaas-api and the output of the HTTP endpoint conforms to the required format, as described above.

Three MBaaS service templates are provided by default, which demonstrate common use cases:

  • Static Data Source – serves data statically defined in a JSON file in the MBaaS service
  • MongoDB Data Source – serves data stored in the built-in MongoDB database, loaded through $fh.db
  • Internet Data Source – serves data parsed from an external website

3.5. Themes

Overview

Themes are used to customise the appearance of a form. Form Editors can create and manage themes, as well as associating them with forms to personalize form appearance. Elements of a theme that can be customised include the theme logo, background colours, typography, and border settings.

3.5.1. Creating a Theme

When creating a theme, select a theme from a list of templates.

When a theme template is selected, a preview of the theme is displayed. Once a template has been selected, the user then enters a theme name, and description (optional). The theme can now be edited to customise the appearance of the form.

3.5.2. Editing Themes

3.5.2.2. Backgrounds

In the Background Color section, you can change background colours for different parts of the theme. The colour can be set by clicking on the coloured square beside the section title, and then selecting a colour from the picker. The update will take place once the colour picker has been closed.

3.5.2.3. Typography

The Typography section allows for the customization of font size, type, and text decorations. The colour of a selected field can also be changed by clicking on the coloured square beside the section title. Clicking the coloured square displays a colour picker.

3.5.2.4. Borders

Customizations can be made to the border sections of a theme. You can make customizations based on colour, border type and border width.

3.5.2.5. Spacing

Certain fields have options for customizing the margin and padding between fields.

Note

To get a preview of how changes made to the various sections affect the theme, select a form from the drop-down menu at the bottom of the preview area.

3.6. Viewing Submissions

3.6.1. Overview

The Submissions page is used to view forms that have been submitted either via Studio or via a Client App. Submissions can be viewed on a per Form basis, per Project basis, or by Recent Submissions.

Form Submissions can be viewed using the Submissions Viewer, and edited by the Submissions Editor.

Submissions can be exported in Comma Separated Value (CSV) format using the Export Submissions button. When exporting Submissions, the headers for the exported fields can be

  • Field Name — The name of the field.
  • Field Code — The Field Code assigned to the field. If no Field Code has been assigned to the field, the Field Name will be used instead.
Note

Field Names and Field Codes are assigned to a Field within a Form using the Form Builder.

The Recent Submissions page also shows a list of forms that have been recently submitted. A variety of submission information is provided along with the Form and Project name. This includes the current environment the Project is deployed on, the date/time the submission was received, and the input to the form fields.

Clicking on a submission will display the details of the submission.

3.6.2. Sorting Submissions

3.6.2.1. Sorting Submissions By Form

The By Form Submissions page allows the user to view Submissions on a per form basis. A user can select a form from the dropdown list, and then view information regarding all the individual submissions relating to that particular form.

After selecting a submission from the list, extra Submission Information is displayed. In the image below, a preview of the form is displayed along with additional Submission Information.

The Form Submission section shows a preview of the form that was submitted, along with the values that were entered for each field.

The Submission Information section displays more technical information such as what App ID, Device ID, and IP address are associated with the Submission.

Note

If a Submissions Editor makes any modification to a Form Submission this is recorded in the 'Date time edited' and 'Edited by' fields.

3.6.2.2. Sorting Submissions By Project

The Per Project Submissions page allows users to view submissions on a per Project basis. First, a Project is selected from the list. Then, a Form is selected from the list of Forms associated with that Project.

3.6.2.3. Filtering Submissions

The By Form and Per Project Submissions page contain a search field. The following fields will be compared to the value when the search button is clicked.

  • The ID of the submission.
  • The name of the form the submission was made against.
  • The ID of the form the submission was made against.
  • ID of the device that made the submission.
  • The IP address the submission was made from.

3.6.3. Searching Submissions

Advanced submission search allows for searching form submissions with customized criteria. Users can build up clauses filtering the values of fields to find the relevant submissions.

3.6.3.1. Creating Search Criteria

To search submissions for a form:

  1. Select a form from the list of available forms. This will populate the Single Fields and Repeating Fields boxes with a list of fields matching the type.
  2. Add a clause by clicking the + icon and remove clauses by clicking the - icon.
  3. Populate a clause by selecting the field, selecting the clause type (for example, is, is not, etc.) and enter the value to compare.
  4. When all clauses have been created, click Search to find the list of submissions that match the created clauses.
Note

If the field is repeating, each entry of the repeating field will be compared to the clause.

Note

Submissions matching the created search criteria can be exported using the Export Submissions button.

3.6.4. Viewing Submission Details

All non-admin fields submitted by the user are displayed along with any images and files the user uploaded.

In addition, Admin Only fields are displayed for adding additional information to the submission.

Images are displayed inline. To save the image to your computer:

  1. Right-click on the image.
  2. Select Save Image As.
  3. Select a location to save the image.

Files can be opened by clicking on the link in each file entry.

To save the file to your computer:

  1. Right-click on the image.
  2. Select Save Link As…​.
  3. Select a location to save the file.

The buttons at the bottom of the screen allow for 4 functions

  • Download PDF: Allows for converting the submission to a PDF document. When the conversion is complete, this process triggers a download in the browser.
  • Print Submission: Allows for converting the document to a printable format. When complete, this process triggers the print function in the browser.
  • Delete Submission: The user is prompted for a confirmation to delete the submission.
  • Edit Submission: Allows for editing a submission to add additional data.
Caution

Deleting a submission is irreversible. All content related to the submission is deleted, including files.

3.6.5. Editing a Submission

Editing a submission can be performed by entering data into the field (for example, text, number).

Admin fields are indicated using the (Admin) icon.

If a field is repeating, additional values can be added to the field with the Add Input button.

The contents of a file or a photo field can be changed by clicking Choose File below the file or a photo. The file or the photo can then be added from your local computer. When the new file has been chosen, a message will appear showing the file is queued for upload.

To save any changes made to the submission, click the Update Submission button. This will update the submission data in addition to uploading any files selected.

Clicking Cancel will abort any changes entered into the submission.

3.6.6. Receiving Notifications on Every Submission

The Notifications section allows users to manage email addresses that will receive an automated email once a submission is received.

Here, email addresses can be added to and removed from a notification list. Any email address that has been added to the list will receive an email whenever a copy of that Form is submitted.