PrizmDoc Viewer v13.18 Release - Updated
API Reference / Viewer Control / Namespace: PCCViewer / Class: ConversionRequest
In This Topic
    Class: ConversionRequest
    In This Topic

    PCCViewer. ConversionRequest

    (protected) new ConversionRequest()

    The ConversionRequest object is created when converting a document using PCCViewer.ViewerControl#requestDocumentConversion.

    The ConversionRequest is a thenable object, which allows Promise-like interactions. Calling the PCCViewer.ConversionRequest#then method will return a PCCViewer.Promise object. On successful conversion, the Promise success method, if added, is called with an array of the urls to download the converted documents. Note that it currently only supports converting to a single PDF file, so the output array will only contain a single URL. On a conversion failure, the Promise is rejected.

    Note that if you create a ConversionRequest object using the PCCViewer.ViewerControl#convertDocument method, which has been marked as deprecated, the Promise success method is called with a single URL string (not an array of URL strings).

    The ConversionRequest object also provides an event subscription method, to get notified of other types of information. See PCCViewer.ConversionRequest.EventType.

    Note: This constructor should not be used directly. Instead, a ConversionRequest is created by a call to PCCViewer.ViewerControl#requestDocumentConversion.

    Example

    function onSuccessfulConvert(convertedDocumentUrls) {
       alert("The first converted document url: " + convertedDocumentUrls[0]);
    }
    
    function onFailedConvert(error) {
      alert("conversion process failed, reason: " + (error.message ? error.message : error));
    }
    
    // A ConversionRequest object is created by and returned from the call to the ViewerControl#requestDocumentConversion method
    var conversionRequest = viewerControl.requestDocumentConversion();
    conversionRequest.then(onSuccessfulConvert, onFailedConvert);
    
    //register some events
    conversionRequest
      .on(PCCViewer.ConversionRequest.EventType.ConversionCompleted,
          function(ev) {
              alert("Document conversion completed.");
          })
      .on(PCCViewer.ConversionRequest.EventType.ConversionProgress,
          function(event) {
              alert("Conversion progress: " + event.percent + "%");
          })
      .on(PCCViewer.ConversionRequest.EventType.ConversionFailed,
          function(event) {
              alert("Document conversion failed.");
          });
    

    Members

    (static, readonly) EventType :string

    A list of events that can be triggered by the PCCViewer.ConversionRequest object.

    Note: This enumeration is for convenience for API developers. Instead of using this enumeration, you can pass string values of the eventType (enumeration values)

    Type:

    • string

    Properties:

    Name Description
    ConversionProgress : string

    Triggered when the conversion process receives an update.

    Augmented properties of the PCCViewer.Event object for this event:

    • progress {number} - Indicates the estimated percentage complete.
    ConversionCompleted : string

    Triggered when the conversion process completes successfully, fails to complete, or is cancelled.

    Augmented properties of the PCCViewer.Event object for this event: None

    ConversionFailed : string

    Triggered when the conversion process fails.

    Augmented properties of the PCCViewer.Event object for this event: None

    ConversionCancelled : string

    Triggered when user cancels the conversion process.

    Augmented properties of the PCCViewer.Event object for this event: None

    ConversionWorkerCreated : string

    Triggered when the conversion process is created by the backend conversion service.

    Augmented properties of the PCCViewer.Event object for this event: None

    See:

    (readonly) convertedDocumentDownloadURLs :string|null

    Gets the URLs for downloading each converted document after successful conversion.

    This property is defined on all ConversionRequest objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Type:

    • string | null
    See:

    Example

    var downloadUrls = conversionRequest.convertedDocumentDownloadURLs;
    

    (readonly) errorCode :number

    Gets the errorCode if there is a failure during conversion process.

    This property is defined on all ConversionRequest objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Type:

    • number
    See:

    Example

    var errorCode = conversionRequest.errorCode;
    

    (readonly) options :Object

    Gets the options that were provided/used to convert the document.

    This property is defined on all ConversionRequest objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Type:

    • Object
    See:

    Example

    var options = conversionRequest.options;
    

    (readonly) progress :number

    Gets the current estimate of the conversion process progress.

    This property is defined on all ConversionRequest objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Type:

    • number
    See:

    Example

    var percentProgress = conversionRequest.progress;
    

    (readonly) workerID :number

    Gets the worker ID.

    This property is defined on all ConversionRequest objects.

    This is an ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8. For the greatest browser compatibility, use the corresponding getter and setter methods.

    Type:

    • number
    See:

    Example

    var percentProgress = conversionRequest.workerID;
    

    Methods

    cancel() → {PCCViewer.ConversionRequest}

    Cancels the conversion request. The PCCViewer.Promise object that is returned will be rejected. If the user cancels the operation, then a PCCViewer.Error object will be returned as the rejection reason and its code property will be set to UserCancelled.

    Returns:

    The cancelled request.

    Type
    PCCViewer.ConversionRequest

    Example

    var conversionRequest = viewerControl.requestDocumentConversion();
    conversionRequest.cancel();
    

    getConvertedDocumentDownloadURL()

    Deprecated since v11.0 (use the PCCViewer.ConversionRequest#getConvertedDocumentDownloadURLs method instead).

    getConvertedDocumentDownloadURLs() → {string|null}

    Gets the URLs for a web tier service to download each converted document.

    Returns:

    Returns an array of URLs to download the converted documents. If called before the process completes, or after the process fails, it will return null.

    Type
    string | null

    Example

    var conversionRequest = viewerControl.requestDocumentConversion();
    var convertedUrls = conversionRequest.getConvertedDocumentDownloadURLs();
    

    getErrorCode() → {string}

    Gets the error code for the conversion request, in cases where the request has failed.

    Returns:

    A value for programmatic identification of an error condition, or null if an error has not occurred.

    Type
    string

    Example

    var conversionRequest = viewerControl.requestDocumentConversion();
    var errorCode = conversionRequest.getErrorCode();
    

    getOptions() → {Object}

    Gets a copy of the options object used by the conversion request.

    The original options object has been provided to the method PCCViewer.ViewerControl#requestDocumentConversion. If no options object was provided to requestDocumentConversion, or the options object did not define all properties, then the returned object will represent the actual options used.

    Returns:

    A copy of the conversion options object which is used by this conversion request.

    • targetExtension {string} - (optional) Whether to convert the signatures.
    • filename {string} - (optional) The format to which the document will be converted.
    Type
    Object

    Example

    var conversionRequest = viewerControl.requestDocumentConversion();
    var options = conversionRequest.getOptions();
    

    getProgress() → {number}

    Gets the currently known conversion progress value.

    Returns:

    A number between 0 and 100 (inclusive). A value of 100 means the conversion process completed.

    Type
    number

    Example

    var conversionRequest = viewerControl.requestDocumentConversion();
    var percent = conversionRequest.getProgress();
    

    getWorkerID() → {string|null}

    Gets the ID of the PCCIS ContentConverter performing conversion.

    Returns:

    The ID of the PCCIS ContentConverter performing conversion. Returns null before the worker is created.

    Type
    string | null

    Example

    var conversionRequest = viewerControl.requestDocumentConversion();
    var workerId = conversionRequest.getWorkerID();
    

    off(eventType, handler) → {PCCViewer.ConversionRequest}

    Unsubscribe an event handler from a specified event type.

    Typically, an event is unsubscribed when you no longer want further notification of the event.

    Parameters:

    Name Type Description
    eventType string

    A string specifying the event type. See PCCViewer.ConversionRequest.EventType for a list and description of all supported events.

    handler PCCViewer.Event~eventHandler

    A function that was attached previously to the ViewerControl.

    Note: This must be the same function object previously passed to PCCViewer.ConversionRequest#on. It cannot be a different object that is functionally equivalent.

    See:

    Returns:

    The ConversionRequest object on which this method was called.

    Type
    PCCViewer.ConversionRequest

    on(eventType, handler) → {PCCViewer.ConversionRequest}

    Subscribe an event handler to an event of a specified type.

    Parameters:

    Name Type Description
    eventType string

    A string that specifies the event type. This value is case-insensitive. See PCCViewer.ConversionRequest.EventType for a list and description of all supported events.

    handler PCCViewer.Event~eventHandler

    A function that will be called whenever the event is triggered.

    See:

    Returns:

    The ConversionRequest object on which this method was called.

    Type
    PCCViewer.ConversionRequest

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

    Register callbacks to access the current or eventual result of the ConversionRequest.

    On successful conversion, the onFulfilled callback(s) are called with the URL to download the converted document.

    On a conversion failure, the onRejected callback(s) are called with a PCCViewer.Error.

    Multiple onFulfilled or onRejected callbacks can be registered for the same ConversionRequest by calling this method multiple times.

    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.requestDocumentConversion().then(
        function onFulfilled(url) {
           // download document using `url`
        },
        function onRejected(error) {
            // Handle failure
        }
    );
    

    Documentation generated by JSDoc 3.3.3 on Fri Sep 10 2021 12:15:35 GMT-0400 (Eastern Daylight Time)