new FormsAPI($rootScope, $http)

Warning! The SmartFlo™ APIs assume 2 global variables are set in $rootScope prior to using the APIs:

  1. $rootScope.credential
  2. set implicitely by the AuthAPI class upon success of the authenticate method
  3. $rootScope.site
  4. set by the calling application to the
    domain (e.g., www.smartflo.biz) or IP address of the target SmartFlo™ system, possibly when initializing the module that declares an API service

Example

//
// Warning! The global '$rootScope.site' field value must be set 
// to the target SmartFlo™ domain prior to using theSmartFlo™ APIs. In this 
// example it is set by the configuration block of the 'sftasklist' module.'
//
angular.module('sftasklist', [])
     // inject API as a service
     .service('SFformsApi', ['$rootScope', '$http', FormsAPI]) 
     .controller('SFtasklistCtrl', TaskListCtrl);
     .run(function ($rootScope, $location) { 
     // store the site for use by APIs
         $rootScope.site = $location.host();
         if ($location.port !== null & $location.port !== 80) {
         $rootScope.site += ':' + $location.port().toString();
    }
});

Parameters

Name Type Optional Description

$rootScope

object

 

The topmost parent scope in AngularJS.

$http

service

 

The core AngularJS service that facilitates communication with the remote HTTP servers via the browser's XMLHttpRequest object or via JSONP.

Copyright
© Chalex Corp. 2002 - 2017. All rights reserved.
Returns

class A constructor that will be instantiated.

Methods

getSavedXMlFormValues(params, successHandler[, failureHandler]) → object

Retrieves the most recent saved values for a given form in a given job.

Example

function getSavedXMlFormValues(jobid, formid) {
     var params = {
         jobid: jobid, // job ID of currently selected task
         formid: formid: // form ID of currently selected task
     };
     SFformsApi.getSavedXMlFormValues(params, handleGetSavedXMlFormValues);
}

function handleGetSavedXMlFormValues(result) {
     if ('0' === result.status) {
         $scope.savedFormData = result.savedFormData;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object providing jobid and task id of the currently selected task.


var params = {
     jobid: [job ID of currently selected task],
     formid: formid [form ID]
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


 result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     savedFormData: {
         affiliate: [SmartFlo™ affiliate],
         jobid: [the job id],
         formid: [form ID],
         editedBy: [most recent editor of form values],
         editedOn: [date of most recent edit],
         fields: [array of field value objects]
     }
 };

fieldValue { fieldid: [id of field], fieldname: [name of field], fieldvalue: [value of field], fieldlabel: [field prompt], fieldtype: [field type] };

getXMlForm(params, successHandler[, failureHandler]) → object

Retrieves a given form definition created using the SmartFlo™ XMLFormBuilder tool and imbedded in a task for a running job.
Note: Form definitions must be unique within a given job. Further, if the form has been previously saved, the most recent saved data initialize the current form field values.

Example

function getXMLForm(jobid, formid) {
     var params = {
         jobid: jobid, // job ID of currently selected task
         formid: formid: // form ID of currently selected task
     };
     SFformsApi.getXMlForm(params, handleGetXMlForm);
}

function handleGetXMlForm(result) {
     if ('0' === result.status) {
         $scope.jsonForm = result.jsonForm;
         if ($scope.jsonForm.formlabels) {
             for (var i=0; i < $scope.jsonForm.formlabels.length; i++) {
                 $scope.jsonForm.formfields.push($scope.jsonForm.formlabels[i]);
             }
         }
         if ($scope.jsonForm.formimages) {
             for (var j=0; j < $scope.jsonForm.formimages.length; j++) {
                 $scope.jsonForm.formfields.push($scope.jsonForm.formimages[j]);
             }
         }
         SFStorage.saveCurrentXmlForm($scope.jsonForm);
         $location.path('/formstask');
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object providing jobid and task id of the currently selected task.


var params = {
     jobid: [job ID of currently selected task],
     formid: formid [form ID]
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


 result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     jsonForm: {
         formfields: [], //array of form field definitions including Questionnaires
         formimages: [], //array of form images
         formlabels: []  // array of form labels
     }
};

getXMlFormIDs(params, successHandler[, failureHandler]) → object

Retrieves a list of the form IDs of a given job's completed forms.

Example

function getXMLFormIDs(jobid) {
     var params = {
         jobid: jobid // job ID of currently selected task
     };
     SFformsApi.getXMlFormIDs(params, handleGetXMlFormIDs);
}

function handleGetXMlFormIDs(result) {
     if ('0' === result.status) {
         $scope.formids = result.formids;
         $location.path('/formsdisplay');
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object providing the jobid of the currently selected task.


var params = {
     jobid: [job ID of currently selected task]
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


 result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     formids: [] //array of form ids
};

postXMLForm(params, successHandler[, failureHandler]) → object

Posts a given task form with its current settings
to the SmartFlo™ system.
Note: Form definitions must be unique with a given job.

Example

function getXMLForm(jobid, formid) {
     var params = {
         jobid: jobid, // job ID of currently selected task
         taskid: [task ID of currently selected task],
         formid: formid, // form ID of currently selected task
         formdata: JSON.stringify($scope.formdata) [form model]
     };
     SFformsApi.getXMlForm(params, handleGetXMlForm);
}

function handleGetXMlForm(result) {
     if ('0' === result.status) {
         $scope.errorCode = 0;
         $scope.feedbackMessage = $translate.instant('label.feedback.form.saved');
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object providing jobid and task id of the currently selected task.


var params = {
     jobid: [job ID of currently selected task],
     taskid: [task ID of currently selected task],
     formid: formid [form ID],
     formdata: JSON.stringify($scope.formdata) [form model]
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


 result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called]
};

renderFields(formfields, applicationStyles[, $translate])

Renders SmartFlo™ form field definitions
(returned by getXMLForm) into Formly field definitions.

Example

JavaScript Fragment:
if ($scope.taskFields) {
     var applicationStyles = new SFApplicationStyles('col-xs-6');
     applicationStyles.Label = '';
     applicationStyles.Image = '';
     $scope.taskFields = SFformsApi.renderFields($scope.taskFields, applicationStyles, $translate);
}

Formly HTML:
<form novalidate name="vm.taskform>
     <formly-form model="formdata" fields="taskFields" form="vm.taskform">
     </formly-form>
</form>

Parameters

Name Type Optional Description

formfields

array

 

An array of SmartFlo™ field definitions.

applicationStyles

object

 

An object containing optional .css styles that will be applied on a field type basis.


As a conveniance, SmartFlo™ provides a JavaScript class that will
initialize all field types with a common CSS class selector
string:

var applicationStyles = new SFApplicationStyles('col-xs-6');
applicationStyles = { TextInput: applicationStyles, TextArea: applicationStyles, CheckBox: applicationStyles, DateField: applicationStyles, ComboBox: applicationStyles, VRadioButtonGroup: applicationStyles, HRadioButtonGroup: applicationStyles, NumericStepper: applicationStyles, Label: applicationStyles, Image: applicationStyles, RBQuestionnaire: applicationStyles, CBQuestionnaire: applicationStyles };

$translate

function()

Yes

Optionally, the $translate function from the angular-translate AngularJS module. If passed, renderFields will call $translate.instant() on all defined field prompts for display purposes.