JSDoc: Class: ImageEffectsWidget

This component is associated with creating an image effect (currently only Pan-and-Zoom is supported).

An image with Pan-and-Zoom applied is an analogy of the effect popularised by Ken Burns whereby an image is represented with two states—a starting state that dynamically transitions to a final state.

In order for the widget to produce an effect either the start state or the end state should be specified although in many cases both states will be specified. If a state is not specified then that state will default to the usual representation of the image.

The widget requires a child element to be specified which refers to the image used in the effect and note that there are some styling requirements, most notably adding the panandzoom class to the <img> element. Additionally a parent element (or the widget element) should be specified with overflow:hidden as the effect relies on creating a pseudo-viewport and so portions of the element will be out-of-frame at some points during the transition. Note: There is actually no requirement for the child element to be an <img>, any HTML will validate.

The widget element should also be specified with a width and height which represents the dimensions of the viewport. Note that the <img> will have it’s native size and the scaling parameter should take into account the <img> and the widget element dimensions (i.e. if the image has dimensions of 1000px/1000px and the widget is 500px/500px then the end-scale should be 0.5 for the image to fill the viewport).

Most of the parameters are fairly self-explanatory but the parent-visible parameter deserves further clarification. The Image Effect widget can be used within other widgets (such as slideshows or popups) and so may begin hidden. In these cases the widget needs to know when it becomes visible otherwise it will fire when the page opens, by specifying the id of the parent a communication link is created and the widget only fires when it becomes visible.

HTML Parameters

The following parameters are required.

data-widget="EFFECTS" Required: The identifier for the widget type.

The following parameters are optional.

id="{{id}}" Optional: It is usually preferable to include a unique ID but it is not strictly necessary.
data-end-offset-x="{{Number}}" Optional: The ending offset of the image (x-axis).
data-end-offset-y="{{Number}}" Optional: The ending offset of the image (y-axis).
data-end-scale="{{Number}}" Optional: The ending scale of the image.
data-end-rotation="{{Number}}" Optional: The ending rotation of the image.
data-start-offset-x="{{Number}}" Optional: Default to 0. The starting offset of the image (x-axis).
data-start-offset-y="{{Number}}" Optional: Default to 0. The starting offset of the image (y-axis).
data-start-scale="{{Number}}" Optional: Default to 0. The starting scale of the image.
data-start-rotation="{{Number}}" Optional: Default to 0. The starting rotation of the image.
data-transition="{{String}}" Optional: Default to PanAndZoom. Transition effect to apply (currently only Pan-and-Zoom is supported).
data-transition-duration="{{Number}}" Optional: Default to 600ms. The time taken for the transition effect.
data-parent-visible="{{id}}" Optional: The id of the elements’ parent—ensures that the transition only fires when it becomes visible.

The following styles are required.

overflow:hidden Required: Should be applied to the widget element (in some circumstances can be applied to a parent element).
class="panandzoom" Required: Should be attributed to the <img> element within the widget element.

Examples

Sizing and styling for examples

To get a grasp on how the various parameters affect the resulting transition special consideration should be given to the relative sizes used at both stages of the transition.

In each of the following examples the following are true where the viewport is 25% of the size of the image size:

Image Size: 1600 x 1200 px

Styling for widget element ⟶

.size {
  overflow: hidden;
  width: 400px;
  height: 300px;
}

Basic zooming

The transition effect always assumes that the origin is 0,0 so as there is no offset in this example the zooming effect will be clamped to the top left corner. The image will start at it’s native size of 1600x1200px, as the viewport is 400x300px only the top-left 25% of the image will be visible. In order to fit the entire image into the viewport an end scale factor of 25% (0.25) is applied so the effect is to zoom from a large portion of the image to reveal the entire image.

<!-- Zoom out from origin -->
<div id="uniqueid1" class="size" data-widget="EFFECTS"
     data-start-offset-x="0"      data-end-offset-x="0"
     data-start-offset-y="0"      data-end-offset-y="0"
     data-start-scale="1"         data-end-scale="0.25"
     data-start-angle="0"         data-end-angle="0"
     data-transition-duration="2000">
    <!-- HTML content for the imageEffect widget (commonly an image) -->
    <img id="uid1" class="panandzoom" src="../assets/big-flower.jpg" />
</div>

Slide from one side of an image to the other

In this example a scale factor of 0.4 is applied throughout the transition which gives the image a resultant size of 640x480px. As the viewport is 400x300px to position the image on the right edge of the viewport requires a starting x offset of 640-400. The ending x offset of 0 transitions the image from the right edge to the left edge. Note that a y offset of 100 is applied only because of the image selected.

<!-- Sliding transition -->
<div id="uniqueid2" class="size" data-widget="EFFECTS"
     data-start-offset-x="240"      data-end-offset-x="0"
     data-start-offset-y="100"      data-end-offset-y="100"
     data-start-scale="0.4"         data-end-scale="0.4"
     data-start-angle="0"           data-end-angle="0"
     data-transition-duration="2000">
    <!-- HTML content for the imageEffect widget (commonly an image) -->
    <img id="uid2" class="panandzoom" src="../assets/big-flower.jpg" />
</div>

Zoom in to center

Zooming in to the center of an image only requires special consideration of the relative sizes. An initial scale factor of 0.25 is applied so that the image displays fully in the viewport and there is then a modest zoom to a scale factor of 0.4 which actually enlarges the image in the viewport to give the zooming effect.

To keep the zoom in the center ending offsets are applied so that the ending image (plus its zoom factor) are displayed centered in the viewport. They are calculated by using:

(image size - viewport size) / 2,

where the resultant image size is:

natural image size * scale factor,

which, when substituted in (for end-offset-x) gives:

( (1600 * 0.4) - 400 ) / 2 = 120,

repeating for y gives the final offset of 90.

 <!-- Zoom in -->
<div id="uniqueid3" class="size" data-widget="EFFECTS"
     data-start-offset-x="0"      data-end-offset-x="120"
     data-start-offset-y="0"      data-end-offset-y="90"
     data-start-scale="0.25"      data-end-scale="0.4"
     data-start-angle="0"         data-end-angle="0"
     data-transition-duration="6000">
    <!-- HTML content for the imageEffect widget (commonly an image) -->
    <img id="uid3" class="panandzoom" src="../assets/big-flower.jpg" />
</div>

Rotation example

The origin of the rotation is always 0,0 so some consideration should be made to ensure that the bounds of the image are not visible in the viewport, usually this can be achieved by using a subtle rotation and zooming into the image. The following is an example of a subtle rotation with an additional upwards pan which hides the bounds of the image which would visible in the starting state. It’s ends with the image centered in the viewport.

<!-- Rotation -->
<div id="uniqueid4" class="size" data-widget="EFFECTS"
     data-start-offset-x="120"      data-end-offset-x="120"
     data-start-offset-y="180"      data-end-offset-y="90"
     data-start-scale="0.4"         data-end-scale="0.4"
     data-start-angle="15"          data-end-angle="0"
     data-transition-duration="4000">
    <!-- HTML content for the imageEffect widget (commonly an image) -->
    <img id="uid1" class="panandzoom" src="../assets/big-flower.jpg" />
</div>

Within a slideshow

The following lengthy example shows a four-slide slideshow where each slide has an image effect. Note that the data-parent-visible parameter should match the ID of it’s containing li in order for the effect to fire when the slide becomes visible. The transition effect should be placed within the slide li as content.

<!-- Slideshow -->
<div id="uniqueid5"
     class="slideshow size"
     data-widget="SLIDESHOW"
     data-transition="SLIDE">
  <ul id="slideUniqueUL">
    <li id="slideUnique1">
        <div id="uid1" data-widget="EFFECTS"
            data-start-offset-x="156"     data-end-offset-x="0"
            data-start-offset-y="72"      data-end-offset-y="0"
            data-start-scale="1"          data-end-scale="0.52"
            data-start-angle="0"          data-end-angle="0"
            data-transition-duration="4000"
            data-parent-visible="slideUnique1">
          <!-- HTML content for the imageEffect widget (commonly an image) -->
          <img id="uid2" class="panandzoom" src="../assets/slides/img-103.jpg" />
        </div>
    </li>
    <li id="slideUnique2">
        <div id="uid3" data-widget="EFFECTS"
            data-start-offset-x="0"      data-end-offset-x="560"
            data-start-offset-y="0"      data-end-offset-y="400"
            data-start-scale="0.52"      data-end-scale="2.617"
            data-start-angle="0"         data-end-angle="0"
            data-transition-duration="4000"
            data-parent-visible="slideUnique2">
          <!-- HTML content for the imageEffect widget (commonly an image) -->
          <img id="uid4" class="panandzoom" src="../assets/slides/img-104.jpg" />
        </div>
    </li>
    <li id="slideUnique3">
        <div id="uid5" data-widget="EFFECTS"
            data-start-offset-x="156"    data-end-offset-x="0"
            data-start-offset-y="72"     data-end-offset-y="0"
            data-start-scale="1"         data-end-scale="0.52"
            data-start-angle="0"         data-end-angle="0"
            data-transition-duration="4000"
            data-parent-visible="slideUnique3">
          <!-- HTML content for the imageEffect widget (commonly an image) -->
          <img id="uid6" class="panandzoom" src="../assets/slides/img-105.jpg" />
        </div>
    </li>
    <li id="slideUnique4">
        <div id="uid7" data-widget="EFFECTS"
            data-start-offset-x="156"    data-end-offset-x="80"
            data-start-offset-y="72"     data-end-offset-y="0"
            data-start-scale="1"         data-end-scale="0.52"
            data-start-angle="0"         data-end-angle="0"
            data-transition-duration="4000"
            data-parent-visible="slideUnique4">
          <!-- HTML content for the imageEffect widget (commonly an image) -->
          <img id="uid8" class="panandzoom" src="../assets/slides/img-106.jpg" />
        </div>
    </li>
  </ul>
</div>

Author:

AppStudio Widgets

Source:

widgets/ImageEffectsWidget.js, line 2

Extends

PR.BaseWidget

Members

elHTMLDIVElement: The DIV DOM element for the effect

Source:

widgets/ImageEffectsWidget.js, line 322
endAngleNumber: Source:

widgets/ImageEffectsWidget.js, line 288
endOffsetXNumber: The starting x-axis offset of the image viewport

Source:

widgets/ImageEffectsWidget.js, line 270
endOffsetYNumber: Source:

widgets/ImageEffectsWidget.js, line 276
endScaleNumber: Source:

widgets/ImageEffectsWidget.js, line 282
imgElHTMLIMGElement: The IMG DOM element for the effect

Source:

widgets/ImageEffectsWidget.js, line 328
parentVisibleString: Source:

widgets/ImageEffectsWidget.js, line 294
startAngleNumber: Source:

widgets/ImageEffectsWidget.js, line 264
startOffsetXNumber: The starting x-axis offset of the image viewport

Source:

widgets/ImageEffectsWidget.js, line 246
startOffsetYNumber: Source:

widgets/ImageEffectsWidget.js, line 252
startScaleNumber: Source:

widgets/ImageEffectsWidget.js, line 258
transitionString: Default Value:

'PanAndZoom'

Source:

widgets/ImageEffectsWidget.js, line 301
transitionDurationNumber: The maximum time it should take to complete the transition (in milliseconds)

Default Value:

600ms.

Source:

widgets/ImageEffectsWidget.js, line 308

Methods

executeTransform_( ): Executes the transform

Source:

widgets/ImageEffectsWidget.js, line 418
findAncestorWithId_( element, id ) → {HTMLElement}: Return the parent containers which has the specified id

Parameters:

Name Type Description

element HTMLElement
the DOM element

id String
the id of the element

Returns:

HTMLElement

Source:

widgets/ImageEffectsWidget.js, line 492
getDataAttributes_( ): Fetch the data attribute values from the mark up and assign them to instance variables.

Source:

widgets/ImageEffectsWidget.js, line 374
initialize( element ): Acts like a constructor, this function triggered by default when you create an object.

Parameters:

Name Type Description

element
The HTML DOM Element which acts like a effect.

Throws:

Error HTML Element not attached.

Source:

widgets/ImageEffectsWidget.js, line 339
positionImageForStart_( ): Set the position of the image based on the start values.

Source:

widgets/ImageEffectsWidget.js, line 390
removeTransform_( ): Removes the transform

Source:

widgets/ImageEffectsWidget.js, line 447
resetImage_( dataset ): Resets the image

Parameters:

Name Type Description

dataset
the dataset of the element

Source:

widgets/ImageEffectsWidget.js, line 432
shouldApplyTransform_( ): Calculates whether the transform should be applied

Source:

widgets/ImageEffectsWidget.js, line 459
startTransition_( ): Starts the transition

Source:

widgets/ImageEffectsWidget.js, line 403

Name	Type	Description
`element`	HTMLElement	the DOM element
`id`	String	the id of the element

Class: ImageEffectsWidget

HTML Parameters

Examples

Sizing and styling for examples

Basic zooming

Slide from one side of an image to the other

Zoom in to center

Rotation example

Within a slideshow

Extends

Members

elHTMLDIVElement

endAngleNumber

endOffsetXNumber

endOffsetYNumber

endScaleNumber

imgElHTMLIMGElement

parentVisibleString

startAngleNumber

startOffsetXNumber

startOffsetYNumber

startScaleNumber

transitionString

transitionDurationNumber

Methods

executeTransform_( )

findAncestorWithId_( element, id ) → {HTMLElement}

Parameters:

Returns:

getDataAttributes_( )

initialize( element )

Parameters:

Throws:

positionImageForStart_( )

removeTransform_( )

resetImage_( dataset )

Parameters:

shouldApplyTransform_( )

startTransition_( )