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.

  1. A form field wiget, which will contain the user provided data that will be sent to an email address and/or server.
  2. A submit button that when clicked will trigger sending the user provided data to an email address and/or server.
  3. 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.

Form fields

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:

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

Submit button

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.

Setup

Figure 10.3 Setup

Pressing this button will open the timeline form window.

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

Forms widget list

Figure 10.5 Forms widget list

  1. Shows a widget with its form element name.
  2. 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.