In This Topic ▼

Using jQuery Promises in the Document Library

Operations to contact the LEADTOOLS Document Service return a jQuery Promise object that must be used to act on events from the service call. The done, fail, progress, and always methods are used to attach event handlers to events.

The Done Promise callback is used to run a function when a service call has completed successfully. In most situations, the done callback function will include as a parameter the requested data from the Document Service. For example, getText will return a Promise for a DocumentPageText object.

In addition, if the Document Service is configured to return other arbitrary user data, that data will be available as a second parameter to the Done callback function. See DocumentFactory.ServiceUserData and LEADDocument.ServiceUserData for more information.
Use the Fail Promise callback to run a function when a service call has failed. More information about the fail callback is in the next section.
Use the Always Promise callback to run a function after the service call is completed, regardless of the result. The always callback is often used to clean up resources. No parameters are provided to the always callback.
The Progress Promise callback is only used for uploading files and returns a DocumentUploadProgress object with the state and progress of the overall upload. See UploadFile, UploadFileDocument, UploadDocumentBlob, and UploadDocument for more information and examples.

The `Fail` Callback

If an error occurs during any service call, the fail callback handler will execute all registered functions with the three parameters normally returned by a failed jQuery Ajax call:

The jqXHR (jQuery XMLHttpRequest) object, which is a superset of the native XMLHttpRequest object.
The textStatus string, which describes the type of error that occurred ("timeout", "error", etc.).
The errorThrown string, which could be the textual portion of an HTTP Status (like "Internal Server Error") if it is available, a general error message, or null.

If the error occurred within the Document Service, all three of these parameters should have values. If the error occurred while parsing or delivering the data, only errorThrown, the third argument, will have a value. If an UploadFile service call was aborted using the special abort method, all the parameters to the fail callback will be null.

The jqXHR object, if not null, may contain data used for creating a ServiceError object, which would include debugging information and messages to be displayed to the user. For more information, see ParseError. If an error occurs, the value sent through the request will be set in the ServiceError.UserData property of the object returned from ParseError.

The jQuery Promise object is a subset of the jQuery Deferred object. Refer to the jQuery documentation for more information on Promises and the Deferred object.

The PrepareAjax event occurs before any request made by the document library client-side code to the server. This allows users to examine or modify the parameters passed. The event data contains detailed information on the call as well as the JQueryAjaxSettings object being used. Any changes made to that object will be used in the request. For example, this will allow users to modify the headers of any request to set authorization headers as they wish.

The Document Service supports a "Service Heartbeat" feature. The defaults for this feature can be configured from each client application's "serviceConfig.json" file in the "heartbeatDefaults". If a timeout occurs, the IsTimeoutError value will be set to true.