Using jQuery Promises in the Documents Library

Summary

Operations to contact the LEADTOOLS Documents 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 Documents Service. For example, GetText will return a Promise for an DocumentPageText object.

In addition, if the Documents Service is configured to return other arbitrary user data, that data will be available as a second parameter to the Done callback function. See ServiceUserData and ServiceUserData for more information.
The Fail Promise callback is used to run a function when a service call has failed. A further discussion of the fail callback is located below.
The Always Promise callback is used 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 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 Documents 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 a UploadFile service call was aborted using the special abort method, all of 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.

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 documents library client-side code to the server. This allows the user 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 a user to modify the headers of any request to set authorization headers as they wish.