TypeScript
JavaScript
References ▼
Specifies the mode by which the image or XML will be loaded.
| Value | Member | Description |
|---|---|---|
| 0 | ImageUrl | Set the url to the src attribute of the workingImageElement. This is the typical way to load an HTML Image Element. |
| 1 | AjaxDataUrl | Use an XMLHttpRequest (via xhr) to load the image or SVG as binary data. |
| 2 | AjaxXml | Use an XMLHttpRequest (via xhr) to load the image or SVG directly. |
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.