Form Component – Simple Form

This component provides a simple contact form that will collect customer contact details and comments. The data is fed back into a simple form you create in the Cloud Services/Dashboard.

Creating a new form:

When you insert the ‘Simple Form Component’ it will be automatically populated with a group of working components. This gives you a simple functional form. It will have Titles for information you require, 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 users text entry is not validated. The next step is to add a form to collect your data in the CloudServices/Dashboard for this app. You need to go to Cloud Services using the top File menu or in the Properties Inspector for the Form Component, use the diagonal right facing arrow alongside Form ID.

There you will add a Simple Form, name it, save it, and then a Form ID will be allocated.

Under the Form ID heading in the Properties Inspector for this Simple Form, click the folder icon which will show all the forms you have already created and in this example we have selected ‘Retail Feedback’.

 

 

 

 

 

 

 

 

 

 

When a user types into the text entry fields and presses the submit button the app will send the data to the dashboard form 223 that we added. If the user fails to fill in a required panel or types in incorrect information, when the ”Submit’ button is pressed the user receives the message to fill in the panel correctly. If all the information is correct, on ‘Submit’, a success message is sent. The cancel button navigates back to the last page you were on.

The data can be retrieved from the Cloud Services/Dashboard as a CSV file. It can be saved or printed out as a spreadsheet in excel.

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 dropdown 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.

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 boxes 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 Page Show” which is the same as the “On Before Page Loads” 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.

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.

Components within the Simple Form Component

Form 1-In the Properties Inspector under Properties you need to associate the Form with the Form ID of a form that you have already created in the App Dashboard. Use the folder icon to select the name of the Form you want to use.
In the Actions panel the Form component has 6 events that will trigger actions that you can customize:

  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

Contact Title Text Component with all the normal Text component properties. Heading for Form.
First Name Text Component with all the normal Text component properties. It displays a caption for the Form.
First Name Text Entry Text Entry Component for user to enter first name. Has all Text Entry Properties, including the option to make it a required field. In the Actions panel, this component also has ‘Pass’ and ‘Fail’ validation events that when activated can show, hide or toggle the component.
Last Name Text Component with all the normal Text component properties. It displays a caption for the Form.
Last Name Text Entry Text Entry Component for user to enter last name. Has all Text Entry Properties, including the option to make it a required field.
First Name Valid Text Component with all the normal Text component properties. It displays the instruction to enter the first name if the user’s original entry was not validated.
Email Address Text Component with all the normal Text component properties. It displays a caption for the Form.
Email Address Text Entry Text Entry Component for user to enter email address. Has all Text Entry Properties, including the option to make it a required field. In the Actions panel, this component also has ‘Pass’ and ‘Fail’ validation events that when activated can show, hide or toggle the component.
Email Valid Text Component with all the normal Text component properties. It displays the instruction to enter a valid email address if the user’s original entry was not validated.
Comment Text Component with all the normal Text component properties. It displays a caption for the Form.
Comment Text Entry Text Entry Component for user to enter a comment. Has all Text Entry Properties, including the option to make it a required field. In the Actions panel, this component also has ‘Pass’ and ‘Fail’ validation events that when activated can show, hide or toggle the component.
Comment Valid Text Component with all the normal Text component properties. It displays the instruction to enter a comment if the user has not completed this panel.
Cancel A Button Component with all the normal button properties and an action to navigate back to the last displayed page.
Submit A Button Component with all the normal button properties and an action to submit the data to the selected form.

Custom regex validation:

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

Email:

^[a-zA-Z0-9._+]+@([a-zA-Z0-9-]+[.]+([a-zA-Z0-9]+[a-zA-Z0-9-]+[.]+[a-zA-Z0-9]{2,6})|([a-zA-Z0-9-]+[.][a-zA-Z0-9]{2,6}))$

Number:

^(-?0[.]\\d+)$|^(-?[1-9]+\\d*([.]\\d+)?)$|^0$

Phone:

^[+]?[0-9]{7,14}$