Image Viewer User-Defined HTML Display

Summary

With the Element property, any HTML (or SVG) element and its descendants may be added to an ImageViewerItem. This brings many new creative possibilities for presenting information with the JavaScript ImageViewer.

Prerequisites for User-Defined HTML

For an application to take advantage of this feature, Image Viewer Elements Mode must be used. In order for the user to interact natively with the elements added, the browser must also support HTML Pointer Events.

Uses for User-Defined HTML and Native Interaction

"User-Defined HTML" refers to HTML (or SVG) elements created or otherwise supplied by the user or other parts of the application to the ImageViewer, versus images or HTML5 Canvas Elements that the viewer creates or maintains itself. This HTML may certainly include an img or canvas, as well as any headers, lists, form elements (such as input or button), and any other browser-supported elements. The HTML will be automatically scaled and positioned to match the bounds of the ImageViewerItem to which it is attached.

User-Defined HTML, when combined with the BackImage property or other configurations, could provide the appearance of interactive PDF Forms over a raster image. Changing the view modes could also create possibilities for surveys, with each ImageViewerItem being a page. Essentially, a normal ImageViewer now creates a potentially infinite number of individualizable mini-webpages, each with rotation, scaling, flip, rotate, alignment, captioning, and transitions. Each "page" sits in the ImageViewer that would function as a page manager, providing additional alignment, organization, and interaction.

The elements added can be interacted with when the pointer-events CSS rule is available. In this case, the added HTML can be configured to respond to native clicking, hovering, dragging, or any other supported browser pointer events. The user is free to assign event handlers to any of the elements and add or remove elements at any time. This is because the user-defined HTML will sit "above" the Interactive Modes that normally capture pointer events for processing. The ElementInsertionHelper utility class (discussed below) can assist with user-defined HTML configuration.

Technical Considerations for User-Defined HTML

Previously, an ImageViewerItem in Elements Mode would still only hold an HTML Image Element (via Image) or an HTML5 Canvas Element (via Canvas). The Element property can accept any HTML or SVG Element. It will also detect if the element provided is an img or canvas and set Image or Canvas instead, since additional functionality is provided for elements in those properties. As always, only one of Image, Canvas, and Element may be set for an ImageViewerItem.

BackImage takes any HTML or SVG Element, instead of simply an HTML Image Element. However, if the user provides HTML to the BackImage the user should not expect the ImageViewerItem elements to be re-configured for the PassthroughDiv (discussed below) unless the Element has user-defined HTML as well.

New helper methods are available with similar effects - CreateFromElement will internally call CreateFromCanvas if the passed parameter is, in fact, a canvas. The same goes for AddFromElement, InsertFromElement, and UpdateElement.

As discussed in ImageViewer_Components, some new elements are added to the ImageViewer to support potential user interaction. These elements (EventCanvas and PassthroughDiv) are only created when native interaction is allowed via HTML Pointer Events. The EventCanvas replaces the ForeCanvas as the input for pointer interactions, while the PassthroughDiv holds the elements to be interacted with.

This is an important distinction - when the PassthroughDiv is used, any elements to be interacted with are moved out of the ViewDiv. Element styling on the page must take this into account, and apply (potentially different) CSS selectors to match the PassthroughDiv descendants. This is discussed more in the "Pitfalls" section below.

Sometimes, not all the elements added to the Element property are meant to be interacted with - this includes container elements like div or section that would get in the way of the Interactive Modes. To handle this issue, the utility class ElementInsertionHelper exists. ElementInsertionHelper provides methods to force or remove pointer-events from provided elements for complete control over interactivity with the user-defined HTML.

User-Defined HTML is not subject to the effects of AutoRemoveItemElements.

Pitfalls of the User-Defined HTML System

As discussed above, elements used for native interaction will still look to be descendants of the ViewDiv but actually are held by the PassthroughDiv. This means interactions with the DOM where a parent or child is requested may not match expectations. This also means CSS may need to be modified to get the same result as an ImageViewerItem that does not have native interaction and User-Defined HTML. Consider the below example - adding a "thumbnails mode" class to the item may require modification of different styles of a different element:

JavaScript Example

.lt-imageviewer .lt-view.thumbnail-mode .lt-item { 
  /* Thumbnail Mode */ 
  padding: 15px; 
  padding-bottom: 70px; 
} 
               
.lt-imageviewer .lt-imageviewer-passthrough.thumbnail-mode .lt-image-clipping { 
  /* Thumbnail Mode on a native interaction item - change margins instead, of the 'clipping' element instead */ 
  margin: 15px; 
  margin-bottom: 50px; 
}

This situation does not make for good, clean code, but does allow the same result in both instances of the ImageViewerItem - one with a regular image, and one with user-defined HTML.

When setting user-defined HTML, be aware of the CSS settings for box-sizing . The ImageViewer is rendered using a consistent box-sizing: "content-box"; this will be applied to the root element added to Element. However, any descendants of that root will not have an explicit box-sizing value set.

When adding the element, internal methods will attempt to get the natural size of the root and its descendants and resize the ImageViewerItem around that computed size. Due to CSS abnormalities and technicalities, particularly with respect to the CSS Box Model, this value may not always be correct. To troubleshoot, try examining what CSS rules are in effect for the added HTML, and if padding or border are involved, consider your values for box-sizing.

See Also