Class: SlideShowWidget

PR. SlideShowWidget

Creates a slideshow widgets.

A slideshow widget is constructed by a 3-layer architecture consisting of a wrapping element (usually a <div> but not a strict requirement, <section> or even <article> is often more semantically appropriate), a <ul> which holds the slides and any number of <li> elements that represent each slide.

Each slide is self-contained and can contain text, images or other widgets—so long as those elements are within the corresponding <li> they will be recognised by the slideshow widget and interpreted as part of the slide. A basic picture slideshow would simply place <img> tags inside the <li> elements, see the basic slideshow example.

The slideshow widget has a number of parameters that define how it works, the most descriptive of these parameters is transition which defines the transition that occurs when moving slides. The slideshow can be a specified to be sliding, flipping, fading or to have no transition effect.

The slideshow widget has an optional show-indicators flag which defines whether positional indicators, which create a visual representation of where a user is within the slideshow, should be shown or not. The visual representation of these indicators can also be specified, see the indicator example.

The slideshow will respond to NEXT_SLIDE, PREVIOUS_SLIDE and GO_TO_SLIDE events meaning that it can be controlled via button widgets or any custom widget that broadcasts those events. See the button example.

The image effect widget, which creates a Ken Burns effect (or pan-and-zoom), can also be used inside of a slideshow. See the Ken Burns example.

Note that most of the booleans can be specified as strings, i.e. data-loop=true and data-loop="true" are comparable.

HTML Parameters

The following parameters are required

data-widget="SLIDESHOW" Required
The identifier for the widget type.
class="slideshow" Required
The class for the slideshow (contained in common.css).
id="{{id}}" Additionally Required
A unique ID is not strictly necessary for all implementations but strongly advised—some implementations will fail without it (unique IDs are recommended for all slide elements too).

The following parameters are optional (defaults supplied in braces)

data-transition="{{NONE}}" Optional
The type of transition to use: SLIDE, FADE, FLIP or NONE. Note that case is important.
data-autoplay="{{false}}" Optional
true || false Specifies whether the slideshow transitions by itself.
data-autoplay-duration="{{2000}}" Optional
(in ms) Specifies the time a slide is visible before transitioning to the next slide.
data-transition-duration="{{500}} Optional
(in ms) Specifies the time taken to transition between slides.
data-loop="{{false}}" Optional
true || false Specifies whether a slideshow should loop.
data-touch-interaction="{{true}}" Optional
true || false Specifies whether a slideshow responds to user interaction.
data-show-indicators="{{false}}" Optional
true || false Specifies whether a slideshow shows positional indicators.
data-indicator-image-on="{{string}}" Optional
The source file of the indicator image to use when the visible slide corresponds to the positional indicator.
data-indicator-image-off="{{string}}" Optional
The source file of the indicator image to use when the visible slide does not match this positional indicator.

Examples

Basic Slideshow Implementation
The following example shows the HTML required to specify a basic sliding image slideshow. Each element of the slideshow (i.e. containing <div>, wrapping <ul> and slides <li>) all have unique ID’s, whilst this is not strictly required for this example it is adhered to as recommended slideshow specification.

Note that the slideshow class is a requirement.

data-transition="SLIDE" Required
Specifies the transition type
 <div id="uniqueid1"
class="slideshow"
data-widget="SLIDESHOW"
data-transition="SLIDE">
<ul id="uniqueid2">
<li id="slideUnique1">
<img src="../assets/slides/img-01.jpg"/>
</li>
<li id="slideUnique2">
<img src="../assets/slides/img-02.jpg"/>
</li>
<li id="slideUnique3">
<img src="../assets/slides/img-03.jpg"/>
</li>
<li id="slideUnique4">
<img src="../assets/slides/img-04.jpg"/>
</li>
</ul>
</div>

Slideshow with positional indicators
The following example shows the HTML required to specify a 4-slide fading slideshow with indicator icons, the slideshow in this example also loops. The positional indicators become active (or on) when the slide is visible and use the specified off image when not visible.

Note that boolean parameters (such as data-loop) can be specified using either a boolean or a string.

data-show-indicators="true" Required
Specified using positional indicators
data-indicator-image-on="src" Optional
Path to custom indicators
data-indicator-image-off="src Optional
Path to custom indicators
data-transition="FADE" Optional
Specifies the transition type
data-loop="true" Optional
Specifies that the slideshow should loop
 <div id="uniqueid1"
class="slideshow"
data-widget="SLIDESHOW"
data-transition="FADE"
data-loop=true
data-show-indicators="true"
data-indicator-image-on="../assets/dot-active.png"
data-indicator-image-off="../assets/dot-inactive.png" >
<ul id="uniqueid2">
<li id="slideUnique1">
<img src="../assets/slides/img-01.jpg"/>
</li>
<li id="slideUnique2">
<img src="../assets/slides/img-02.jpg"/>
</li>
<li id="slideUnique3">
<img src="../assets/slides/img-03.jpg"/>
</li>
<li id="slideUnique4">
<img src="../assets/slides/img-04.jpg"/>
</li>
</ul>
</div>

Slideshow operated via buttons
The following example shows the HTML required to specify a slideshow that responds only to clicking/tapping a button. The example restricts user interaction but it is perfectly acceptable to keep it set to true, the slideshow can respond to buttons and to user interaction on the same page. Specifying unique ID’s mean that using multiple slideshows on a page and using unique buttons for each slideshow is possible, or you could specify the buttons to action more than one slideshow at a time depending on your requirement.

This example also demonstrates using a slower transition speed. Multiple button taps/clicks with a slow transition speed will still show the correct slide after the duration (2 secs) has passed.

Note: As always, the child elements of the button widget can be anything to describe the look of the button, the important things are the action, target and target-slide. The GO_TO_SLIDE button shown here sends the slideshow to the first slide i.e. how a reset button may work.

data-transition="FADE" Optional
Specifies the transition type
data-transition-duration="src Optional
Specifies a longer transition time
data-loop="true" Optional
Specifies that the slideshow should loop
data-user-interaction="false" Optional
Restricts user interaction
 <div id="uniqueid1" class="slideshow" data-widget="SLIDESHOW" data-transition="FADE" data-transition-duration="2000" data-loop=true data-user-interaction=false >
<ul id="uniqueid2">
<li id="slideUnique1">
<img src="../assets/slides/img-01.jpg"/>
</li>
<li id="slideUnique2">
<img src="../assets/slides/img-02.jpg"/>
</li>
<li id="slideUnique3">
<img src="../assets/slides/img-03.jpg"/>
</li>
<li id="slideUnique4">
<img src="../assets/slides/img-04.jpg"/>
</li>
</ul>
</div>

<!-- Previous Slide Button -->
<div id="buttonid1" data-action="PREVIOUS_SLIDE" data-target="uniqueid1" data-widget="BUTTON" >
<img class="icon" src="../assets/arrow.png" style="-webkit-transform:rotate(-90deg);"/>
</div>

<!-- Next Slide Button -->
<div id="buttonid2" data-action="NEXT_SLIDE" data-target="uniqueid1" data-widget="BUTTON" >
<img class="icon" src="../assets/arrow.png" style="-webkit-transform:rotate(90deg);"/>
</div>

<!-- Goto Specific Slide Button -->
<div id="buttonid3" data-action="GO_TO_SLIDE" data-target="uniqueid1" data-target-slide="slideUnique1" data-widget="BUTTON" >
<img class="icon" src="../assets/button.png" />
</div>

Mr Ken Burns
The following example shows the HTML required to specify an image slideshow whose images employ the Ken Burns effect of panning and zooming when they become visible. The slideshow responds to user-interaction but it also proceeds on it’s own via autoplay, the duration of the autoplay is set to match the duration of the image effect but this is not a requirement and a nice option to hold the image after finishing the panning and zooming is to set the duration of the autoplay to be greater than the image effect duration.

Note also that the image effect widget inside each slide requires the data-parent-visible parameter to match the id of the slide (which means a unique slide ID is a requirement).

id="{{id}}" Required
Unique ID required on slides
data-transition="FADE" Optional
Specifies the transition type
data-transition-duration="2000" Optional
Specifies duration of the transition
data-loop="true" Optional
Specifies that the slideshow should loop
data-autoplay="true" Optional
Specifies that the slideshow should autoplay
data-autoplay-duration="2000" Optional
This matches with the duration of the image effect
 <div id="uniqueid1"
class="slideshow"
data-widget="SLIDESHOW"
data-transition="FADE"
data-transition-duration="2000"
data-loop=true
data-autoplay=true
data-autoplay-duration="2000" >
<ul id="uniqueid2">
<li id="slideUnique1">
<div id="effectid1" data-widget="EFFECTS"
data-start-offset-x="0" data-start-offset-y="100" data-start-scale="1" data-start-angle="0"
data-end-offset-x="0" data-end-offset-y="100" data-end-scale="0.8" data-end-angle="0"
data-transition-duration="2000" data-parent-visible="slideUnique1">
<!-- Content for the image effect (commonly an image) -->
<img id="uniqueid11" class="panandzoom" src="../assets/img-01.jpg" />
</div>
</li>
<li id="slideUnique2">
<div id="effectid2" data-widget="EFFECTS"
data-start-offset-x="0" data-start-offset-y="0" data-start-scale="0.75" data-start-angle="0"
data-end-offset-x="0" data-end-offset-y="0" data-end-scale="0.72" data-end-angle="0"
data-transition-duration="2000" data-parent-visible="slideUnique2">
<!-- Content for the image effect (commonly an image) -->
<img id="uniqueid11" class="panandzoom" src="../assets/img-02.jpg" />
</div>
</li>
<li id="slideUnique3">
<div id="effectid3" data-widget="EFFECTS"
data-start-offset-x="20" data-start-offset-y="100" data-start-scale="0.7" data-start-angle="0"
data-end-offset-x="22" data-end-offset-y="150" data-end-scale="0.95" data-end-angle="5"
data-transition-duration="2000" data-parent-visible="slideUnique3">
<!-- Content for the image effect (commonly an image) -->
<img id="uniqueid11" class="panandzoom" src="../assets/img-03.jpg" />
</div>
</li>
<li id="slideUnique4">
<div id="effectid4" data-widget="EFFECTS"
data-start-offset-x="100" data-start-offset-y="200" data-start-scale="1" data-start-angle="0"
data-end-offset-x="10" data-end-offset-y="200" data-end-scale="0.88" data-end-angle="0"
data-transition-duration="2000" data-parent-visible="slideUnique4">
<!-- Content for the image effect (commonly an image) -->
<img id="uniqueid11" class="panandzoom" src="../assets/img-04.jpg" />
</div>
</li>
</ul>
</div>
Author:
  • AppStudio Widgets
Source:
  • widgets/SlideshowWidget.js, line 3

Extends

  • PR.BaseWidget

Members

<static, constant> TRANSITION_EFFECTSobject

Slide transition effects

Properties:
Name Type Description
NONE string

No transition effect

SLIDE string

Sliding transition

FADE string

Fade transition

FLIP string

Flip transition

Source:
  • widgets/SlideshowWidget.js, line 1616

autoplayBoolean

Flag to indicate if the slideshow can play automatically without user interaction, based on the duration specified in the mark up.

Default Value:
  • false
Source:
  • widgets/SlideshowWidget.js, line 439

autoplayDurationNumber

The duration in seconds between slide if auto play option is set true.

Default Value:
  • 3000
Source:
  • widgets/SlideshowWidget.js, line 453

currentXPos_Number

Holds the current x co-ordinates of the slide.

Default Value:
  • 0
Source:
  • widgets/SlideshowWidget.js, line 285

defaultIndexNumber

The default index of the slide show.

Default Value:
  • 0
Source:
  • widgets/SlideshowWidget.js, line 465

defaultTransitionDurationNumber

The default transition for the effects. If the transition duration exceeds this default value,
then it is set one second.

Default Value:
  • 1000ms
Source:
  • widgets/SlideshowWidget.js, line 293

directionNumber

The direction the slide has to move, indicating the left or right. -1 to left and +1 to right.

Source:
  • widgets/SlideshowWidget.js, line 342

dotPath_String

Path of the slideshow indicators

Source:
  • widgets/SlideshowWidget.js, line 373

droidInitBoolean

This is set once the droidInit has been initialised

Source:
  • widgets/SlideshowWidget.js, line 530

dx_Number

Distance moved on the x-axis when the user the touches slide till the touch is released.

Source:
  • widgets/SlideshowWidget.js, line 298

dy_Number

Distance moved on the y-axis when the user the touches slide till the touch is released.
Not used in the slideshow, just for reference if we have to implement a vertical swipe in the future.

Source:
  • widgets/SlideshowWidget.js, line 305

elHTMLUListElement

The UL DOM element for the slideshow

Source:
  • widgets/SlideshowWidget.js, line 459

endDistanceNumber

The distance the slide has to move to get to next/previous slide.

Source:
  • widgets/SlideshowWidget.js, line 336

flipping_boolean

Denotes whether we are currently flipping or not

Source:
  • widgets/SlideshowWidget.js, line 424

idString

The html id of the widget.

Source:
  • widgets/SlideshowWidget.js, line 470

index_Number

The index of the active/visible slide.

Default Value:
  • 0
Source:
  • widgets/SlideshowWidget.js, line 361

indicatorImageOffString

Indicator for inactive slides

Source:
  • widgets/SlideshowWidget.js, line 385

indicatorImageOnString

Indicator for active slide

Source:
  • widgets/SlideshowWidget.js, line 379

indicatorsDivHTMLDivElement

Holds the container div for the indicator shown on the bottom of the slide.

Source:
  • widgets/SlideshowWidget.js, line 367

isHardwareAcceleratedBoolean

Flag indicates if the slideshow is hardware accelerated.

Default Value:
  • false
Source:
  • widgets/SlideshowWidget.js, line 477

itemsArray

Array holds all the slides in this widget.

Source:
  • widgets/SlideshowWidget.js, line 498

loopBoolean

Flag to indicate if the slideshow can loop at the end (used on Autoplay)

Default Value:
  • false
Source:
  • widgets/SlideshowWidget.js, line 446

nextButton

Reference to the next side button

Source:
  • widgets/SlideshowWidget.js, line 511

oldX_Number

Temporary variable that stores the clientX values between the user swipe gestures.

Source:
  • widgets/SlideshowWidget.js, line 324

oldY_Number

Temporary variable that stores the clientY values between the user swipe gestures.

Source:
  • widgets/SlideshowWidget.js, line 330

previousButton

Reference to the previous button

Source:
  • widgets/SlideshowWidget.js, line 517

previousIndex_Number

The index of the previously active slide. The previous index is not neccessarily the +/-1 and is useful especially, with go to slide functionality.

Default Value:
  • 0
Source:
  • widgets/SlideshowWidget.js, line 394

showIndicatorsBoolean

Flag to create indicators(dots) which states the current slide count.

Default Value:
  • false
Source:
  • widgets/SlideshowWidget.js, line 484

slideHeight_Number

The width of single slide.

Source:
  • widgets/SlideshowWidget.js, line 405

slideWidth_Number

The width of single slide.

Source:
  • widgets/SlideshowWidget.js, line 400

timer_

Timer id created if the autoplay option is set to true.

Source:
  • widgets/SlideshowWidget.js, line 347

tolerance_Number

Minimum distance to move a slide to go to the next slide.

Default Value:
  • 10
Source:
  • widgets/SlideshowWidget.js, line 412

touchInteractionString

Flag indicates if the touch gestures are enabled. This flag is set from data-touch attribute from the mark up.
If the value is true, then touch events are added and slideshow is interactive.

Default Value:
  • 'true'
Source:
  • widgets/SlideshowWidget.js, line 492

transitionString

The effect that needs to be applied to this slideshow. Valid values are 'slideLeft', 'fade', 'kenburns'

Default Value:
  • 'slideLeft'
Source:
  • widgets/SlideshowWidget.js, line 524

transitionDurationNumber

The maximum time it should take to complete the slide transition (in seconds)

Default Value:
  • 1000ms.
Source:
  • widgets/SlideshowWidget.js, line 505

translation_Array

Array to contain the slideshow elements' translation coordinates.

Source:
  • widgets/SlideshowWidget.js, line 418

vx_Number

Velocity with the which user swipes the finger on the x-axis.

Source:
  • widgets/SlideshowWidget.js, line 311

vy_Number

Velocity on the y-axis when the user swipes.
Not used in the slideshow, just for reference if we have to implement a vertical swipe in the future.

Source:
  • widgets/SlideshowWidget.js, line 318

Methods

addTouchEvents_( )

Add touch/mouse event listeners on initialization. If the 'data-touch' attribute is defined and is set to true
then add the event listeners. Consume the events even if the interaction is set to false, so we can prevent the default
behaviour of those events.

Source:
  • widgets/SlideshowWidget.js, line 719

animate( )

This function will animate to the previous/next slide depending on the new position when touch swiped.

Source:
  • widgets/SlideshowWidget.js, line 1186

createIndicators_( )

Create iOS style interface markers for slideshow position

Source:
  • widgets/SlideshowWidget.js, line 1355

createLayout_( )

Create the layout of the slides based on the type of transitions. For the Slide transition we need to a layout horizontally, for the fade effect we want
to stack on top of each other.

Source:
  • widgets/SlideshowWidget.js, line 664

determineCurrentPosition( )

Before the swipe/drag, should determine the current position. The 'translation' property is updated with current X position.

Source:
  • widgets/SlideshowWidget.js, line 1296

endScroll( )

Remove the transition from the slideshow DOM element

Source:
  • widgets/SlideshowWidget.js, line 1340

getIndex( ) → {Number}

Returns:
Number
Source:
  • widgets/SlideshowWidget.js, line 1447

goToSlide( nextIndex, previousIndex )

Will navigate to the specified next slide. Next index is not neccessarily the adjacent slide always.

Parameters:
Name Type Description
nextIndex
previousIndex
Source:
  • widgets/SlideshowWidget.js, line 1249

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

Throws:
Error HTML Element not attached.
Source:
  • widgets/SlideshowWidget.js, line 537

initSlideShow_( )

Configure slide show for user interaction and check if need to trigger the auto play timer.

Source:
  • widgets/SlideshowWidget.js, line 702

initTimer_( )

Handler for the timer if the autoplay is set to true. Trigger onSlideInterval_ every few seconds specified by @see autoplayDuration

Source:
  • widgets/SlideshowWidget.js, line 754

initVars_( )

Initialize the variables, fetch the attribute values from the mark up and assign them to instance variables.

Source:
  • widgets/SlideshowWidget.js, line 619

onGoToSlide( ) → {Boolean}

Event handler triggered by the go to slide button outside the slide show widget. The button instance that triggers the
action is passed as an argument. The 'data-target' attribute specifies the target slide show widget and the 'data-target-slide'
specifies the actual slide that needs to be visible/active.

Returns:
Boolean
Source:
  • widgets/SlideshowWidget.js, line 879

onInteractionEnd_( event )

Stop slideshow movement and trigger momentum-drift animation and auto-centering

Parameters:
Name Type Description
event

touchend/mouseup event

Source:
  • widgets/SlideshowWidget.js, line 1030

onInteractionMove_( event )

Move the slideshow, following the user's input

Parameters:
Name Type Description
event MouseEvent
Source:
  • widgets/SlideshowWidget.js, line 1000

onInteractionStart_( event, event )

Initialise the movement of the slideshow, set starting vars and notify the app

Parameters:
Name Type Description
event MouseEvent
event
Source:
  • widgets/SlideshowWidget.js, line 956

onNextSlide( dataset )

Click handler for the next button.

Parameters:
Name Type Description
dataset DOMStringMap
Source:
  • widgets/SlideshowWidget.js, line 935

onPreviousSlide( dataset )

Click handler for the previous button.

Parameters:
Name Type Description
dataset DOMStringMap
Source:
  • widgets/SlideshowWidget.js, line 923

onTransitionStart_( event )

Event handler triggered just before any transition is played.
todo- Need to refactor this to be an actual handler.

Parameters:
Name Type Description
event
Source:
  • widgets/SlideshowWidget.js, line 1061

setIndex( index )

Getter/Setter for current slide

Parameters:
Name Type Description
index Number

The current count of the slide. The count starts from 1-indicates the first slide

Source:
  • widgets/SlideshowWidget.js, line 1433

shouldHardwareAccelerate( )

Decide whether or not to hard accelerate the slideshow
which is needed on flip pages.

A slideshow on the back of a flip card doesn't update the left
position on an element until the page is re-rendered, however,
updating a 3d this.translation on an element updates as expected.

Source:
  • widgets/SlideshowWidget.js, line 1396

slideByDirection( pDirection )

Specify the this.direction to slide, either PREVIOUS or NEXT

Parameters:
Name Type Description
pDirection
Properties:
Name Type Description
PREVIOUS string

PR.SlideShowWidget.PREVIOUS

NEXT string

PR.SlideShowWidget.NEXT

Source:
  • widgets/SlideshowWidget.js, line 1206

slideByIndex( index, index )

Specify an index to slide.

Parameters:
Name Type Description
index Number
index Boolean

If this value is set, then it will loop to the first slide after the last slide.

Source:
  • widgets/SlideshowWidget.js, line 1232

subscribeEvents_( )

@-

Source:
  • widgets/SlideshowWidget.js, line 595

updateIndicators( )

Update interface markers to match current state of slideshow

Source:
  • widgets/SlideshowWidget.js, line 1412
Top