NAV
Javascript

Introduction

The EZFORMS Core SDK provides developers the ability to add any EZFORMS form or checklist into your website or mobile app. The tool kit exposes a public api, giving the developer granular control of form workflow, business rules, and presentation.

Download & Setup

<head>
    <link href="ezforms/css/core.app.css" rel="stylesheet">
</head>
<body>
    <ezcore></ezcore>
</body>

<script src="ezforms/ezforms.js"></script>

You can get the sdk files from the EZFORMS Github page:

First retrieve the Javascript SDK. Once you have the files, you will need to add the SDK to your project. By default, the SDK assumes you will put the EZFORMS SDK in a folder called ‘ezforms’ in the project root. You can modify this by going into ezforms.js and modifying the path. Add the css <link href="/ezforms/css/core.app.css" rel="stylesheet"> reference to the head and the script <script src="/ezforms/ezforms.js"></script> reference to the bottom of the page below all body content.

You now need to add the EZFORMS Core node to your html. Place <ezcore></ezcore> wherever you would like to render EZFORMS content.

Thats it! Just to make sure its all hooked up. Open your web page and check to see if you have a global variable Ezforms.

Quick Start

<head>
 <link href="ezforms/css/core.app.css" rel="stylesheet">
</head>
<body>
 <ezcore></ezcore>
</body>

<script src="ezforms/ezforms.js"></script>
<script>
 Ezforms.ready(function(){
     Ezforms.createSession('APP-API-KEY').then(function(){
         Ezforms.form.exec('Form-ID').then(function(formSession){
             //formSession is your instance of form execution
             formSession.render();
             //You can also call Ezforms.form.render()
         })
     })
 })
</script>

Lets get you up and running quick by rendering a form on view/page load. The following steps will get you authenticated, begin a form execution session, and render it to the view.

Web/Javascript:

  1. Use Ezforms.ready() to launch your form on load. This is not neccesary if your rendering a form from an event like a button onClick().

  2. Use Ezforms.createSession() to authenticate and create a session token

  3. Use Ezforms.form.exec() to begin a headless form execution. This allows you to manipulate form data without rendering it to the view. This is helpful if you want to pre populate fields on load.

  4. Use Ezforms.form.render() to render the form to the view.

Authentication

Ezforms.ready(function(){

    //Create a new session client side
    Ezforms.createSession('APP-API-KEY').then(function(){
        //Ready for use
    })

    //Use an existing, non expired token
    Ezforms.useSession("APP-TOKEN").then(function(){
        //Ready for use
    });

})

You can find your App API Key inside the admin console Administration > Apps.

To begin using the SDK, you must first authenticate your app and start or resume a session. Your API Key will be used for the first auth call. A Session Token will be returned and used on all calls going forward. Dont worry, the SDK handles this for you.

A note on web security - The SDK allows for client side scripting and web service calls via CORS to authenticate your application. If your using EZFORMS on a public website, we highly recommend authenticating and creating the session server side and implement useSession() client side. While your App API Key has limited abilities, if the key were compromised, it could expose information about your forms.

Once the library is properly referenced, a global variable Ezforms will be available and exposes createSession method to authenticate. Supply your app API-KEY from the admin console.

Form Execution Interactions

Method Description
createSession() Creates a new session. Returns a promise. Not recommended for client side JS.
useSession() Use an existing session that has not expired. Returns a promise.

Forms

Exec/Resume

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
        //formSession is the instance of form execution

        })

        Ezforms.form.resume(id, options).then(function(formSession){
        //formSession is the instance of form execution

        });
    })
})

When ever you want to begin working with a form, use the exec command to create a new form execution session. Returns a Promise, providing additional interaction options.

The execution session is headless and does not require you to render a view of the form. You can interact, populate, and submit the form using just the api. Its absolutely possible to fill out and submit a form without any UI. This allows you to create your own user experience and populate the form pragmatically.

Use resume to continue working on an existing pending form that was saved. You can request the pending form by the id of the saved form instance.

Returns the form execution session

Form Methods

Method Description
exec() Creates a new instance of the form being executed.
resume() Resumes from the last saved point. Lookup using the forms executed id.

Exec/Resume Parameters

Param Required Description
id Yes The Form ID
options No Session options for execution

Exec/Resume Options

Method Default Description
cached false If a locally cached version of the form exists. Use it instead of pull a fresh copy. Improves load performance, but make sure to sync regularly.
autoSave false Save progress on each user input.
geo false Request geo location from device. Requires user to authorize GEO services on the device or browser.

Form Execution Interactions

Method Description
save() Will save form progress. Returns a promise.
submit() Will submit the form as completed. Returns a promise.
render(id, type, options) Render the form as a partial view.
destroy(options) Will permanently delete the form execution record. Returns a promise.
get(id, type, field) Will get a field value by type and id
set(id, type, values) Will set a values by type and id
getElements(field, filter) Will get all elements in the form that match the filter. field options are tags and type.

Destroy Options

Method Default Description
atServer false Deletes current progress and any saved versions residing on the server.

Form Fields

Field Type Description
name string Name of the form

Page Fields

Field Type Description
fieldName string page identifier

Container Fields

Field Type Description
fieldName string Identifier of the container

Row Fields

Field Type Description
fieldName string Identifier of the row

Element Fields

Field Type Description
fieldName string Identifier of the element
value The elements input value of proper type i.e. textfield = “my input” & numfield = 5
displayValue string The input value casted to a string. Setting value will automatically trigger update of this field to string version of value. i.e. 5 = “5”.

Render

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
            //formSession is the instance of form execution

            //Render the entire form
            formSession.render(options).then(function(view){
                {
                    //view Interactions
                }
            });

            //Render a single page from the form
            formSession.render('page','id',options);

            //Render a container from the form
            formSession.render('container','id',options);

            //Render a row from the form
            formSession.render('row','id',options);

            //Render a single element from the form
            formSession.render('element','id',options);

        })
    })
})

Returns available interactions for the render type

Once you have an execution session, you can render all or portions of the form. Returns a Promise with possible view interactions.

Render Parameters

Param Required Description
id No The ID or Field Name of the resource. Defaults to Current exec form session.
type No The of identifer provided as page, container, or element.
options No Behavior options.

Render Options

Method Default Description
allowSave true Allow a form to be saved, but not submitted. Form can be completed at a later time.
allowPageChange true Display controls for paging forward and back.
enableRealTime false NOT IMPLEMENTED.
showTopMenu true Display top menu bar.
showBottomMenu true Display bottom menu bar.
showBackground true Display background. Note: The mobile platforms have this set to false by default. You must set explicitly to true to render the background on mobile.
allowPageImages true Upload images that will be affiliated with the page.
allowRowImages true Upload images that will be affiliated with the row.
allowPageNotes true Add notes that will be affiliated with the page.
allowRowNotes true Add notes that will be affiliated with the row.
css none Provide custom css which will be applied during render.
submitRedirectURL “” Redirect to fully qualified url path on submit. Set as “” to avoid redirect.

View Interactions

method Description
forward() Will go to next page in the form
back() Will go to prior page in the form

Forward

Will go to next page in the form

Back

Will go to prior page in the form

Save/Submit/Destroy

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
            //formSession is the instance of form execution

            //Render the entire form
            formSession.render();



        })
    })

    function save(){
        //Save form progress
        Ezforms.form.save();
    }

    function submit(){
        //Submit your form as completed
        Ezforms.form.save();
    }

    function destroy(){
        //Delete the form and all progress
        Ezforms.form.destroy();
    }

})

Save

Saving a form allows you to save your progress, but not be marked as completed

Submit

Submitting a form will save the form data and mark it as complete. A completed form should not be edited later.

Destroy

Destroy will terminate the form session and delete the form and all progress made.

Completed

Completed form will return the forms which are completed.

Get

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
            //formSession is the instance of form execution

            //Render the entire form
            formSession.render();

            var item = Ezforms.form.getItem(id, type, field);
            console.log(item)

        })
    })


})

The get command will allow you to retrieve the current value of any field in your form.

Get Parameters

Param Required Description
id Yes The id or fieldName of the requested object.
type Yes Element type element container row form
field No The field value to be returned. Leave empty to retrieve entire entity

Get Elements

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
            //formSession is the instance of form execution

            //Render the entire form
            formSession.render();

            var items = Ezforms.form.getElements(tags,'someTagName');
            console.log(items)

        })
    })


})

The getElements command will allow you to retrieve an array of elements from your form that match the provided filter.

Get Elements Parameters

Param Required Description
field Yes Send either tags or type.
filter Yes Specify what to look for.

Set

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
            //formSession is the instance of form execution

            Ezforms.form.setItem(id, type, valuesObj)

            //Render the entire form. The form will render with the modified items new value.
            formSession.render();

        })
    })
})

The set command will allow you to set any field in your form. Setting a field will reflect in a rendered view instantly.

Set Parameters

Param Required Description
id Yes The id or fieldName of the entity getting updated
type Yes The type of entity that is being updated
values No An object that contains 1 or more values to update

Events

During yours forms session, named events will be fired throughout. Register an event to tie your own code into EZ FORMS.

Register Event


function myFunc(event, error){
    //Do something
    console.log(event)
}

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
            //formSession is the instance of form execution

            Ezforms.form.setItem(id, type, valuesObj)

            //Render the entire form. The form will render with the modified items new value.
            formSession.render();

            //Register an event to call myFunc
            Ezforms.events.subscribe('event', myFunc);

        })
    })
})

Register your own method to an event and be notified when the event occurs.

Example

In the above example when the EventType is elementChange then whenever there is any change in the form element callback will be received.

Events

Event Description
formSelect Notified when a form execution or resume session has begun.
render Notified when a form is rendered.
renderDestroy Notified when a rendered form view is destroyed.
formSave Notified when a form is saved.
formSubmit Notified when a form is submitted.
formDestroy Notified when a form has been destroyed(deleted).
elementChange Notified when a elements value has been changed.
pageChange Notified when paging.

Registered Events


function myFunc(event, error){
    //Do something
    console.log(event)
}

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
            //formSession is the instance of form execution

            Ezforms.form.setItem(id, type, valuesObj)

            //Render the entire form. The form will render with the modified items new value.
            formSession.render();

            //Register an event to call myFunc
            Ezforms.events.subscribe('event', myFunc);

            console.log(Ezforms.events.registeredEvents)

        })
    })
})

See a list of possible events and whats been registered

Clear Event


function myFunc(event, error){
    //Do something
    console.log(event)
}

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){
        Ezforms.form.exec('id', options).then(function(formSession){
            //formSession is the instance of form execution

            Ezforms.form.setItem(id, type, valuesObj)

            //Render the entire form. The form will render with the modified items new value.
            formSession.render();

            //Register an event to call myFunc
            Ezforms.events.subscribe('formSubmit', myFunc);

            console.log(Ezforms.events.registeredEvents)

            Ezforms.events.clear('formSubmit');

            console.log(Ezforms.events.registeredEvents)

        })
    })
})

When you no longer want to subscribe to an event, just remove it.

Storage

EZFORMS maintains a local data store for use offline and in situations where a form submission failed for network reasons. The following utility API’s give you control over how the data store works.

Sync Forms

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){

        Ezforms.storage.syncForms();

    })
})

Downloads all forms within your account for use offline. This is also beneficial for speedy loading of a form that does not change often.

Clear Forms

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){

        Ezforms.storage.clearForms();

    })
})

Clear local storage of all downloaded forms.

Process Queue

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){

        Ezforms.storage.processQueue();

    })
})

Allows you to attempt to process all items in the queue. This is automatically triggered upon the successful submission of a form.

Clear Queue

Clear out all items in the queue.

Ezforms.ready(function(){
    Ezforms.createSession('APP-API-KEY').then(function(){

        Ezforms.storage.clearQueue();

    })
})

API

You have access to run many of the Rest API’s from within the SDK. For a full list of API’s go to the Rest API section. All calls return a Promise.

Method Description
appAuth(apiKey) Use your App API Key to start a session. Returns a Session token.
getApp() Get the app record for this session
getForms() Get all publish forms. For use in giving the user the ability to select a form to execute.
getForm(id) Get a form by id. Retrieving a form does not start a execution session.
getPendingForms() Get all pending forms. A pending form has been saved, but has not been marked completed. For use in giving the user the ability to select a pending to resume.
getPendingForm(id) Get a pending by id. Retrieving a form does not resume a execution session.

Errors

The Ezcore API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The kitten requested is hidden for administrators only
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
429 Too Many Requests – You’re requesting too many kittens! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
141 ScriptFailed - Error code indicating that a script failed.
102 InvalidQuery - Error code indicating you tried to query with a datatype that doesn’t support it, like exact matching an array or object
107 InvalidJSON - Error code indicating that badly formed JSON was received upstream. This either indicates you have done something unusual with modifying how things encode to JSON, or the network is failing badly.