1. Introduction
The Uize.Widget.SlideShow class eases the creation of slideshow presentations, supporting navigation controls, configurable visualizations, and more.
DEVELOPERS: Chris van Rensburg
The Uize.Widget.SlideShow module defines the Uize.Widget.SlideShow widget class, a subclass of Uize.Widget.
1.1. A Panoply of Flavors
The Uize.Widget.SlideShow class doesn't dictate how slides are presented, but provides a versatile framework for a wide range of different flavors of slideshow presentations.
Among the range of possibilities for slideshows are...
| a simple image slideshow, with no transition effects and merely employing an implied node for the slide image | |
an image slideshow with transition effects, employing helper widget classes (such as Uize.Widget.ImageWipe) | |
| an image slideshow with transition effects, and displaying slide meta data (such as rating, description, tags, etc.) through a combination of helper widgets and implied nodes | |
a slideshow of data, such as a bar chart representing different facets of data for different months of a year, and employing helper widget classes (such as Uize.Widget.Bar) | |
| a slideshow of slideshows, such as a slideshow of different houses - where each slide represents a house and itself presents its own sub-slideshow of different pictures of the house |
1.2. Navigation Control
The Uize.Widget.SlideShow class wires up and manages enabled state for navigation control buttons that allow the user to navigate forward and back through a slideshow.
The navigation control is comprised of four buttons:
the next button navigates to the next slide in the slides set | |
the previous button navigates to the previous slide in the slides set | |
the first button navigates to the first slide in the slides set | |
that last button navigates to the last slide in the slides set |
All the navigation buttons are optional. That is to say, it is not necessary to provide markup for the button child widgets, and if no HTML is present for them no disastrous consequences will ensue - the user will simply not see those buttons and the slideshow will still function correctly. Usually one wants markup for at least the next and previous buttons, so one may choose to omit markup for the first and last buttons, or one may choose only to provide markup for the first button as a "go back to beginning" feature.
1.2.1. Enabled State Management
The Uize.Widget.SlideShow class manages the enabled state of the various navigation buttons, so that they're never inappropriately enabled.
For example, when the slideshow is at the first slide the first button becomes disabled. Likewise, when the slideshow is at the last slide the last button becomes disabled. If there are no slides in the set, then all the navigation buttons become disabled. As for the next and previous buttons, the next button becomes disabled when at the last slide and wrap is set to false and, similarly, the previous button becomes disabled when at the first slide and wrap is set to false.
1.3. No Effects Please, We're British
A slideshow will typically be presented with transition / animation effects as one navigates from one slide to the next.
The Uize.Widget.SlideShow base class does not provide or impose any specific transition effects, however, and acts primarily as a foundation / scaffolding upon which to build a slideshow user experience. Slideshows with elaborate transition effects can quite easily be configured by combining the Uize.Widget.SlideShow class with other widget classes from the UIZE JavaScript Framework - such as the Uize.Widget.Swap.Image and Uize.Widget.ImageWipe classes - or your own widget classes.
1.4. Slide Properties
The Uize.Widget.SlideShow class supports an arbitrary number of properties for slides, each of which can be bound - either implicitly or explicitly - to child widgets, implied nodes, Uize subclass instances, or handler functions.
The system for binding slide properties so that they are represented in the user interface for a slideshow supports a wide range of possible applications for slideshows, where each slide may contain a rich set of data for display. For example, you may implement a slideshow with slides that contain imageUrl, title, description, rating, author, and tags properties. Or, you may implement a nutritional information slideshow - where each slide represents a different fruit and contains properties like calories, totalFat, saturatedFat, cholesterol, sodium, etc.
1.5. Slide Property Bindings
A slideshow would not be terribly useful if there was nothing to see.
As mentioned earlier, the Uize.Widget.SlideShow class does not make assumptions about the content described by slides, and does also not presume to know how best to display that content. Instead, it is left to an individual application, a subclass of Uize.Widget.SlideShow, or some other widget class that uses the Uize.Widget.SlideShow class as a helper class to implement the presentation.
What the Uize.Widget.SlideShow class does provide is a mechanism for binding the values of slide properties - either implicitly to child widgets or implied nodes, or explicitly to registered Uize subclass instances or handler functions.
1.5.1. Implicit Bindings
The Uize.Widget.SlideShow class implements a convenient facility for implicitly binding properties of the current slide to either child widgets of a Uize.Widget.SlideShow instance, or implied nodes of the instance.
1.5.1.1. Child Widget Bindings
One facility for implicit slide property binding involves testing for a child widget of a specific name.
When the user interface for a Uize.Widget.SlideShow instance is updated - either initially when it is wired up, or each time that the current slide is changed - the slideshow instance tests for the existence of child widgets that correspond to each of the properties in the slide object. It does this by following the rule that any child widget that is intended to be bound to a slide property should be named slide[PropertyName], where PropertyName is the name of the property with its first letter capitalized. So, for example, to have the imageUrl property for a slide implicitly bound to a child widget, a child widget should exist with the name slideImageUrl.
HOW IT'S DISPLAYED
Now, if a child widget instance is found that corresponds to a slide property, then the value set-get property for that child widget will be set to the value of the slide property for the current slide. This means that child widgets that are implicitly bound to slide properties must implement the Value Interface (ie. provide a value set-get property). If the set-get property that logically represents the value in the child widget's class is not publicly named value, then one could modify the class to register value as a public alias for that property (for more details, consult the explainer Set-get Properties).
If the Child Widget Bindings facility is not successful in implicitly binding a slide property to a child widget, then the Implied Node Bindings facility will be employed.
1.5.1.2. Implied Node Bindings
Another facility for implicit slide property binding involves setting the value for an implied node.
If the Child Widget Bindings facility is not successful in implicitly binding a slide property to a child widget, then the slideshow instance will attempt to display the value of that slide property in an implied node of the instance, following the rule that an implied node that is intended to be bound to a slide property should be named slide_[propertyName]. So, for example, to have the imageUrl property for a slide implicitly bound to an implied node, an implied node named slide_imageUrl should exist in the DOM.
HOW IT'S DISPLAYED
To display the values of slide properties in corresponding implied nodes, the setNodeValue instance method of the Uize.Widget base class is used. This has the implication that values of slide properties can easily be represented in form elements (such as text input fields, textarea fields, radio buttons, checkboxes, etc.), image elements (src attribute will be set), or any HTML element (innerHTML will be set). If no node exists that corresponds to a slide property, then that slide property will simply not be represented in the user interface. Therefore, it is acceptable to have properties in the slide object that are either not meant to appear in the slideshow UI, or for which the UI is not yet implemented.
In the most simple usage of the Uize.Widget.SlideShow class, the Implied Node Bindings facility provides a simple and lightweight way to reflect slide properties in the UI, simply by adding nodes to the DOM with correctly named id's.
1.5.1.3. Remapped Implied Node Bindings
In the event that the naming scheme employed by the Implied Node Bindings facility does not suit your needs, you can use the implied node name remapping facility provided in the Uize.Widget base class to bind slide properties to arbitrarily named implied nodes.
EXAMPLE
mySlideShow = new Uize.Widget.SlideShow ({
nodeMap:{
slide_imageUrl:'imageUrl'
}
});
In the above example, the value of the imageUrl slide property - that would normally be bound by the Implied Node Bindings facility to the implied node slide_imageUrl - is being remapped so that it is bound instead to the implied node imageUrl, using the nodeMap set-get property that is implemented in the Uize.Widget class.
1.5.2. Explicit Bindings
A facility is provided to explicitly declare a binding between a slide property and either an instance of a Uize subclass that implements the Value Interface (ie. provides a value set-get property), or an update handler function that will be executed when the value of the slide set-get property changes.
This facility is implemented in the form of the slideBindings set-get property, whose value should be an object that provides mappings between slide properties and binding targets. The name of each key in the slideBindings object should correspond to the name of a property in the slide object, and its value should be either a reference to an instance of a Uize subclass that implements the Value Interface (ie. provides a value set-get property), or an update handler function that will be executed when the value of the slide set-get property changes. If an explicit binding is provided for a particular slide property, then the Implicit Bindings facility will not be employed for that slide property (the explicit binding takes precedence).
1.5.2.1. Explicit Object Bindings
Any slide property can be bound to an instance of a Uize subclass that implements the Value Interface (ie. provides a value set-get property), simply by specifying a reference to that instance as the value for a binding.
EXAMPLE
mySlideShow = new Uize.Widget.SlideShow ({
slideBindings:{
imageUrl:myImageWipeInstance
}
});
In the above example, the imageUrl slide property is being bound to the widget instance myImageWipeInstance - an instance of the Uize.Widget.ImageWipe widget class.
1.5.2.2. Explicit Function Bindings
Any slide property can be bound to a handler function, simply by specifying a reference to that function as the value for a binding.
EXAMPLE
mySlideShow = new Uize.Widget.SlideShow ({
slideBindings:{
imageUrl:function (value) {
myCustomImageEffectsWidget.chooseRandomTransition ();
myCustomImageEffectsWidget.set ({image:value});
}
}
});
In the above example, the value of the imageUrl slide property is being represented using the hypothetical myCustomImageEffectsWidget instance. The explicit binding of imageUrl to a handler function causes this handler to be executed when the value of the slide set-get property changes. In the handler function, the hypothetical chooseRandomTransition instance method is called to choose a new transition effect, and then the image set-get property of the myCustomImageEffectsWidget instance is set to the new value of the imageUrl slide property (which is passed as the single parameter to the handler function).
1.5.3. Mixed Bindings
One may use a combination of the Implicit Bindings and Explicit Bindings facilities.
You are not forced to choose one facility or the other for all slide properties. So, if a non-null value is specified for the slideBindings set-get property, it does not mean that all slide properties must be bound explicitly. Rather, any slide property for which an explicit binding is not declared in the slideBindings set-get property will be attempted to be bound using the Implicit Bindings facility.
2. Child Widgets
2.1. first
An instance of Uize.Widget.Button, that is wired up as part of the Navigation Control, and that advances the slideshow to the first slide in the set.
NOTES
this button becomes disabled when the slideshow is at the first slide, or if the slides array is empty | |
the markup for this child widget is optional, and a given implementation of a slideshow widget in HTML does not need to offer a first button |
2.2. last
An instance of Uize.Widget.Button, that is wired up as part of the Navigation Control, and that advances the slideshow to the last slide in the set.
NOTES
this button becomes disabled when the slideshow is at the last slide, or if the slides array is empty | |
the markup for this child widget is optional, and a given implementation of a slideshow widget in HTML does not need to offer a last button |
2.3. next
An instance of Uize.Widget.Button, that is wired up as part of the Navigation Control, and that advances the slideshow to the next slide.
NOTES
this button becomes disabled when the slideshow is at the last slide and wrap is set to false, or if the slides array is empty | |
the markup for this child widget is optional, and a given implementation of a slideshow widget in HTML does not need to offer a next button |
2.4. previous
An instance of Uize.Widget.Button, that is wired up as part of the Navigation Control, and that advances the slideshow to the previous slide.
NOTES
this button becomes disabled when the slideshow is at the first slide and wrap is set to false, or if the slides array is empty | |
the markup for this child widget is optional, and a given implementation of a slideshow widget in HTML does not need to offer a previous button |
2.5. slide[PropertyName]
An instance of any widget class that implements the Value Interface (ie. provides a value set-get property), and that will be used to represent the value for a corresponding slide property of the name propertyName.
For example, a child widget that is intended to represent the value for a slide property named imageUrl should be named slideImageUrl. An arbitrary number of child widgets may be added to an instance of the Uize.Widget.SlideShow class, for the purpose of representing the values of slide properties through the Child Widget Bindings facility.
3. Implied Nodes
3.1. slide_[propertyName]
An element node of any type, that will be used to represent the value for a corresponding slide property of the name propertyName.
For example, an implied node that is intended to represent the value for a slide property named imageUrl should be named slide_imageUrl. An arbitrary number of implied nodes may exist in the DOM for an instance of the Uize.Widget.SlideShow class, for the purpose of representing the values of slide properties through the Implied Node Bindings facility.
4. Instance Methods
4.1. advance
Lets you advance the position within the slideshow by a specified amount.
SYNTAX
myInstance.advance (advanceAmountINT);
Specifying a positive number for the advanceAmountINT parameter navigates forwards in the slideshow, while specifying a negative number navigates backwards. Typically, this method would be used to advance one slide in either direction, as in...
myInstance.advance (-1); // previous slide myInstance.advance (1); // next slide
This method is offered merely as a convenience. There is nothing terribly special about it, and the same effect could be accomplished simply by modifying the value of the slideNo set-get property, as in...
myInstance.set ({slideNo:myInstance.get ('slideNo') - 1}); // previous slide
myInstance.set ({slideNo:myInstance.get ('slideNo') + 1}); // next slide
The behavior when advancing in a negative direction beyond the first slide, or advancing in a positive direction beyond the last slide is governed by the wrap set-get property.
NOTES
see the slideNo and wrap set-get properties |
5. Set-get Properties
5.1. progress
An integer, representing the progress (measured in percentage) through the entire set of slides.
The value of this read-only property is derived from the values of the slideNo and totalSlides set-get properties and is not intended to be set by an application.
NOTES
| this property is read-only | |
the initial value is 0 |
5.2. slide
An object, representing the element in the slides array that corresponds to the current slide (as specified by the slideNo property).
The value of this read-only property is derived from the values of the slideNo and slides set-get properties and is not intended to be set by an application. As the values of the slideNo and slides properties are modified, the slide property is automatically updated and kept current.
NOTES
| this property is read-only | |
if the slides set-get property is set to null or undefined, or if the slides array has zero elements, then the slide property will be set to null | |
the initial value is undefined |
5.3. slideBindings
An object, representing explicit bindings between slide properties and Uize subclass instances or handler functions.
The name of each key in the slideBindings object should correspond to the name of a property in the slide object, and its value should be either a reference to an instance of a Uize subclass that implements the Value Interface (ie. provides a value set-get property), or an update handler function that will be executed when the value of the slide set-get property changes. It is not necessary to provide a binding for every slide property, and any slide property for which no explicit binding is provided will be bound implicitly to either a child widget or an implied mode.
For more details on property bindings, consult the section Slide Property Bindings.
NOTES
the initial value is undefined |
5.4. slideNo
An integer, representing the current position within the slideshow presentation.
The value of this property can be set in order to jump straight to a different position in the slideshow, and the slideshow will update automatically - including updating the navigation buttons to the appropriate state.
NOTES
see also the advance instance method | |
if the slides set-get property is set to null or undefined, or if the slides array has zero elements, then the slideNo property will be set to -1 | |
the initial value is -1 |
5.5. slides
An array, representing the set of slides for the slideshow, where each element of the array should be an object whose properties can be presented in the user interface.
NOTES
the initial value is [] (an empty array) |
5.6. totalSlides
An integer, specifying the total number of slides in the slides set.
The value of this read-only property will correspond to the length of the array specified by the slides set-gt property, but if slides is set to null or undefined, then totalSlides will be set to the value 0.
NOTES
| this property is read-only | |
the initial value is 0 |
5.7. wrap
A boolean, specifying whether or not navigation should be allowed beyond the beginning or end of the set of slides.
By default, navigation is not permitted beyond the beginning or end of the set of slides, and the previous and next buttons become disabled when reaching the beginning or end of the set, respectively. Moreover, attempting to set the value of the slideNo set-get property outside of the range of the slides set causes it to be conformed to the beginning or the end of the set.
But when the wrap set-get property is set to true, then the previous and next buttons will remain enabled, and navigating to the previous slide when at the first slide will cause slideNo to "wrap" around to the last slide, and navigating to the next slide when at the last slide will cause slideNo to "wrap" around to the first slide.
Moreoever, attempting to set the value of the slideNo set-get property outside of the range of the slides set causes it to be conformed to within the range by "wrapping" its value around as many times as needed in order to bring it into range. For example, in a set of ten slides and when wrap is set to true, setting the slideNo property to 13 will cause it to be conformed to 3 (wrapped around forwards once), and setting slideNo to -23 will cause it to be conformed to 7 (wrapped around backwards twice and then third from the end).
NOTES
the initial value is false |