Formstack's Most Recent Form Builder(V4) and API Overview

What is V4 and why are we changing?

 

V4 Live Forms is the latest update to our form building engine. While you won’t see any significant changes in how the form builder looks and feels, there is a lot that has improved under the hood. This move is to better align ourselves with industry standards and allow for more flexibility in the way our forms can be interacted with and manipulated. This move also allows us to be more agile with improvements and feature additions in the future. While this move is a large undertaking, it will set us and our customers up for long-term success. Below is an in-depth breakdown of the changes happening and why.

This article mostly covers the technical side of what V4 is and why we've made this move. If you're looking for more information on how to migrate your forms to the newest version, we'd recommend checking out this article .
 

Note: While we provide access to our API on all paid accounts, our support team is unable to assist with troubleshooting custom API setups. If you're looking for help with building out some of these solutions, we'd recommend getting in touch with one of our certified Partners here.  

 

Formstacks most recent form builder version (V4) is built with industry-standard modern technologies

• React is an industry-standard
• Users new to the product can get up to speed faster
• New features are possible to develop
• Typescript with proper static analysis, tooling, and deployment

 

Formstacks last version (V3) is proprietary, complex, inefficient, and expensive to maintain

• It is difficult for new users to get up to speed.
• Unable to extend without breaking existing functionality
• A single 10k-long file in plain old Javascript.

 

Why an API?

• Standardize interactions with the live form
• Ensure changes to technology do not affect downstream customers
• Transparent, easily documented

 

Encapsulation

Protect clients from knowing the specifics of how controls are implemented. Instead of accessing the DOM directly and manipulating elements to dynamically change options at run time, the API provides a concrete way to accomplish use cases that will not change

 

For example: in v3 the minutes of a date field are modeled with a simple dropdown, while in v4 a new sophisticated date picker control was used. Using the API, a developer does not need to know the specifics of the control implementation, but instead, interacts with the API abstraction, which will remain static no matter what the specific DOM nodes used to implement the actual control.

 

This also means a client does not need to include any additional libraries, like jQuery, to accomplish most customization.

 

// v3 with jQuery

$(document).ready(function() {

  $("#field12345I option").hide(); //hide all minute options

  $("#field12345I option[value=30]").show(); //show the “30” minute option

  $("#field12345I option[value=00]").show(); //show the “00” minute option

});

 

 

// v4

var form = window.fsApi().getForm("100");

var dateField = form.getField("12345");

dateField.setTypeAttribute("timeSteps", { hours: 1, minutes: 30, seconds 1 });

 

Key Differences between v3 and v4

 

Rendering

V3 is server-side rendered, and V4 is client-side. This means that scripts included in Embed Code fields are being executed at a different point in the lifecycle of the page, much later than they would be in V3.

 

This means that certain events and features are not available including, but not limited to:

• `document.ready` has already fired
• `document.write` the page as been rendered, and the elements cannot be written in this way
   

Event Handling

V3 had no formal event system, forcing users to directly bind DOM events to inputs, and if they weren’t careful, potentially compromising the functionality of the form.

 

The V4 API provides an abstraction over the normal DOM events, protecting the user from having to know exactly what kind of elements they need to bind to, as well as providing some useful form-specific events such as changing pages.

 

var form = window.fsApi().getForm("100");

 
form.registerFormEventListener({

    type: "change",

    onFormEvent: function (event) {

    // behavior to occur during a change event can be added here

        return Promise.resolve(event);

    }

  });

Note - When making any style changes using CSS via the style editor, or in an embed code script on the form, how we handle variable and utility class names have changed. The new form version utilizes variable class names (ex. jnnwJH or hCMMok) and utility class names (ex. fsSubmit or fsPage). The utility classes will never change but the variable classes may change with large form updates. All of the examples in this document use utility classes and we highly recommend only using utility classes as well. If there is an item you want to target that doesn’t have a utility class, please reach out! We can add additional classes. 

Please reference this article to see all of the available Classes and IDs - /hc/articles/44593219745939

 

Link to API Spec

https://live-form-api.formstack.com/index.html

Conclusion

The catchword of v4 is Encapsulation. A robust API has been built around the core engine to ensure all participants in development are able to extend functionality without interfering with each other, for example: 

• Designers are free to use whatever controls are appropriate for the best user experience without breaking custom user implementations. 
• Engineers are able to use whatever technologies are best and safest to meet product requirements. 
• Downstream clients of the API will have a well-documented and stable framework to implement customization that will remain intact for v5 and beyond.