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> 
         <span class="lt-item-text"></span> 
      </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:

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:

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 will not automatically maintain angle of view when rotated.

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:

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 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.

Help Version 19.0.2017.10.27
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.
LEADTOOLS HTML5 JavaScript
Introduction
Getting Started
HTML5 Browsers
LEADTOOLS Software License Agreement
Demo Programs
Files To Be Included With Your Application
LEADTOOLS JavaScript Object Module
Imaging
Annotations
Documents
Medical
Tutorials
Support
Version History
Libraries