Loading HTML or SVG Elements

This topic discusses the technical side of loading HTML or SVG Elements that represent images for a DocumentPage. For a discussion of loading a Document instead of individual page images or thumbnails, see Document Loading.

Some methods of DocumentPage and DocumentImages allow the user to get the URL pointing to a representation of the page or pages of the document. Additionally, some methods use that URL to load the HTML or SVG Element from the endpoint and return it as part of a Promise object. This has the benefit of triggering the PrepareAjax event for AJAX requests and allowing the use of ServiceUserData (or ServiceUserData).

When calling these methods to retrieve an HTML or SVG Element, default values for the options of the image load are retrieved from ElementUrlMode and, if AJAX, ElementAjaxMethod.

The methods that return an HTML or SVG Element call the method to retrieve the URL internally, then load the image with an ImageLoader instance. ElementUrlMode is used for the value of UrlMode, determining whether or not the image will be loaded with AJAX.

If loading via AJAX, ElementAjaxMethod will be used to specify if the load is a GET or POST. PrepareAjax will be called as it is with all other AJAX methods, and the image load can be canceled with Cancel. After all the callbacks for PrepareAjax have run, any modified settings are returned to the ImageLoader and Run is called. The result image should be available from the Promise when the ImageLoader completes.

Providing an ImageLoader as a Parameter

Each method takes an optional ImageLoader parameter to allow the user more control over the image loading process. In this case, an internal ImageLoader is not created.

• The user may add callbacks to any of PreRun, Done, Fail, or Always.
• The values from ElementUrlMode and ElementAjaxMethod will not be used. Those values will be kept from the provided UrlMode and Method, respectively.
• The ImageLoader will not be run immediately. All the necessary values and functions for the image load will be stored in the ImageLoader instance that was originally passed, and the user may execute the load with Run at any time.

It is important to note that if an ImageLoader is provided, only the Url will be set immediately. All the other settings, including the hook for PrepareAjax, take place within a PreRun event callback. Done and Fail callbacks are also added to resolve the Promise. For this reason, the order of adding callbacks to PreRun, Done, and Fail matters with respect to calling the element loading method. For example, a user should not add a PreRun callback before calling the element loading method if that callback will attempt to read the settings for the image load - those settings will not exist yet. Instead, attach the callback after calling the element loading method.

Caching

These methods involving image loading make use of caching. The following checks are done in order to ensure the fastest response time.

1. The browser's cache, if enabled, is automatically used for duplicate requests of the exact same URL (excluding POST requests).

2. If an item was found in the LEADTOOLS service cache, it is returned right away.

3. If this is an original page in the source document file (the value of OriginalPageNumber is not -1), then the image object is loaded from the original page. The image object is saved to the cache before it is returned. Next time this method is called, the image will be returned from the cache directly without loading it from the file or creating a new instance.

4. If this is not an original page in the source document file (the value of OriginalPageNumber is not 1), then a new image object is created based on the page size and resolution and the default values in DocumentImages. The image object is saved to the cache before it is returned. Next time this method is called, the image will be returned from the cache directly without loading it from the file or creating a new instance.

Reference

Documents Library Features

Documents Viewer Application

Loading Documents Using LEADTOOLS Documents Library

Creating Documents with LEADTOOLS Documents Library

Document Toolkit and Caching

Uploading Using the Documents Library

Documents Library Coordinate System

Loading Encrypted Files Using the Documents Library

Parsing Text with the Documents Library

Barcode processing with the Documents Library

Using jQuery Promises in the Documents Library

Using LEADTOOLS Document Viewer