The viewer collection invokes the IViewerCardInstance.cardLoadItem method when a viewer type should load a new queue item. This page describes how to call this method, and handle cancellations and errors.
This page contains the following information:
The IViewerCardInstance.cardLoadItem method has these parameters described in the following sections:
The item parameter specifies a IQueueItem object for loading into the viewer type. It is the queue item that the viewer type display. Viewer types may use metadata exposed on the item object to make API calls, or they may render the item inside the viewer card.
For reference content, see IQueueItem.
The options parameter specifies a set of options used during loading. For reference content, see ILoadOptions.
The following sections describe these options:
The cancellationToken option is a cancellation token of type ICancellationToken used for the load operation. For information about using this parameter, see Handling Cancellation.
The reloadRequired option is a Boolean value indicating whether to reload the content. See the following sample use cases:
Example 1 - A user switches between the custom viewer type and the Image Viewer for a queue item. You don't need to reload the queue item in the custom viewer type when the user switches the active viewer type.
In this example, the viewer collection passes false as the value of reloadRequired.
Example 2 - A user loads the first queue item in the custom viewer type, switches to the Image Viewer, and begins reviewing documents in the Image Viewer only. After a few minutes, the user navigates back to the first item in the queue and switches back to the custom viewer type. The custom viewer has the correct queue item loaded, but the data may be stale. In this example, the viewer collection passes true as the value of reloadRequired.
The longTextFieldArtifactId option is of type Number or undefined. It is the Artifact ID for a long text field that the queue pointer is currently using. This property may be undefined if no long text field has been selected.
Note: This property can be ignored unless the custom viewer type needs to render data from long text fields.
The productionArtifactId option is of type Number or undefined. It is the Artifact ID for the production that the queue pointer is currently using. This property may be undefined if no production has been selected.
Note: This property can be ignored unless the custom viewer type needs to render data with produced images.
When navigation is requested, the viewer collection cancels any in-flight load operations. It does so by requesting cancellation with a cancellationToken object.
If cancellation is requested before a load is complete, the cardLoadItem() method should resolve the returned Promise with false.
Check for a cancellation request using one of following three options:
cardLoadItem().)Check for a token cancellation after completing asynchronous operations. This approach ensures that slow-running asynchronous operations aren't improperly handled after a subsequent load operation completed.
For example, a load operation begins, and a viewer makes a slow asynchronous HTTP call for data. Before the HTTP call response is retrieved, the user requests another navigation, and a second load operation begins. If the HTTP call for the second load operation completes before the first HTTP call, then the viewer code should ignore the response from the first HTTP call. This action prevents improperly displaying the document from the first load operation.
The following sample code illustrates how to use the cancellation token when performing asynchronous operations:
function cardLoadItem(item, options) {
return new Promise(function (resolve, reject) {
performAsyncHttpCall(item).then(function (results) {
// Check for a cancellation.
if (options.cancellationToken.isCancellationRequested) {
resolve(false);
return;
}
// Use retrieved results to render new content here.
});
});
}Ensure that your custom viewer types handle errors appropriately. Inform the users about errors to prevent them from reviewing the wrong content.
Custom viewer types should perform the following actions to handle errors that occur in the cardLoadItem() method:
Update the viewer content to display an error.
For example, if the user was quickly navigating and the load operation for last navigation fails, update the content in the viewer card to indicate an error occurred. Otherwise, the user doesn't know that the content from one of the intermediate navigation steps isn't associated with other UI components, such as the coding layout or family documents.
Reject the Promise returned by cardLoadItem() with an Error object containing a descriptive message.
Completing this step ensures that the IViewerCollection.contentType API correctly returns the viewererror, indicating to other extension components that the user is currently viewing a successfully loaded document.
Note: Don't throw an error when the load operation is cancelled. We recommend that custom viewer types don't use ICancellationToken.throwIfCancellationRequested to check token cancellation in the cardLoadItem() method.