9. Embeddable Form widget

You are here:
< All Topics

Form Widget

  1. Introduction
  2. Which Form Embed Code Should I Use?
  3. How to populate a Field with a Querystring?
  4. How to listen postMessages sent by the Form Widget
  5. Form Widget Setting
  6. Interacting with the Form via JavaScript

Introduction

The Embed code is a few lines of HTML that you can use to embed forms and surveys into your own website. This is the easiest way to display a form on your site. This is compatible with a vast range of CMS systems such as WordPress. Every time you make a change to your form in the form builder, the embedded form will automatically update.

The Form Widget has been designed to work on any web page without conflicting with it’s javascript or css.

Which Form Embed Code Should I Use?

We currently offer two options for publishing a form within your web site:

  1. Embed with Design: Publishes the form with the theme that has been applied.
  2. Embed without design: Publishes the form without any theme.

How to populate a Field with a Querystring?

You can populate a field with URL parameters. Just make sure to use the Field ID or Field Alias as the parameter key, then the value assigned to this parameter will appear in the field.

How to listen postMessages sent by the Form Widget

To be able to listen to the messages sent by the Form Widget, you can add an event listener to your web page. If you need to know a submission ID for your own website, then you can add this code below theembed code:

window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
    if (event.data) {
        var data = JSON.parse(event.data);
        if (typeof data.action !== "undefined" && data.action === "success") {
            console.log("Submission saved with ID", data.data.id);
        }
    }
}

Advanced Form Widget Settings

The form widget has some options that you can set:

  • Id: Form’s ID in the application. For example: ‘id’: 1152
  • Sid: Submission ID. Use this option to edit a form submission previously collected. To find the Submission ID, go to the Submission Manager. For example ‘sid’: 964
  • Container: ID of the HTML element where the form’s iframe will be inserted. By default, points to the DIV ID that contains the link to the form. For example: ‘container’: ‘c132’
  • Width: Specifies the width of the form/survey. For example: ‘width’: ‘100%’
  • Height: Specifies the height of the form/survey. Usually, the embed code comes set with a value in pixels. For example: ‘height’: ‘846px’
  • Auto Resize: By default, is enabled. Automatically resize to the height of the form. For example, when validation messages are shown.
  • Custom JS: By default, is enabled. Is an integer value (1 or 0) that lets you enable or disable the loading of external javascript files. For example: ‘customJS’: 1
  • Record: By default, is enabled. Is an integer value (1 or 0) that lets you enable or disable the Form Tracker. For example: 'record': 1
  • Form: Specifies the path to the form’s embed.
  • addToOffsetTop: By default, is 0. Add or subtract a number of pixels to OffsetTop before calculating the form location. For example: 'addToOffsetTop': '-60'
  • Default Values: If you want to pre-fill form fields with default values, you can use this option. Default Values is a JSON object where your key is the id of the form field and its value is the content of the field. For example:
'defaultValues': {
    'text_0': 'This is my default value'
}

Note that fields of type checkbox and radio button are selected by using boolean values. For example:

'defaultValues': {
    'text_0': 'This is my default value',
    'checkbox_0': true
}

Interacting with the Form via JavaScript

The Form Widget contains many features and options that can be configured inside an external JavaScript File.

Note: To load a JavaScript File you must go to Forms -> Actions -> Settings -> UI Settings.

By default, a jQuery object is available. So you can interact with the Form in a very simple way by using the following lines of code:

$( document ).ready(function() {
  // 
});

The Form element

The Form element – formEl – is a jQuery object to which you can access to get information and/or manipulate it directly. For example, we’re going to know the high of our form with the following lines of code:

$( document ).ready(function() {
  console.log('The form height is', formEl.height());
});

Listening for Events

Certain events are triggered when the Form does something.

  • view: This event will be triggered when a form has been viewed.
  • fill: This event will be triggered the first time you interact with the form. For example, by filling a text field or select a radio button.
  • error: This event will be triggered when the Server threw a validation error.
  • success: This event will be triggered when the Form has been submitted successfully.
  • nextStep: This event will be triggered each time you progress to the next step in a multi-step form.
  • previousStep: This event will be triggered each time you go back one step in a multi-step form.

A very basic example for detecting when a form fail would be:

$( document ).ready(function() {
    formEl.on('error', function(event) {
        /* Track a validation error */
    });
});

The Event Handlers: previousStep and nextStep

In addition to the events, A1Surveys offers two event handlers that allow you to go backward and forward a page on a multi-page form/survey. .

Auto-Advance in multi page forms and surveys

By default, when you create a multi-page form, two navigation buttons are added automatically: “Previous” and “Next” at the bottom of the form. These buttons allow you to navigate through the form until you reach the last page where usually the Submit button is placed.

In certain circumstances, you may wish to advance directly to the next page without pressing any buttons. For this, we will make use of the nextStep event.

With the following code, we will make our form / survey go to the next page each time a radio button is selected:

$( document ).ready(function() {
    $('input[type=radio]').on('change', nextStep);
});

Finally, if you want to hide the navigation buttons you can add the following lines in the CSS Theme assigned to your form:

.previous, .next {
    display: none !important;
}

Upload Multiple JavaScript and CSS files in our Form

By having the jQuery object, we can make use of jQuery.when().done() to load multiple javascript objects and make use of them once they are ready to use.

Previous 8. Survey and Form Analytics
Next 10. Import and Export
Table of Contents