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 totrue
, 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>
- Source:
- widgets/SlideshowWidget.js, line 3
Extends
- PR.BaseWidget
Members
-
<static, constant> TRANSITION_EFFECTSobject
-
Slide transition effects
- Source:
- widgets/SlideshowWidget.js, line 1616
Properties:
Name Type Description NONE
string No transition effect
SLIDE
string Sliding transition
FADE
string Fade transition
FLIP
string Flip transition
-
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
- Source:
- widgets/SlideshowWidget.js, line 1206
Properties:
Name Type Description PREVIOUS
string PR.SlideShowWidget.PREVIOUS
NEXT
string PR.SlideShowWidget.NEXT
-
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