Forms
Timeline forms are used to insert form elements into the timeline interactivity. Form widgets are widgets that are linked to the form entity in the timeline. There can only be one form in a timeline. Using forms in a timeline is done the same way as a regular HTML form, by using form fields. The only difference from normal HTML forms is thats it's possible to use a form field that will show, for example, after 1 minute of playtime. Or show a form field the whole time or after a click on a button. I>A user can only use forms in a timeline when they have the timeline forms permission.
10.1 Form setup
To set up a form to send data to a server there are 3 prerequisites.
- A form field wiget, which will contain the user provided data that will be sent to an email address and/or server.
- A submit button that when clicked will trigger sending the user provided data to an email address and/or server.
- Configuration of the form, like location to send the data to
10.2 Form field widget
The form field widget is a input field, which can be used to collect information from the user. This widget has a couple of configuration fields that need to be supplied for correct behavior.
Figure 10.1 Form fields
10.2.1 Placeholder
Use this text to show a message in the input field e.g., please provide us with your name.
10.2.2 Form Element Name
This is the name this form field will have within the form. E.g. a form element name called address will be sent with it's value as address#SomeAddressTheUserProvided
10.2.3 Validation
Use this to configure if and how this field is to be validated. Validation has the following methods available:
- Blue Billywig internal; Choose from: mandatory, email address, postal code
- Custom Backend; A custom backend url, like http://www.example.com/validate
10.2.4 onValidationSucceeded
Add actions that will be triggered when this form field widget is valid. Whenever a user changes input data which is valid this will trigger an onValidationSucceeded event.
10.2.5 onValidationFailed
Add actions that will be triggered when this form field widget is invalid. Whenever a user changes input data which is invalid this will trigger an onValidationFailed event.
10.3 Submit button
This can be any widget that has a form post action defined, provided it has an onclick handler
Figure 10.2 Submit button
Adding a form post action to the onclick handler will make it possible to post the form.
10.4 Configuration of the form
As soon as a form field widget is on the stage the form button will be visible beneath the configuration panel in the top right of the screen.
Figure 10.3 Setup
Pressing this button will open the timeline form window.
Figure 10.4 Forms window
10.5 Form properties
10.5.1 Name
Name of the form. A name is not mandatory, though we advise to fill it in as it will be used as subject in the email and it can be used for analytics.
10.5.2 Post to url
Backend url that will handle the form post. This field is only mandatory when data should be sent to an external system. However, the data will always be sent first to the Blue Billywig backend. The Blue Billywig backend will then send the data to the external url and/or the provided email address.
10.5.3 Send to Email
Email address to send the mail to. This address will receive an email after a user pressed the submit button.
10.5.4 Use template url
Specify a url to an email template file used to create the email that will be sent to the provided email addresses. Any of the 3 meta-data strings shown below can be used in the template to automatically append certain data.
- ||thumbnailUrl|| url to the thumbnail of the video the form was posted from
- ||Subject|| clip title : name of form
- ||body|| form variables and its values
The template url should link to a page that has an html structure like defined below.
<html> <head> <title>Mail Template formsubmit</title> <style type="text/css"> * { padding: 0; margin: 0; } h1, h2, h3, p, ul, ol { margin: 1em 0; } </style> </head> <body> <img src="||thumbnailUrl||"> ||Subject|| ||body|| </body> </html>
10.5.5 Email-from
This field can be used to change the email address from which the email originated. This address has to be whitelisted at our VMS mail service. Please contact support to whitelist an email address support@bluebillywig.com .
10.6 Form event handling
There are three form events that can be thrown i.e., onSuccess, onFailure and on all widgets validated. Although it's possible to add a form-post action to the on all widgets validated event, we strongly advise against it. We suggest to show the submit button after the on all widgets validated event has been thrown.
10.7 Form widget list
The widget list shows all form related widgets used in this form.
Figure 10.5 Forms widget list
- Shows a widget with its form element name.
- Shows a widget without a form element name. Take notice of the warning sign. Form widgets without a form element name will not post any data to the backend. The Form element name field can be found in the configuration panel in the top right of the screen.