Loading HTML or SVG Elements - Namespace - HTML5 JavaScript Help

Loading HTML or SVG Elements

Summary

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

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.

Help Version 20.0.2018.7.3
Products | Support | Contact Us | Copyright Notices
© 1991-2018 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS HTML5 JavaScript