Class: Promise

PCCViewer.Promise

The PCCViewer.Promise object is an implementation of the Promises/A+ standard.

"A promise represents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through its then method, which registers callbacks to receive either a promise's eventual value or the reason why the promise cannot be fulfilled." -- Promises/A+ standard

The PrizmDoc Viewing Client API uses Promises as a means for a caller to subscribe callbacks for an asynchronous operation. This API uses promises as an alternative to the pattern of providing callbacks as arguments to the API method.

The PCCViewer.Promise object is compatible with other Promises/A+ implementations, and other non-conformant promise implementations, which are "thenable" (i.e. the promise exposes a .then() method).

Constructor

new Promise()

The Promise constructor is for internal use only. Promise objects returned by other API methods are created with this constructor.

Methods

(static) all(promises)

Returns a promise that is fulfilled when all of the input promises are fulfilled. The returned promise is fulfilled with an array of the fulfilment values for all of the input promises.

If any of the promises are rejected, then the returned promise will be rejected with the reason of that rejected promise. If rejected, there will be guarantee of the state all promises in the promises array, some have been resolved and some may still be pending.

Parameters:

Name Type Description

Name	Type	Description
`promises`	Array.<(PCCViewer.Promise\|thenable\|*)>	An array of values that will be resolved. If a value is not a PCCViewer.Promise object, then this method will create a new PCCViewer.Promise and fulfill it with the value. Resolution of various types is as follows. If the item is a PCCViewer.Promise, then the output value will be the fulfilment value of the promise. If the item is thenable, then the output value will be the fulfilment value of the thenable. Otherwise, the output value will be the item.

promises

Array.<(PCCViewer.Promise|thenable|*)>

An array of values that will be resolved. If a value is not a PCCViewer.Promise object, then this method will create a new PCCViewer.Promise and fulfill it with the value.

Resolution of various types is as follows.

If the item is a PCCViewer.Promise, then the output value will be the fulfilment value of the promise.
If the item is thenable, then the output value will be the fulfilment value of the thenable.
Otherwise, the output value will be the item.

Throws:

If the promises argument is not an array.

Type: TypeError

Example

var viewerControl = $("#myElement").pccViewer(...).viewerControl;

// Get page text for specific pages
PCCViewer.Promise.all([
    viewerControl.requestPageText(1),
    viewerControl.requestPageText(2)]).then(
    function onFulfilled(values) {
       // Values is an array that contains the text of pages 1 & 2.
       var page1Text = values[0];
       var page2Text = values[1];
    },
    function onRejected(error) {
        alert("Something went wrong getting the page text. " + (error.message ? error.message : error));
    }
);

// Get attributes for all pages
var allPages = _.range(1, viewerControl.getPageCount() + 1); // Using Underscore.js - generates an array like [1, 2, ..., 12]
var pageAttributePromises = _.map(allPages, viewerControl.requestPageAttributes, viewerControl); // Using Underscore.js
PCCViewer.Promise.all(pageAttributePromises).then(
    function onFulfilled(allPageAttributes) {
        console.log(JSON.stringify(allPageAttributes));
    },
    function onRejected(error) {
        alert("Something went wrong getting the page attributes. " + (error.message ? error.message : error));
    }
);

// it's OK to pass a value that is not a promise
PCCViewer.Promise.all([
    viewerControl.requestPageAttributes(1),
    true]).then(
    function(values) {
       // Values is an array that contains the text of pages 1 and the value `true`.
       var page1Text = values[0]; // text of page 1
       var otherValue = values[1]; // true
    }
);

(static) all(promises)

Returns a promise that is fulfilled when all of the input promises are fulfilled. The returned promise is fulfilled with an array of the fulfilment values for all of the input promises.

Parameters:

Name Type Description

Name	Type	Description
`promises`	Array.<(PCCViewer.Promise\|thenable\|*)>	An array of values that will be resolved. If a value is not a PCCViewer.Promise object, then this method will create a new PCCViewer.Promise and fulfill it with the value. Resolution of various types is as follows. If the item is a PCCViewer.Promise, then the output value will be the fulfilment value of the promise. If the item is thenable, then the output value will be the fulfilment value of the thenable. Otherwise, the output value will be the item.

promises

Array.<(PCCViewer.Promise|thenable|*)>

An array of values that will be resolved. If a value is not a PCCViewer.Promise object, then this method will create a new PCCViewer.Promise and fulfill it with the value.

Resolution of various types is as follows.

If the item is a PCCViewer.Promise, then the output value will be the fulfilment value of the promise.
If the item is thenable, then the output value will be the fulfilment value of the thenable.
Otherwise, the output value will be the item.

Throws:

If the promises argument is not an array.

Type: TypeError

Example

var viewerControl = $("#myElement").pccViewer(...).viewerControl;

// Get page text for specific pages
PCCViewer.Promise.all([
    viewerControl.requestPageText(1),
    viewerControl.requestPageText(2)]).then(
    function onFulfilled(values) {
       // Values is an array that contains the text of pages 1 & 2.
       var page1Text = values[0];
       var page2Text = values[1];
    },
    function onRejected(error) {
        alert("Something went wrong getting the page text. " + (error.message ? error.message : error));
    }
);

// Get attributes for all pages
var allPages = _.range(1, viewerControl.getPageCount() + 1); // Using Underscore.js - generates an array like [1, 2, ..., 12]
var pageAttributePromises = _.map(allPages, viewerControl.requestPageAttributes, viewerControl); // Using Underscore.js
PCCViewer.Promise.all(pageAttributePromises).then(
    function onFulfilled(allPageAttributes) {
        console.log(JSON.stringify(allPageAttributes));
    },
    function onRejected(error) {
        alert("Something went wrong getting the page attributes. " + (error.message ? error.message : error));
    }
);

// it's OK to pass a value that is not a promise
PCCViewer.Promise.all([
    viewerControl.requestPageAttributes(1),
    true]).then(
    function(values) {
       // Values is an array that contains the text of pages 1 and the value `true`.
       var page1Text = values[0]; // text of page 1
       var otherValue = values[1]; // true
    }
);

then(onFulfilledopt, onRejectedopt) → {PCCViewer.Promise}

Use .then(...) to register callbacks to access the current or eventual value, or reason, of the promise.

A promise is in one of three states: pending, resolved, rejected. The onFulfilled callback will be called when a promise is resolved, or if a promise is already resolved, then the onFulfilled callback will be called immediately. The onRejected callback will be called when a promise is rejected, or if a promise is already rejected, then the onRejected callback will be called immediately.

Parameters:

Name	Type	Attributes	Description
`onFulfilled`	PCCViewer.Promise~onFulfilled	<optional>	Called if or when the promise is resolved. Optionally pass a value of `null` or `undefined` if you do not use this callback, but you want to provide an onRejected callback.
`onRejected`	PCCViewer.Promise~onRejected	<optional>	Called if or when the promise is rejected.

Returns:

A promise object that is resolved according to the Promises/A+ standard.

Type: PCCViewer.Promise

Example

var viewerControl = $("#myElement").pccViewer(...).viewerControl;

// a basic example
viewerControl.requestPageText(1).then(
    function onFulfilled(value) {
       // according to the definition of requestPageText, the promise will be resolved with the text
       // of the page.
       var pageText = value;
    },
    function onRejected(error) {
        // according to the definition of requestPageText, the promise will be rejected if there is
        // an error extracting text for the document.
        alert("Something went wrong getting the text of page 1. " + (error.message ? error.message : error));
    }
);

// it's OK to pass a value of null (or undefined) for `onFulfilled`
viewerControl.requestPageText(1).then(
    null,
    function onRejected(error) { ... }
);

// it's OK to ignore the onRejected parameter, or pass null or undefined
viewerControl.requestPageText(1).then(
    function onFulfilled(value) { ... }
);

then(onFulfilledopt, onRejectedopt) → {PCCViewer.Promise}

Use .then(...) to register callbacks to access the current or eventual value, or reason, of the promise.

Parameters:

Name	Type	Attributes	Description
`onFulfilled`	PCCViewer.Promise~onFulfilled	<optional>	Called if or when the promise is resolved. Optionally pass a value of `null` or `undefined` if you do not use this callback, but you want to provide an onRejected callback.
`onRejected`	PCCViewer.Promise~onRejected	<optional>	Called if or when the promise is rejected.

Returns:

A promise object that is resolved according to the Promises/A+ standard.

Type: PCCViewer.Promise

Example

var viewerControl = $("#myElement").pccViewer(...).viewerControl;

// a basic example
viewerControl.requestPageText(1).then(
    function onFulfilled(value) {
       // according to the definition of requestPageText, the promise will be resolved with the text
       // of the page.
       var pageText = value;
    },
    function onRejected(error) {
        // according to the definition of requestPageText, the promise will be rejected if there is
        // an error extracting text for the document.
        alert("Something went wrong getting the text of page 1. " + (error.message ? error.message : error));
    }
);

// it's OK to pass a value of null (or undefined) for `onFulfilled`
viewerControl.requestPageText(1).then(
    null,
    function onRejected(error) { ... }
);

// it's OK to ignore the onRejected parameter, or pass null or undefined
viewerControl.requestPageText(1).then(
    function onFulfilled(value) { ... }
);

Type Definitions

onFulfilled(value)

An onFulfilled callback is called if or when a PCCViewer.Promise is resolved.

Parameters:

Name	Type	Description
`value`	*	The type and value of the `value` argument depends on the API method that generated the Promise object. See the documentation for the method that generated the Promise.

onFulfilled(value)

An onFulfilled callback is called if or when a PCCViewer.Promise is resolved.

Parameters:

Name	Type	Description
`value`	*	The type and value of the `value` argument depends on the API method that generated the Promise object. See the documentation for the method that generated the Promise.

onRejected(reason)

An onRejected callback is called if or when a PCCViewer.Promise is rejected.

Parameters:

Name	Type	Description
`reason`	*	The type and value of the `reason` argument depends on the API method that generated the Promise object. See the documentation for the method that generated the Promise.

onRejected(reason)

An onRejected callback is called if or when a PCCViewer.Promise is rejected.

Parameters:

Name	Type	Description
`reason`	*	The type and value of the `reason` argument depends on the API method that generated the Promise object. See the documentation for the method that generated the Promise.

PCCViewer.Promise

The PCCViewer.Promise object is an implementation of the Promises/A+ standard.

"A promise represents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through its then method, which registers callbacks to receive either a promise's eventual value or the reason why the promise cannot be fulfilled." -- Promises/A+ standard

Constructor

new Promise()

The Promise constructor is for internal use only. Promise objects returned by other API methods are created with this constructor.

Methods

(static) all(promises)

Returns a promise that is fulfilled when all of the input promises are fulfilled. The returned promise is fulfilled with an array of the fulfilment values for all of the input promises.

Parameters:

Name Type Description

Name	Type	Description
`promises`	Array.<(PCCViewer.Promise\|thenable\|*)>	An array of values that will be resolved. If a value is not a PCCViewer.Promise object, then this method will create a new PCCViewer.Promise and fulfill it with the value. Resolution of various types is as follows. If the item is a PCCViewer.Promise, then the output value will be the fulfilment value of the promise. If the item is thenable, then the output value will be the fulfilment value of the thenable. Otherwise, the output value will be the item.

promises

Array.<(PCCViewer.Promise|thenable|*)>

An array of values that will be resolved. If a value is not a PCCViewer.Promise object, then this method will create a new PCCViewer.Promise and fulfill it with the value.

Resolution of various types is as follows.

If the item is a PCCViewer.Promise, then the output value will be the fulfilment value of the promise.
If the item is thenable, then the output value will be the fulfilment value of the thenable.
Otherwise, the output value will be the item.

Throws:

If the promises argument is not an array.

Type: TypeError

Example

var viewerControl = $("#myElement").pccViewer(...).viewerControl;

// Get page text for specific pages
PCCViewer.Promise.all([
    viewerControl.requestPageText(1),
    viewerControl.requestPageText(2)]).then(
    function onFulfilled(values) {
       // Values is an array that contains the text of pages 1 & 2.
       var page1Text = values[0];
       var page2Text = values[1];
    },
    function onRejected(error) {
        alert("Something went wrong getting the page text. " + (error.message ? error.message : error));
    }
);

// Get attributes for all pages
var allPages = _.range(1, viewerControl.getPageCount() + 1); // Using Underscore.js - generates an array like [1, 2, ..., 12]
var pageAttributePromises = _.map(allPages, viewerControl.requestPageAttributes, viewerControl); // Using Underscore.js
PCCViewer.Promise.all(pageAttributePromises).then(
    function onFulfilled(allPageAttributes) {
        console.log(JSON.stringify(allPageAttributes));
    },
    function onRejected(error) {
        alert("Something went wrong getting the page attributes. " + (error.message ? error.message : error));
    }
);

// it's OK to pass a value that is not a promise
PCCViewer.Promise.all([
    viewerControl.requestPageAttributes(1),
    true]).then(
    function(values) {
       // Values is an array that contains the text of pages 1 and the value `true`.
       var page1Text = values[0]; // text of page 1
       var otherValue = values[1]; // true
    }
);

(static) all(promises)

Returns a promise that is fulfilled when all of the input promises are fulfilled. The returned promise is fulfilled with an array of the fulfilment values for all of the input promises.

Parameters:

Name Type Description

Name	Type	Description
`promises`	Array.<(PCCViewer.Promise\|thenable\|*)>	An array of values that will be resolved. If a value is not a PCCViewer.Promise object, then this method will create a new PCCViewer.Promise and fulfill it with the value. Resolution of various types is as follows. If the item is a PCCViewer.Promise, then the output value will be the fulfilment value of the promise. If the item is thenable, then the output value will be the fulfilment value of the thenable. Otherwise, the output value will be the item.

promises

Array.<(PCCViewer.Promise|thenable|*)>

An array of values that will be resolved. If a value is not a PCCViewer.Promise object, then this method will create a new PCCViewer.Promise and fulfill it with the value.

Resolution of various types is as follows.

If the item is a PCCViewer.Promise, then the output value will be the fulfilment value of the promise.
If the item is thenable, then the output value will be the fulfilment value of the thenable.
Otherwise, the output value will be the item.

Throws:

If the promises argument is not an array.

Type: TypeError

Example

var viewerControl = $("#myElement").pccViewer(...).viewerControl;

// Get page text for specific pages
PCCViewer.Promise.all([
    viewerControl.requestPageText(1),
    viewerControl.requestPageText(2)]).then(
    function onFulfilled(values) {
       // Values is an array that contains the text of pages 1 & 2.
       var page1Text = values[0];
       var page2Text = values[1];
    },
    function onRejected(error) {
        alert("Something went wrong getting the page text. " + (error.message ? error.message : error));
    }
);

// Get attributes for all pages
var allPages = _.range(1, viewerControl.getPageCount() + 1); // Using Underscore.js - generates an array like [1, 2, ..., 12]
var pageAttributePromises = _.map(allPages, viewerControl.requestPageAttributes, viewerControl); // Using Underscore.js
PCCViewer.Promise.all(pageAttributePromises).then(
    function onFulfilled(allPageAttributes) {
        console.log(JSON.stringify(allPageAttributes));
    },
    function onRejected(error) {
        alert("Something went wrong getting the page attributes. " + (error.message ? error.message : error));
    }
);

// it's OK to pass a value that is not a promise
PCCViewer.Promise.all([
    viewerControl.requestPageAttributes(1),
    true]).then(
    function(values) {
       // Values is an array that contains the text of pages 1 and the value `true`.
       var page1Text = values[0]; // text of page 1
       var otherValue = values[1]; // true
    }
);

then(onFulfilledopt, onRejectedopt) → {PCCViewer.Promise}

Use .then(...) to register callbacks to access the current or eventual value, or reason, of the promise.

Parameters:

Name	Type	Attributes	Description
`onFulfilled`	PCCViewer.Promise~onFulfilled	<optional>	Called if or when the promise is resolved. Optionally pass a value of `null` or `undefined` if you do not use this callback, but you want to provide an onRejected callback.
`onRejected`	PCCViewer.Promise~onRejected	<optional>	Called if or when the promise is rejected.

Returns:

A promise object that is resolved according to the Promises/A+ standard.

Type: PCCViewer.Promise

Example

var viewerControl = $("#myElement").pccViewer(...).viewerControl;

// a basic example
viewerControl.requestPageText(1).then(
    function onFulfilled(value) {
       // according to the definition of requestPageText, the promise will be resolved with the text
       // of the page.
       var pageText = value;
    },
    function onRejected(error) {
        // according to the definition of requestPageText, the promise will be rejected if there is
        // an error extracting text for the document.
        alert("Something went wrong getting the text of page 1. " + (error.message ? error.message : error));
    }
);

// it's OK to pass a value of null (or undefined) for `onFulfilled`
viewerControl.requestPageText(1).then(
    null,
    function onRejected(error) { ... }
);

// it's OK to ignore the onRejected parameter, or pass null or undefined
viewerControl.requestPageText(1).then(
    function onFulfilled(value) { ... }
);

then(onFulfilledopt, onRejectedopt) → {PCCViewer.Promise}

Use .then(...) to register callbacks to access the current or eventual value, or reason, of the promise.

Parameters:

Name	Type	Attributes	Description
`onFulfilled`	PCCViewer.Promise~onFulfilled	<optional>	Called if or when the promise is resolved. Optionally pass a value of `null` or `undefined` if you do not use this callback, but you want to provide an onRejected callback.
`onRejected`	PCCViewer.Promise~onRejected	<optional>	Called if or when the promise is rejected.

Returns:

A promise object that is resolved according to the Promises/A+ standard.

Type: PCCViewer.Promise

Example

var viewerControl = $("#myElement").pccViewer(...).viewerControl;

// a basic example
viewerControl.requestPageText(1).then(
    function onFulfilled(value) {
       // according to the definition of requestPageText, the promise will be resolved with the text
       // of the page.
       var pageText = value;
    },
    function onRejected(error) {
        // according to the definition of requestPageText, the promise will be rejected if there is
        // an error extracting text for the document.
        alert("Something went wrong getting the text of page 1. " + (error.message ? error.message : error));
    }
);

// it's OK to pass a value of null (or undefined) for `onFulfilled`
viewerControl.requestPageText(1).then(
    null,
    function onRejected(error) { ... }
);

// it's OK to ignore the onRejected parameter, or pass null or undefined
viewerControl.requestPageText(1).then(
    function onFulfilled(value) { ... }
);

Type Definitions

onFulfilled(value)

An onFulfilled callback is called if or when a PCCViewer.Promise is resolved.

Parameters:

Name	Type	Description
`value`	*	The type and value of the `value` argument depends on the API method that generated the Promise object. See the documentation for the method that generated the Promise.

onFulfilled(value)

An onFulfilled callback is called if or when a PCCViewer.Promise is resolved.

Parameters:

Name	Type	Description
`value`	*	The type and value of the `value` argument depends on the API method that generated the Promise object. See the documentation for the method that generated the Promise.

onRejected(reason)

An onRejected callback is called if or when a PCCViewer.Promise is rejected.

Parameters:

Name	Type	Description
`reason`	*	The type and value of the `reason` argument depends on the API method that generated the Promise object. See the documentation for the method that generated the Promise.

onRejected(reason)

An onRejected callback is called if or when a PCCViewer.Promise is rejected.

Parameters:

Name	Type	Description
`reason`	*	The type and value of the `reason` argument depends on the API method that generated the Promise object. See the documentation for the method that generated the Promise.