Image Viewer Elements Mode

Summary

The HTML5 / JavaScript ImageViewer has the ImageViewerCreateOptions.UseElements property, which may either be true or false, signifying that the image viewer will use the Elements Mode. Elements Mode uses real HTML5 elements to render the viewer and its items, instead of painting onto a canvas element. The Elements Mode of the viewer still uses a canvas element for registering click, touch, scroll, and drag events, as well as custom post rendering operations (such as rendering annotations).

When using Elements Mode, an application may attach arbitrary HTML to Element and use default browser page interactions with the added HTML, such as button clicks or textbox editing. See the Image Viewer User Defined HTML topic for more information.

For a complete example, refer to the Image Viewer Styles demo included in your LEADTOOLS installation. The JavaScript version of the Document Viewer demo also uses Elements Mode by default.

Below is the hierarchy of elements used, with default class names (discussed further below):

HTML

<div > 
   <div class="lt-view"> 
      <div class="lt-item"> 
         <div class="lt-clipping"> 
            <div class="lt-flip"> 
               <div class="lt-image-border"></div> 
                  <img class="lt-backimage" /> 
                  <img class="lt-image" /> 
               </div> 
            </div> 
          class="lt-item-text" 
      </div> 
      <div class="lt-item">...</div> 
      ... 
   </div> 
</div>

Layout

ViewDivHolder 
    ViewDiv 
       Item 
          Clipping 
             Flip 
             Border 
             Back Image 
             Image 
             
             
          Text

Each element has a certain importance:

View Holder Element (ImageViewer.ViewDivHolder)

Parent of the ViewDiv.
View Element (ImageViewer.ViewDiv)

Holds the item elements and shows the viewer's view margin, view padding, view border, and view box shadow.
Item Clipping Element (ImageViewerItem.ImageClippingElement)

Serves as a barrier to limit the user's view of the image element when the image needs to be clipped, such as when ImageViewerItem.ResizeOnTransform is false and ImageViewerItem.ClipImageToContent is true.
Item Flip Element (ImageViewerItem.ImageFlipElement)

Used internally to assist in smooth CSS transitions when CSS transitions are applied and ImageViewerItem.Flip or ImageViewerItem.RotateAngle is changed.
Image Border Element (ImageViewerItem.ImageBorderElement)

Instead of creating a CSS border around the image elements, a single border is applied as a separate <div>. This ensures the border will not stretch as the image is resized internally. The element holds the image border and image shadow.
Back Image Element (ImageViewerItem.BackImageElement)

If a partially-transparent image is used (such as SVG) that requires a back image, this element is used. Otherwise, it is not created.
Image Element (ImageViewerItem.ImageElement)

Holds the actual img or canvas being viewed. It should not be given a border or shadow in CSS, as this is the job of the Image Border Element.
Text / Caption Element (ImageViewerItem.TextElement)

Holds the caption set for the item in ImageViewerItem.Text. Holds the text font, size, and other styles.

Because HTML elements are used, CSS styles and transitions can be applied to the elements. As a result, setting these properties programmatically in the image viewer is no longer needed or allowed. Setting the value of any of these properties will be ignored and not used:

These properties are now handled entirely through CSS by the application, which results in a faster UI. As discussed below, after updating properties that would change the size of any item / element, ImageViewer.UpdateStyles should be called - the viewer will get the new values that may have been changed in CSS and set the values for these properties internally. This method is required since there is not automatic way to handle detecting CSS changes automatically in standard HTML / DOM.

Because of this change, certain properties can now have different values in different places - for example, two different items may be given different item border width values. Different size values for different items is not currently supported, so the following properties are always computed from their values on the first item for which elements have been created (which may not be the first element in certain events where ImageViewerElementsModeCreateOptions.AutoRemoveItemElements is true:

In addition, only the border-top-width CSS value is used for the ImageViewer.ImageBorderThickness and ImageViewer.ItemBorderThickness.

CSS can now also be used for additional properties not available before for items - all valid CSS is usable.

Overwriting necessary viewer rules, such as the overflow: hidden on some elements, may produce unexpected results and should be avoided. When added, a viewer will create and append a number of <style> elements to the <head> of the document that list basic element rules that are required for the image viewer to function correctly.

CSS rules can be applied by CSS class name selectors (such as .lt-item for items), which can all be modified programmatically in ImageViewerElementsModeCreateOptions. These Elements Mode-specific settings can be set to the ImageViewerCreateOptions.ElementsModeOptions property and will be read when the viewer is created.

ImageViewerElementsModeCreateOptions has the following default class name values:

Entity	Property	Default Value	Default Value, prefixed
Prefix	ClassPrefix	`lt`	N/A
View Element	ViewElementClass	`view`	`lt-view`
Item Element	ItemElementClass	`item`	`lt-item`
Image Element	ItemImageElementClass	`image`	`lt-image`
Back Image Element	ItemBackImageElementClass	`backimage`	`lt-backimage`
Image Border Element	ItemImageBorderElementClass	`image-border`	`lt-image-border`
Image Clipping Element	ItemImageClippingElementClass	`image-clipping`	`lt-image-clipping`
Image Flip Element	ItemImageFlipElementClass	`image-flip`	`lt-image-flip`
Item Text Element	ItemTextElementClass	`item-text`	`lt-item-text`
Hovered Item (in Select Interactive Mode)	ItemHoverClass	`item-hovered`	`lt-item-hovered`
Selected Item (in Select Interactive Mode)	ItemSelectClass	`item-selected`	`lt-item-selected`
Active Item	ItemActiveClass	`item-active`	`lt-item-active`
Image Loading (when ImageViewerItem.Url is set)	ItemImageLoadingClass	`image-loading`	`lt-image-loading`
Image Loaded (when ImageViewerItem.Image is a fully-loaded image)	ItemImageLoadedClass	`image-loaded`	`lt-image-loaded`

ImageViewerElementsModeCreateOptions.ClassPrefix holds a prefix that will be applied to each other class name when the viewer is created - this allows different styles to be applied to different viewers added to the same page. The prefix is only applied once the viewer is constructed, but the user may pass true as a parameter to the ImageViewerElementsModeCreateOptions.Clone function to receive the prefixed version of each class name. The ImageViewerElementsModeCreateOptions object should not be passed to the viewer with the prefixes already applied: do not pass an options object created from the Clone function. This function is called internally.

The prefix value also helps to avoid possible class name collisions with other classes on a page not involved with LEADTOOLS.

ImageViewerElementsModeCreateOptions also contains an ImageViewerElementsModeCreateOptions.AutoRemoveItemElements property, which controls items that are out of view on the page. When AutoRemoveItemElements is true, items that move out of view will be removed entirely from the page: all elements from the ImageViewerItem.ItemElement down are deleted, including the ImageViewerItem.Image or ImageViewerItem.Canvas, whichever was being used. These elements are entirely re-created when the item must come back into view, and if an image used to exist at ImageViewerItem.Image then the ImageViewerItem.Url property is set to trigger a new request for the image. The image should be cached by the browser. Overall, auto-removing the items should reduce memory used by the page for a significantly large number of items and / or significantly large images.

After items are added due to the ImageViewerElementsModeCreateOptions.AutoRemoveItemElements property, the viewer triggers the ImageViewer.AutoItemElementsAdded event.

Before items are added due to the ImageViewerElementsModeCreateOptions.AutoRemoveItemElements property, the viewer triggers the ImageViewer.AutoItemElementsRemoved event.

Using these events can assist in doing cleanup or other tasks when item elements must be removed and added.

Now, with CSS, one can easily style the background color of the active item element as follows, for example:

JavaScript Example

.lt-imageviewer .lt-item-active { 
    /* Active Item */ 
    background-color: red; 
 }

This value of lt-item-active came from the application of the default ImageViewerElementsModeCreateOptions.ClassPrefix ("lt") with the default ImageViewerElementsModeCreateOptions.ItemActiveClass ("item-active"). Either value may be changed prior to the creation of the viewer to create a fully-customizable class name.

Some of the class names within ImageViewerElementsModeCreateOptions apply not to elements, but to certain element states:

ImageViewerElementsModeCreateOptions.ItemHoverClass

This class will be applied to a hovered item when the viewer is using the ImageViewerSelectItemsInteractiveMode. Whether or not the hover or select CSS rules apply (if both should) depends on the CSS rule specificity set by the user.
ImageViewerElementsModeCreateOptions.ItemSelectClass

This class will be applied to all selected items when the viewer is using the ImageViewerSelectItemsInteractiveMode. Whether or not the hover or select CSS rules apply (if both should) depends on the CSS rule specificity set by the user.
ImageViewerElementsModeCreateOptions.ItemActiveClass

This class will be applied to the active item. See ImageViewer.ActiveItem for more information.
ImageViewerElementsModeCreateOptions.ItemImageLoadingClass

If an image is being set to the item through ImageViewerItem.Url, the item will have this class set between the time the URL request is sent and the request is resolved (either successfully, or by error).
ImageViewerElementsModeCreateOptions.ItemImageLoadedClass

Due to the hierarchical nature of CSS rule application, it is not possible to apply stylings for an item based on the conditional existence of that item's image. To fix this, the ImageViewerElementsModeCreateOptions.ItemImageLoadedClass is applied to a class whenever it has a non-null ImageViewerItem.ImageElement.

There are other classes that exist which may be applied to elements, but the user defines neither their names nor their rules. The definitions for these classes, which are defined in dynamically-added <style> elements to the <head>, are meant to be outside the concerns of the user.

In Elements Mode of the Image Viewer, all updates to the elements for an item take place between the ImageViewer.RenderItem and ImageViewer.PostRenderItem events. Refer to the rendering cycle for more information.

CSS for a box shadow can be applied to an item image's border, like below:

JavaScript Example

.lt-image-border { 
   /* Box Shadow (view, item, image border) */ 
   box-shadow: #333 1px 1px 4px -1px; 
}

Box shadows on the image border's element will automatically rotate to maintain the angle of view. Due to computational limits, the border may slightly fade if the element is rotated multiple hundred degrees per second. This rotating shadow will work even with transitions.

ImageViewer.UpdateShadowOnRotation, which defaults to true, will update the CSS values for the box-shadow property of each ImageViewerItem.ImageBorderElement. When true, the viewer will parse the h-shadow and v-shadow attributes from the style and rotate them to match the rotation of the image and border, such that the shadow always seems to come from the same 3-dimensional location.

While CSS transitions may be applied to every aspect of the image viewer elements, there are instances in which internal code must disable transitions on elements. The following actions may cause disabled transitions:

Step-wise zoom
Scroll
Pan
Movements due to interactive modes (unless specifically enabled with ImageViewerInteractiveMode.AutoDisableTransitions as false)
Resizing the browser

To disable transitions, the viewer applies an internal class to each element that overrides any set transitions (using the !important CSS directive). This class is removed immediately after the update occurs. This performed by calling the DisableTransitions (applies the style) and EnableTransitions methods (remove the style). These methods can be used by the user to disable/re-enable the transitions manually. The The IsTransitionsEnabled property can be used to check if the viewer is currently in a state where transitions is disabled.

The ElementsUpdated event occurs anytime the viewer changes any DOM or CSS property on an element that is part of view or any item. This event also contains the ImageViewerElementsUpdatedEventArgs.IsTransitionsEnabled property that can be used to detect when the image viewer is performing a CSS transition. For example, the document viewer uses this event to stop custom painting of the annotations while a CSS transition is in effect.

See Also