Introduction

Welcome to the formhero.js API reference section! The following is a living document meant to describe the functionality and usage of the library to launch smart forms and process completed data..

If you require additional assistance, please contact us. Enjoy.

Embedding

Embedding the formhero.js library

Example Script Tag:

<script src="https://use.formhero.io/latest/formhero.js" type="text/javascript">/script>

Notes

Including the formhero.js library in your application or webpage is as easy as adding a single script tag to your HTML. The tag can be included in the head section, or just before the closing body tag.

Note:
Please source the file from our URL versus downloading the file and including it in your own web resources. This will ensure you include critical bug fixes without having to make changes to your site/service.

Links:

Launching

Launching: Simple HTML

Example Usage of Simple HTML Launching (No custom JavaScript required)

// Example form url:  https://formhero.sandbox.smartforms-testing.com/#/demos/pdf-in-browser-demo/

<a fh-form="pdf-in-browser-demo" fh-organization="formhero" fh-team="demos" fh-view-mode="modal|page">Launch Sample Form</a>

Instructions

If you are comfortable making HTML changes, only need basic integration, and don’t want to write any JavaScript, you can just add some custom HTML attributes to anchor (<a>) or button (<button>) tags in your page.

In this use case, you must add the following attributes to HTML elements you would like to use to initiate for FormHero form/workflow:

Required Parameters

Optional Parameters

Codepen Example

Launching: Complete

Example Usage of Complete Launching

formhero.loadForm({
  form:"my-form-name",
  organization: "fh",
  team: "demos",
  onCloseFn: function() { console.log("The user closed the modal"); },
  onUpdateFn: function(status) { console.log("The user moved to a new area in the form"); }
}, 
{ /* Map of data to pass into form */
  "customer.firstName": "Daniel",
  "customer.lastName": "Radcliffe"
}).then(
  function(successResult) {
    // The successResult object contains the data that was collected.
    // Use this object and space to process the data via your services.
    console.log("Form Success:", successResult);
  },
  function(cancelledResult){
    // The cancelledResult object contains the data that was collected.
    // Use this object and space to persist a session.
    console.log("Form Cancelled:", cancelledResult);
  }
).catch(function(exceptionResult) {
  /* Called if an error occurs loading the form */
  console.log("Exception:", exceptionResult);
});

Example Result Success

successResult: { } // An object containing
  collectedData: { } // An object containing
    FORMHERO_SESSION_ID: "3e51f974-1175-43c4-b829-e12bb89d065b"
    customer.firstName: "Daniel"
    customer.firstName: "Radcliffe"
    customer.school: "Hogwarts"
  outputFiles: [ ] // An array containing
    0: { } // An object containing
      mimetype: "application/pdf"
      sessionId: "3e51f974-1175-43c4-b829-e12bb89d065b"
      url: "https://services.fh.formhero.io/.../c234gsdf43434/unsigned.pdf"
  state:"form-success"
  submittedAt: "2017-01-01T11:11:11.111Z"

Example Result Reject

canceledResult: { } // An object containing
  buttonAction: "cancel-without-save"
  collectedData: { } // An object containing
    FORMHERO_SESSION_ID: "3e51f974-1175-43c4-b829-e12bb89d065b"
    customer.firstName: "Daniel"
    customer.firstName: "Radcliffe"
  formError: null
  state:"form-saved-but-incomplete"

Usage

formhero.loadForm(options, <dataMap>)

Instructions

You may also call FormHero from within your own JavaScript code. This method provides the most functionality to your web development team, including complete control over the collected data and notification about when a form is completed, abandoned, or when there are unexpected errors.

Required Parameters

Optional Parameters

Returns

formhero.loadForm(...) returns a promise that resolves to a formResult object with the following properties:

Codepen Example

Retrieving

Retrieving Documents

The result object returned to your resolve function will contain a ‘collectedData’ field, which is a map of the field-name / value pairs resulting from the user’s submission of the document.

This object will also contain a stringified ‘submittedAt’ timestamp, an ‘outputFiles’ array object, a sessionId and a JWT token. When documents are signed or generated as a part of the output, this array will contain objects in the following format:

Note that generated documents are only available for a limited window of time (10 minutes) and session ID value must be provided in the HTTP Header in the HTTP call made to retrieve the document. So, set an HTTP Header named ‘x-formhero-session-id’ to the sessionId value returned in the outputFile object you are trying to retrieve.