Clear all local forms.

formsList.clearAllForms(function(err) {
    if (err) {
        console.log('Error deleting forms', err);
    } else {
        console.log('Reloading forms list', formsList.getFormsList()); //will return empty list
    }
});

Check if a specific form model is up to date.

var model = new $fh.forms.models.Form();
var updated = $fh.forms.models.forms.isFormUpdated(model);
console.log(updated);

Get form meta object by formId.

var exampleFormId = '1234';

var params = {
 'fromRemote' : true
};

$fh.forms.getForms(params, function(err, formsList){
if(err) console.error(err);

var formDetails = formsList.getFormMetaById(exampleFormId); //gets meta object from forms list based on id
console.log(formDetails);
});

Read form list model from local or remote forcely. It will store to local storage automatically if it does not exist.

formsList.refresh(true, function (err) { //if fromRemote == true, forms are read from server.
// If false, reads from local storage
  if (err) {
    console.log('Error refreshing form', err);
  } else {
    console.log('Refreshed form list', formsList); //prints newly refrehsed list
  }
});

Removes model from local storage but not from RAM.

formsList.clearLocal(function (err) {
  if (err) {
    console.log('Error occurred clearing forms from local storage', err);
  } else {
    console.log('Reloading forms', formsList.getFormsList());
  }
});

Retrieve an array containing forms meta data.

var params = {
  'fromRemote': true
};

$fh.forms.getForms(params, function (err, formsList) {
  if (err) console.error(err);

  var forms = formsList.getFormsList();
  console.log(forms);
});

Retrieve the number of forms stored.

var params = {
  "fromRemote": true
};

$fh.forms.getForms(params, function (err, formsList) {
  if (err) console.error.(err);

  var numOfForms = formsList.size();
  console.log(numOfForms);
});

Construct a Form object. Callback when form definition is loaded.

var params = {
  "formId": ”1234”,
  "fromRemote": true
};

$fh.forms.getForm(params, function (err, form) {
  if (err) console.error(err);

  // new form model
  console.log(form);
});

Retrieve last updated timestamp on server.

var params = {
  "formId": ”1234”,
  "fromRemote": true
};

$fh.forms.getForm(params, function (err, form) {
  if (err) console.error(err);

  var lastUpdate = form.getLastUpdate();
  console.log(lastUpdate);
});

Retrieve an array of page models associated to this form.

var params = {
  "formId": "1234",
  "fromRemote": true
};

$fh.forms.getForm(params, function (err, form) {
  if (err) console.error(err);

  var pageList = form.getPageModelList();
  console.log('Array of pages associated with this form', pageList);
});

form.getRuleEngine();

Retrieve rule engine attached to the form().

var params = {
  "formId": 1234,
  "fromRemote": true
};

$fh.forms.getForm(params, function (err, form) {
  if (err) console.error(err);

  var ruleEngine = form.getRuleEngine();
  console.log(ruleEngine);
});

Retrieve form name.

var params = {
  "formId": "1234",
  "fromRemote": true
};

$fh.forms.getForm(params, function (err, form) {
  if (err) console.error(err);

  var formName = form.getName();
  console.log(formName);
});

Retrieve form description.

var params = {
  "formId": "1234",
  "fromRemote": true
};

$fh.forms.getForm(params, function (err, form) {
  if (err) console.error(err);

  var formDescription = form.getDescription();
  console.log(formDescription);
});

Retrieve form Id.

var params = {
  "formId": "1234",
  "fromRemote": true
};

$fh.forms.getForm(params, function (err, form) {
  if (err) console.error(err);

  var formId = form.getId();
  console.log(formId);
});

Retrieve field model by field id.

var params = {
  "formId": "1234",
  "fromRemote": true,
  "fieldId": "123"
};

$fh.forms.getForm(params, function (err, form) {
  if (err) console.error(err);

  var fieldModel = form.getFieldModelById(fieldId);
  console.log(fieldModel);
});

Initialise a new submission model for this form.

form.newSubmission(); //creates a new submission

Remove current form model from memory cache (singleton).

form.removeFromCache();

Read form model from local memory or remote forcely. It will sotre to local storage automatically if it does not exist.

form.refresh(true, function (err) {
  if (err) {
    console.log('Error refreshing', err);
  } else {
    console.log('Refreshed page');
    //refresh successful
  }
});

Remove locally stored Form.

foundForm.clearLocal(function (err) {
  if (err) {
   console.log('Error removing form');
  } else {
   //form cleared successfully
  }
});

Set if this page model should be visible or not. Will emit ‘visible’ or ‘hidden’ based on whether the boolean value 'isVisible' is set to true or false.

page.setVisible(true) //Boolean value to determine whether page is set to visible or not.

Retrieves page name.

 var pageList = foundForm.getPageModelList(); //Iterates through all pages of a returned form and prints out page names
 for (var page = 0; page < pageList.length; page++) {
   var currentPage = pageList[page];
   console.log('Name of current page is: ', currentPage.getName());
 }

Retrieve page description.

page.getDescription();

Retrieve field models associated to this page.

var pageList = form.getPageModelList(); //Retrieves all pages of a form

for (var page = 0; page < pageList.length; page++) { //Iterates through all pages
  var currentPage = pageList[page];
  var pageFields = currentPage.getFieldModelList(); //Retrieves all fields on a page
  console.log(pageFields); //Lists all fields
}

Retrieve a specific field model. The field model does not need to be in this page. Alias of Form.getFieldModelById(fieldId).

var fieldId = '1234';

page.getFieldModelById(fieldId); //Returns Field model

Returns true if the field is a required field.

currentField.isRequired(); //will return true if the field is required

Returns true if the field is a repeating field, or false if the field is not a repeating field.

field.isRepeating();

Returns the type of the field.

field.getType();

Returns the name of the field.

console.log(field.getName()); //pritns name of field

Returns the Field Code for a field if it exists. If the field was not assigned a field code in the Studio null is returned.

Returns field instruction text.

field.getHelpText();

Returns the inputValue object if validation is successful, or an error message if validation fails.

var field = form.getFieldModelById(fieldId);
var inputValue = elem.value; //Value of an element such as text field, numberfield etc

field.validate(inputValue, function (err, res) {
  if (err) {
    console.log('Validation Error', err);
  } else {
    console.log('Validation Successful', res);
  }
});

Returns an array of rule objects that are associated with the field.

field.getRules();

Retuns an array of check box choices.

if (field.getType() == 'checkboxes') {
  console.log('Checkbox options: ', field.getCheckBoxOptions());
}

Returns radio box options.

if (field.getType() == 'radio') {
  console.log('Radio options: ', field.getRadioOption());
}

Returns a list of submission meta data.

submissions.getSubmissions();

Returns a list of submission meta data

submissions.getSubmissionMetaList();

Retrieves the meta data for specified form.

var formId = '53146bf95a133733451cd35b';

$fh.forms.getSubmissions({}, function (err, submissions) {
  if (err) {
    console.log('Error loading submissions', err);
  } else {
    console.log('Array of completed submissions', submissions);
    var foundSubmissions = submissions.findByFormId(formId);
    console.log('Array of submissions for specified form: ', foundSubmissions);

  }
});

Clear submission meta list from this model and local storage.

$fh.forms.getSubmissions({}, function(err, submissions) {
    if (err) {
        console.log('Error loading submissions', err);
    } else {
        console.log('Array of completed submissions', submissions);
        submissions.clear(function(err) {
            if (err) console.err(err);
        });
    }
});

Return submission drafts()

submissions.getDrafts();

Returns pending submissions.

submissions.getPending();

Returns submitted submissions.

submissions.getSubmitted();

Returns submissions that have errors.

submissions.getError();

Return submissions that are currently in progress.

submissions.getInProgress();

Retrieves a submission model object by submission meta data from submission list model.

var params = submissions.getSubmitted()[0];

submissions.getSubmissionByMeta(params, function (err, submission){
  if(err) console.error(err);

  console.log('Returned Submission',submission);
});

Retrieves a submission model by the Local ID of the submission.

var localId = "sublocalid1";

submissions.getSubmissionByLocalId(localId, function (err, submission){
  if(err) console.error(err);

  console.log('Returned Submission',submission);
});

Retrieves a submission model by the Remote ID of the submission.

var remoteId = "subremoteid1";

submissions.getSubmissionByRemoteId(remoteId, function (err, submission){
  if(err) console.error(err);

  console.log('Returned Submission',submission);
}

Save current submission to draft / local storage.

currentSubmission.saveDraft(function (err) {
  if (err) {
    console.log(err);
  } else {
    console.log('Draft saved to local storage');
  }
});

Submit current submission. It will create a task for uploading.

currentSubmission.submit(function (err) {
  console.log(!err);
  if (err) {
    console.log(err);
  }
});

currentSubmission.on("submit", function () {
 /* Upload the submission. */
  currentSubmission.upload(function (err) {
    if (err) {
      console.log(err);
    }
  });
});

Returns the current status of the submission.

submission.getStatus();

Allows a user to add a comment to the current submission.

submission.addComment('test message', 'test user');

Returns an array of commetns for the current submission.

submission.addComment('test message', 'test user');

console.log(submission.getComments()); //will return an array containing the above comment

Remove a comment from the current submission via its timestamp.

submission.removeComment(timeStamp);

Add a value to submission for a field. This will validate the input value and it will return an error message as a string if failed. If in transaction mode, it will not immediately add user input value to submission but a temp variable. If not in transaction mode, the input value is added to submission immediately. If the "sectionIndex" parameter is provided, a new value is added to the field in the given section index, within the repeating section group.

var params = {
    "fieldId": '53146c1f04e694ec1ad715b6',
    "value": 'New example text',
  "Index":optional,
    "sectionIndex":optional

};
currentSubmission.addInputValue(params, function(err, res) {
    if (err) console.error(err);

    console.log('Newly added input: ', res);
});

Start a transaction for user input. if already started, it will drop temporary input.

submission.startInputTransaction();

End the transaction. If the transaction succeeds, it will copy temporary input to submission to be uploaded. If it fails, it will drop the temporary user input. 'isSucceed' is a boolean value. If 'true' is passed into the function, the transaction is complete and the user input is transfered from temporary storage to the submission. If 'false' is passed into the function, then the temporary values are discarded and the transaction is not completed.

submission.startInputTransaction();

var params = {
    "fieldId": '53146c1f04e694ec1ad715b6',
    "value": 'Example text'
  };

submission.addInputValue(params, function(err, res) {
    if (err) {
        console.log('Error adding input', err);
        submission.endInputTransaction(false); //Transaction failed. New values are not added to submission.
    } else {
        console.log('Updated value: ', res);
        submission.endInputTransaction(true); //End input transaction. New value is added to submission.
    }
});

Remove all user input from this submission.

submission.reset();

Returns Form object associated with the submission.

submission.getForm(function(err, form) {
    if (err) console.error(err);

    console.log('Form associated with submission: ', form);
});

Remove a value from a specific field based on ID, sectionIndex may be passed to get value of a field in specific section, otherwise it defaults to 0.

var exampleFieldId = '1234';

submission.removeFieldValue(exampleFieldId);

Get input values associated with a field, sectionIndex may be passed to get value of a field in specific section, otherwise it defaults to 0.

var fieldId = '1234';

currentSubmission.getInputValueByFieldId(fieldId, function(err, res) {
    if (err) console.error(err);

    console.log('Field value: ', res);
});

submission.on('inprogress', function(uploadTask) {
    var self = this;
    uploadTask.submissionModel(function(err, submissionModel) {
        //The 'this' parameter in the event refers the submission model that emitted the event.
        assert.strictEqual(self, submissionModel);
    });
});

submission.on('error', function(errorMessage) {
    console.error(errorMessage);
    assert.equal(errorMessage, this.getErrorMessage);
});

submission.on('savedraft', function() {
    //This is the local ID of the submission that emitted the 'savedraft' event.
    assert.isString(this.getLocalId());
});

This error is only emitted locally. This is not a validation error on the server side.

submission.on('validationerror', function(validationObject) {
    //This is the local ID of the submission that emitted the 'savedraft' event.
    assert.isString(false, validationObject.valid);
});

Validation Object

{
    valid: < true / false > ,
    < fieldid1 > : {
        valid: < true / false > ,
        errorMessages: [
            "Validation Error Message 1",
            "Validation Error Message 2"
        ]
    },
    ....,
    < fieldidN > : {
        valid: < true / false > ,
        errorMessages: [
            "Validation Error Message 1",
            "Validation Error Message 2"
        ]
    }
}

The submission has passed local validation. It is now ready to be uploaded to the Cloud.

submission.on('submit', function() {
    //Valid Submission, it can be uploaded now or at any other time
    this.upload(function(err, uploadTask) {
            ...
    });
});

submission.on('submitted', function(remoteSubmissionId) {
    assert.equal(remoteSubmissionId, this.getRemoteSubmissionId());
});

At this point, the remote submission ID has been assigned on the Cloud side. The submission can now be considered valid on both Client and Cloud sides.

submission.on('queued', function(remoteSubmissionId) {
    assert.equal(remoteSubmissionId, this.getRemoteSubmissionId());
});

submission.on('progress', function(progressJSON) {
    //The Current Progress Of The Submission
});

{
    'formJSON': false, //Boolean specifying if the submission JSON has been uploaded.
    'currentFileIndex': 0,
    'totalFiles': 3,
    'totalSize': 54321, //Size in Bytes of the entire submission
    'uploaded': 12345, //Size, in Bytes already uploaded
    'retryAttempts': 1, //Number of times the submission has been tried.
    'submissionTransferType': < upload / download > , //Is the submission being uploaded or downloaded.
    'submissionRemoteId': "remoteSubmissionID1234", //The remote submission ID if it is available.
    'submissionLocalId': "localSubmissionID1234" //The local submission ID
}

This also includes all files when a submission is downloaded to a mobile client device.

submission.on('downloaded', function(remoteSubmissionId) {
    assert.equal(remoteSubmissionId, this.getRemoteSubmissionId());
});