ImageLoaderUrlMode Enumeration

Summary

Specifies the mode by which the image or XML will be loaded.

Syntax
TypeScript
JavaScript
lt.ImageLoaderUrlMode = { 
	imageUrl: 0, 
	ajaxDataUrl: 1, 
	ajaxXml: 2 
} 
lt.ImageLoaderUrlMode = { 
	imageUrl: 0, 
	ajaxDataUrl: 1, 
	ajaxXml: 2 
} 
Members
ValueMemberDescription
0ImageUrlSet the url to the src attribute of the workingImageElement. This is the typical way to load an HTML Image Element.
1AjaxDataUrlUse an XMLHttpRequest (via xhr) to load the image or SVG as binary data.
2AjaxXmlUse an XMLHttpRequest (via xhr) to load the image or SVG directly.
Remarks

Use ImageLoaderUrlMode with the urlMode property. The chosen enumeration value dictates how the url will be loaded to create the resulting element.

There are three distinct ways an image can be loaded:

imageUrl

ajaxDataUrl

ajaxXml

Description

imageUrl loads an image the way most people would expect: by creating a new HTML Image Element and setting the src attribute of that element to the url property. This method works best for loading web-safe images quickly.

ajaxDataUrl loads an image using XMLHttpRequest, and thus supports appending headers and additional data (if POST) to the request. These additional options are available through an ImageLoaderAjaxOptions object on ajaxOptions. The data is always requested in binary format, so additional time is necessary to convert the data into a viewable form.

ajaxXml loads XML using XMLHttpRequest, meaning it also supports the options from ajaxOptions. This method is the only one that will load SVG in its full format, instead of as an SVG-as-IMG (with the HTML Image Element holding the SVG). As the name implies, arbitrary XML can also be loaded, though normal web-safe image file types cannot.

For Images

imageUrl is the best option for loading web-safe image file types. This method works in every browser and is the fastest.

ajaxDataUrl will request the image as binary data. In most cases, loading will be slower as the data must be converted to a Blob type and then reloaded. This method does, however, hold the advantage of allowing AJAX customization in the form of headers and data via ImageLoaderAjaxOptions in an ajaxOptions object. You can also view and modify the returned binary data with processAjaxData.

ajaxXml will fail for normal web-safe images, since it expects XML. However, should the url point to a server that can return an SVG element as a wrapper to the image as its only child, the ImageLoader will be able to load and return only that image as an HTML Image Element. In this case, the image inside the SVG can be either embedded or linked.

For SVG

imageUrl loads an SVG inside of an HTML Image Element. For browser security reasons, any images inside the SVG must not be linked images.

The SVG image renders quickly, but memory consumption can be high and native SVG functions (such as text selection) are lost.

ajaxDataUrl also loads SVG inside of an HTML Image Element, using AJAX. The data is returned as binary, so additional processing time is required. As with imageUrl, any images inside the SVG must not be linked images.

The SVG image renders quickly, but memory consumption can be high and native SVG functions (such as text selection) are lost.

ajaxXml loads the SVG in its native XML format, using AJAX. This format works in all browsers, but rendering can be slow and the DOM can become congested.

SVG will have all native functionality, such as attribute editing and text selection.

For XML

imageUrl fails when trying to load XML.

ajaxDataUrl fails when trying to load XML.

ajaxXml allows XML to be retrieved from an endpoint via AJAX, though with the same caveats as loading an SVG: slow rendering and a much larger DOM size.

If the URL to be loaded is a data URL, it will always be loaded as ImageLoaderUrlMode.imageUrl.

Example
ImageLoader.ts
ImageLoader.js
ImageLoader.html
export class ImageLoaderExample { 
   // We will show the results of loading a raster web image and SVG in all three supported loading modes. 
   // Insert URLs to raster (GIF, PNG, JPG) and SVG images below. The images must have CORS properties for AJAX. 
   private imageRasterUrl: string = "http://demo.leadtools.com/images/gif/clock.gif"; 
   private imageSvgUrl: string = "http://demo.leadtools.com/images/svg/lazio.svg"; 
 
   constructor() { 
      lt.RasterSupport.setLicenseUri("https://demo.leadtools.com/licenses/js/LEADTOOLSEVAL.txt", "EVAL", null); 
   } 
 
   public run = () => { 
      const targets = [ 
         // Raster images 
         { parent: "rasterImageUrl", mode: lt.ImageLoaderUrlMode.imageUrl, url: this.imageRasterUrl }, 
         { parent: "rasterAjaxDataUrl", mode: lt.ImageLoaderUrlMode.ajaxDataUrl, url: this.imageRasterUrl }, 
         { parent: "rasterAjaxXml", mode: lt.ImageLoaderUrlMode.ajaxXml, url: this.imageRasterUrl }, 
         // SVG images 
         { parent: "svgImageUrl", mode: lt.ImageLoaderUrlMode.imageUrl, url: this.imageSvgUrl }, 
         { parent: "svgAjaxDataUrl", mode: lt.ImageLoaderUrlMode.ajaxDataUrl, url: this.imageSvgUrl }, 
         { parent: "svgAjaxXml", mode: lt.ImageLoaderUrlMode.ajaxXml, url: this.imageSvgUrl }, 
      ]; 
      targets.forEach((target) => { 
         const imageLoader: lt.ImageLoader = new lt.ImageLoader(); 
         imageLoader.urlMode = target.mode; 
         imageLoader.url = target.url; 
 
         // If we're loading with AJAX, attach a header or even change to a POST request (endpoint must have proper CORS properties) 
         //if (target.mode === lt.ImageLoaderUrlMode.ajaxDataUrl || target.mode === lt.ImageLoaderUrlMode.ajaxXml) { 
         //imageLoader.ajaxOptions.headers["myKey"] = "myValue"; 
         //imageLoader.ajaxOptions.method = "POST"; 
         //imageLoader.ajaxOptions.headers["contentType"] = "application/json"; 
         //imageLoader.ajaxOptions.postData = JSON.stringify({ key: "value" }); 
         //} 
         imageLoader.preRun.add(this.preRun); 
         imageLoader.done.add(this.done); 
         imageLoader.fail.add(this.fail); 
         imageLoader.always.add(this.always); 
 
         // Add the target ID to the loader so we can use it in our callbacks easily 
         imageLoader["parent"] = target.parent; 
         imageLoader.run(); 
      }); 
   } 
 
   // Before the imageLoader is run, we can do what we like. 
   public preRun(imageLoader, preRunEventArgs): void { 
      // Optional: we can set "abort" to true to make the imageLoader fail. 
      //preRunEventArgs.cancel = true; 
      console.log("ImageLoader about to run: " + imageLoader.url); 
   } 
 
   // When we're done, append the image to our page. 
   public done(imageLoader): void { 
      // For this example, we set an extra property as a target ID. 
      const parent = document.getElementById(imageLoader["parent"]); 
      const textElement = document.createElement("p"); 
      textElement.innerHTML = (imageLoader.isHTMLImageElement ? "<img>" : "<svg>") + " width: " + imageLoader.width + ", height: " + imageLoader.height; 
      parent.appendChild(imageLoader.element); 
      parent.appendChild(textElement); 
   } 
 
   // If we failed, show the error. 
   public fail(imageLoader): void { 
      const parent = document.getElementById(imageLoader["parent"]); 
      const textElement = document.createElement("p"); 
      textElement.innerHTML = imageLoader.error; 
      parent.appendChild(textElement); 
      console.error(imageLoader.error); 
   } 
 
   // Do some cleanup, regardless of the result 
   public always(imageLoader): void { 
      imageLoader.preRun.remove(this.preRun); 
      imageLoader.done.remove(this.done); 
      imageLoader.fail.remove(this.fail); 
      imageLoader.always.remove(this.always); 
      // Call dispose at the very end 
      imageLoader.dispose(); 
   } 
} 
export class ImageLoaderExample { 
   // We will show the results of loading a raster web image and SVG in all three supported loading modes. 
   // Insert URLs to raster (GIF, PNG, JPG) and SVG images below. The images must have CORS properties for AJAX. 
   imageRasterUrl = "http://demo.leadtools.com/images/gif/clock.gif"; 
   imageSvgUrl = "http://demo.leadtools.com/images/svg/lazio.svg"; 
 
   constructor() { 
      lt.RasterSupport.setLicenseUri("https://demo.leadtools.com/licenses/js/LEADTOOLSEVAL.txt", "EVAL", null); 
   } 
 
   run = () => { 
      const targets = [ 
         // Raster images 
         { parent: "rasterImageUrl", mode: lt.ImageLoaderUrlMode.imageUrl, url: this.imageRasterUrl }, 
         { parent: "rasterAjaxDataUrl", mode: lt.ImageLoaderUrlMode.ajaxDataUrl, url: this.imageRasterUrl }, 
         { parent: "rasterAjaxXml", mode: lt.ImageLoaderUrlMode.ajaxXml, url: this.imageRasterUrl }, 
         // SVG images 
         { parent: "svgImageUrl", mode: lt.ImageLoaderUrlMode.imageUrl, url: this.imageSvgUrl }, 
         { parent: "svgAjaxDataUrl", mode: lt.ImageLoaderUrlMode.ajaxDataUrl, url: this.imageSvgUrl }, 
         { parent: "svgAjaxXml", mode: lt.ImageLoaderUrlMode.ajaxXml, url: this.imageSvgUrl }, 
      ]; 
      targets.forEach((target) => { 
         const imageLoader = new lt.ImageLoader(); 
         imageLoader.urlMode = target.mode; 
         imageLoader.url = target.url; 
 
         // If we're loading with AJAX, attach a header or even change to a POST request (endpoint must have proper CORS properties) 
         //if (target.mode === lt.ImageLoaderUrlMode.ajaxDataUrl || target.mode === lt.ImageLoaderUrlMode.ajaxXml) { 
         //imageLoader.ajaxOptions.headers["myKey"] = "myValue"; 
         //imageLoader.ajaxOptions.method = "POST"; 
         //imageLoader.ajaxOptions.headers["contentType"] = "application/json"; 
         //imageLoader.ajaxOptions.postData = JSON.stringify({ key: "value" }); 
         //} 
         imageLoader.preRun.add(this.preRun); 
         imageLoader.done.add(this.done); 
         imageLoader.fail.add(this.fail); 
         imageLoader.always.add(this.always); 
 
         // Add the target ID to the loader so we can use it in our callbacks easily 
         imageLoader["parent"] = target.parent; 
         imageLoader.run(); 
      }); 
   } 
 
   // Before the imageLoader is run, we can do what we like. 
   preRun(imageLoader, preRunEventArgs) { 
      // Optional: we can set "abort" to true to make the imageLoader fail. 
      //preRunEventArgs.cancel = true; 
      console.log("ImageLoader about to run: " + imageLoader.url); 
   } 
 
   // When we're done, append the image to our page. 
   done(imageLoader) { 
      // For this example, we set an extra property as a target ID. 
      const parent = document.getElementById(imageLoader["parent"]); 
      const textElement = document.createElement("p"); 
      textElement.innerHTML = (imageLoader.isHTMLImageElement ? "<img>" : "<svg>") + " width: " + imageLoader.width + ", height: " + imageLoader.height; 
      parent.appendChild(imageLoader.element); 
      parent.appendChild(textElement); 
   } 
 
   // If we failed, show the error. 
   fail(imageLoader) { 
      const parent = document.getElementById(imageLoader["parent"]); 
      const textElement = document.createElement("p"); 
      textElement.innerHTML = imageLoader.error; 
      parent.appendChild(textElement); 
      console.error(imageLoader.error); 
   } 
 
   // Do some cleanup, regardless of the result 
   always(imageLoader) { 
      imageLoader.preRun.remove(this.preRun); 
      imageLoader.done.remove(this.done); 
      imageLoader.fail.remove(this.fail); 
      imageLoader.always.remove(this.always); 
      // Call dispose at the very end 
      imageLoader.dispose(); 
   } 
} 
<!doctype html> 
<html lang="en"> 
<title>LEADTOOLS Example | ImageLoader</title> 
 
<head> 
   <script src="https://code.jquery.com/jquery-2.2.4.min.js" 
      integrity="sha256-BbhdlvQf/xTY9gja0Dq3HiwQF8LaCRTXxZKRutelT44=" crossorigin="anonymous"></script> 
 
   <script src="../../LT/Leadtools.js"></script> 
 
   <style> 
      body { 
        font-family: 'Arial', 'Helvetica', sans-serif; 
        margin: 5px 5px 5px 5px; 
      } 
 
      #imagesHolder { 
        visibility: hidden; 
      } 
 
      table { 
        text-align: center; 
      } 
 
      th { 
        width: 250px; 
      } 
    </style> 
   <!-- All demo files are bundled and appended to the window --> 
   <script src="../../bundle.js" type="text/javascript"></script> 
</head> 
 
<body> 
   <!-- The element used by the imageLoader to do extra loading (hidden) --> 
   <div id="imagesHolder"></div> 
 
   <h4>Open your browser's developer tools to see how these images differ in the DOM.</h4> 
   <h4>You will need CORS-enabled images for AJAX.</h4> 
   <!-- Where we want to put our result --> 
   <table> 
      <thead> 
         <tr> 
            <th></th> 
            <th>Raster</th> 
            <th>SVG</th> 
         </tr> 
      </thead> 
      <tbody> 
         <tr> 
            <th>Image Url</th> 
            <td id="rasterImageUrl"></td> 
            <td id="svgImageUrl"></td> 
         </tr> 
         <tr> 
            <th>Ajax Data Url</th> 
            <td id="rasterAjaxDataUrl"></td> 
            <td id="svgAjaxDataUrl"></td> 
         </tr> 
         <tr> 
            <th>Ajax Xml</th> 
            <td id="rasterAjaxXml"></td> 
            <td id="svgAjaxXml"></td> 
         </tr> 
      </tbody> 
   </table> 
</body> 
 
<script> 
   window.onload = () => new window.examples.ImageLoader().run(); 
</script> 
</html> 
Requirements

Target Platforms

See Also

Reference

Leadtools Namespace

Help Version 23.0.2024.2.29
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2024 LEAD Technologies, Inc. All Rights Reserved.

Leadtools Assembly
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.