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).
|Representation||Method for URL String||Method for Loaded Element|
|Grid of thumbnail images for multiple Document pages||GetThumbnailsGridUrl||GetThumbnailsGridElement|
|Thumbnail for a single DocumentPage||GetThumbnailImageUrl||GetThumbnailImageElement|
|Raster image for a page||GetImageUrl||GetImageElement|
|Resized (proportionally) raster image for a page||GetImageResizedUrl||GetImageResizedElement|
|SVG image for a page||GetSvgUrl||GetSvgElement|
|Background raster image to match the SVG image for a page||GetSvgBackImageUrl||GetSvgBackImageElement|
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 the image will be loaded with AJAX.
If loading via AJAX, ElementAjaxMethod will be used to specify if the load is a
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 resulting image should be available from the Promise when the ImageLoader completes.
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.
It is important to note that if an ImageLoader is provided, only the Url is 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.
These methods involving image loading make use of caching. The following checks are done in order to ensure the fastest response time.
The browser's cache, if enabled, is automatically used for duplicate requests of the exact same URL (excluding
If an item was found in the LEADTOOLS service cache, it is returned right away.
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.
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.