Form

This component provides a form that will collect information from the user. A simple example is collecting
customer feedback with contact details and comments.

The data is saved into Umajin Cloud, and can be retrieved from as a CSV file download.

Creating a new form

When you insert the ‘Simple Form Component’ it will be automatically populated with a group of working
components, making up an functional example: a contact form.

The example shows the way that submission and validation can work together.

It will have Text labels, Text Entry fields, a Cancel Button and a Submit Button. There will also be some
red error Text Labels that will display (in play mode) if the user’s text entry is not validated.

You can delete or change any of these components if you don’t need them.

After inserting the form, we can set up data collection using the Umajin Cloud. To open the Umajin Cloud,
click on the Form component to open the Properties Inspector then click on the diagonal right facing arrow
beside the Form ID field.

This will open up a page in your web browser. On the page add a Simple Form feed by pressing the + button.

Type in a form name (we’re using Retail Feedback), and press the save button. A simple Form ID will be
allocated.

Next we need to go back to the Umajin Editor to bind the feed we just made to our Simple Form component. In
the Properties Inspector for our Simple Form component, under the Form ID property, click on the folder or
the box to open the feed picker and select the ‘Retail Feedback’ feed we just created.

The Simple Form and the ‘Retail Feedback’ feed we created in the Umajin Cloud are now attached together.
When the user enters information into the text entry fields and presses the submit button, the app will
first check if all the information is valid (such as email) and all required fields are filled in.

This data can be retrieved by going back to our web browser with the Umajin Cloud page and clicking the
‘download’ button. If you closed the page, you can reopen it quickly by clicking on the arrow under Form ID
in the Simple Form component’s Property Inspector.

The data is downloaded as CSV file. These are commonly viewed in Microsoft Excel and Google Spreadsheets.
They can also be opened as a text file with a program like notepad.

The column headers are created from the Form field name property for each component within the form. The
data is grouped under the appropriate headers. Try changing the field name and see how the data changes.

Form validation

In the ‘Properties Inspector’ for each of the ‘Text Entry Components’, under the heading ‘Form Validation’
there is a property called “Validation type”. This can be set to any of the options in the drop down and if
the text entered into this field does not match the type selected, then it is considered invalid and the
form submit will not send.

An advanced option is to select the “Custom regex” option from the dropdown. You can enter in a regex text
into the “Validation regex” property below it and it will use this to validate the text. (See below for more
on regex.)

There is also a “Required Field” checkbox option. If this is checked, then even if no validation type is
selected, it will still fail to send if that field is empty.

If you don’t want one of your text entry components to send its contents when the form is submitted and for
the form to not check if it is valid, then you can uncheck the “Enabled form submit” checkbox.

Alternatively if you are using JavaScript for complex form submission you can turn this on for components
that aren’t normally used on a form. For Javascript custom components, the from “value” can be set with
setData(component, “value”).

If you want to do much more complicated validation on your text entry component then you can use JavaScript
in the text entry component’s “On Before Validation” event. Doing the validation here allows the result of
your custom validation to trigger text entry component’s “On Fail Validation” and “On Pass Validation” based
on the results of your script. You just need to write true or false to the text entry component’s
“passed_form_validation” property.

The error labels

The 3 default error Text Labels have been setup to start hidden when the page plays/shows. You can see this
if you go to play mode. Each one is paired with a text entry box.

1. Text component renamed as ‘First Name Valid’
2. Text component renamed as ‘Email Valid’
3. Text component renamed as ‘Comment Valid

If you type something invalid into its text entry and tab to the next one then the label will show, alerting
the user to the error. If you go back and enter something valid and tab away then the label will hide again.
This system is done in each of the Text Entry Components in their Property Inspector ‘Actions’ tab. The “On
Fail Validation” and “On Pass Validation” events show and hide the labels. The labels are made to start
hidden using the Form’s event “On Page Show” to hide all three error labels.

Events on the Form that trigger Actions

The Form has the event, “On press”, which can have actions attributed to it.

The Form has the “On Before Submit” event which happens when you press the submit button and is meant to be
used to add in your own form validation checking with JavaScript. Each item in the Form that has “Enabled
form submit” will have a hidden property called “passed_form_validation” set based on its selected form
validation. In JavaScript you can inspect this property, inspect the text and perform your own tests and
then set the “passed_form_validation” to false if you want it to fail and true if you want it to succeed.

Next the Form checks each of its fields that have Enabled form submit on, to make sure that the
“passed_form_validation” property is true. If any of these items is false then the “On Validation Fail”
event will occur. The default setup shows a popup with a simple message to the user to let them know the
form failed validation.

If the Form passes validation then it will try to send its data to the dashboard. If for some reason, such
as no internet connection, the Form fails to send then the “On Send Fail” event will trigger. The default
setup again shows a popup to let the user know. If the Form sends correctly then we get an “On Send Success”
event. The default setup uses this to reset the Form and show a popup to inform the user.

The Form has the event “On Page Show” which is the same as the “On Before Page Shows” event that pages have.
Forms often have some initial setup we want to do, so this allows us to group it all under the form rather
than adding it to the Page event.

1. ‘On Press’ – an action of your choice can be added
2. ‘On Before Submit’ – an action of your choice can be added
3. ‘On Validation Fail’ will show a popup with a message you can customize
4. ‘On Send Success’ will show a popup with a message you can customize, reset to a selected page, and
   set component visibility to hide/show or toggle as long as name, email and comment are valid entries
5. ‘On Send Fail’ will show a popup with a message you can customize
6. ‘On Page Show’ will set component visibility to hide/show or toggle as long as name, email and
   comment are valid entries

Tutorial on how to customize a simple Form

Tutorial on
customizing a simple Form

Default Components that populate the Form Component

Custom regex validation

Here are some examples of regex. You can write your own or search on the internet for more.

Email

Number

Phone