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

There are numerous ways to integrate your Smart Forms on the back-end as well: Sending your generated artifacts and data to Web Services, databases, through emails, messaging systems, cloud storage, etc, etc. These page and examples are only demonstrating front-end integrations.

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

Examples

Prepopulation

Demonstrates how to launch a Smart Form while passing in user or transaction context information to either prepopulate the form or to modify the Smart Form's behavior.

Link

UI-Free Submission

Demonstrates how to programmatically submit a Smart Form without first launching and navigating the form. This allows an application to leverage the artifact (PDF/XML/JSON/RichText) generation and back-end integration capabilities of the FormHero platform programmatically.

Link

HTML-only Integration (no-code)

Shows how you can launch a FormHero Smart Form from any HTML element, without writing any custom JavaScript in your page/application.

Link

Signed / Authenticated Form Launching

Demonstrates how to launch a Smart Form that is protected by authentication requiring a JSON Web Token. This ensures prepopulated data isn't modified, and serves as a simple form of authentication (your Smart Forms can be configured to require a JWT token that you have signed).

Link

EMBED SMART FORM IN A PAGE DIV

Illustrates how using 'viewMode': 'embedded', and a 'selector' allows a developer to embed a FormHero Smart Form within a page. 

Link

Embedding

Embedding the formhero.js library

Example Script Tag:

<script src="https://use.formhero.com/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

 

 

Example

 

 

Integrating

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"
  artifacts: [ ] // An array containing
    0: { } // An object containing
      type: "application/pdf"
      fileName: "c7f69e05-77ce-46c3-9442-5ee2572f322c.pdf"
id: "pdf::c7f69e05-77ce-46c3-9442-5ee2572f322c::7e47f6f8-85ea-4add-a123-01232e856928::c7f69e05-77ce-46c3-9442-5ee2572f322c.pdf" url: "https://services.fh.formhero.io/.../c234gsdf43434/unsigned.pdf" formHeroSessionId: "3e51f974-1175-43c4-b829-e12bb89d065b"
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:

 

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.