Simple Controls Gallery v1.5
v1.5 (Oct 6th) : Gallery made responsive and mobile
friendly, by supporting a percentage "width
" value and swipe/ touch
support. Also adds a new "scaleimage
" option to scale the images
inside the gallery in 2 different ways.
Description: Want to display images as an automatic slideshow that can also be explicitly played or paused by the user? Simple Controls Gallery rotates and displays an image by fading it into view over the previous one, with navigation controls that pop up when the mouse rolls over the Gallery. Lets take a look at the script's set of features:
- Displays images either as an automatic or manual slideshow, with the image faded into view over the previous. A Navigational Panel slides up when the mouse rolls over the gallery to play, pause, or step through to a specific image within the gallery.
-
Supports scaling of the images inside the gallery in 2 different ways to
ensure they are visible regardless of image dimensions, by way of the "
scaleimage
" option. v1.5 feature - In automatic mode, set the number of cycles before the script stops rotating.
- Each slide consists of an image that can be hyperlinked.
- Each slide can have a description associated with it. When defined, a Description Panel slides down from the top of the gallery showing the description.
- The gallery supports persistence of the last viewed image via session cookies, so going away then coming back to the gallery calls up the last viewed image within a browser session.
- Responsive and mobile friendly. Width of gallery can be set to percentage value. On mobile devices, touch to activate description and play/pause controls, and swipe to navigate. v1.5 feature
The images within the Gallery should all be the same size for best results.
Demos:
Step 1: Add the following script to the <head> section of your page:
The code above references three external .js files plus 5 images, which you need to download below (right click/ select "Save As"):
- simplegallery.js (customize variable
"simpleGallery_navpanel"
at the top) - jquery.touchSwipe.min.js v1.6.6 (project page)
- simplegallery.css
Step 2: Then, where you wish a Gallery to
appear on your page, add an empty DIV with a unique ID attribute and a CSS
class of "simplegallery
" (required):
<div id="simplegallery1" class="simplegallery"></div>
The DIV's ID value should match up with the value set in
simpleGallery.wrapperid
in the code of Step 1 above. When the page loads,
the script will load the gallery into this DIV.
More information
To define a new Simple Controls Gallery, you should call
new simpleGallery()
in the HEAD section of your page with the supported
parameters:
var mygallery=new simpleGallery({ wrapperid: "simplegallery1", //ID of main gallery container, dimensions: [250, 180], //width/height of gallery in [pixels, pixels] or ['percentage%', pixels] imagearray: [ ["pool.jpg", "http://en.wikipedia.org/wiki/Swimming_pool", "_new", ""], ["cave.jpg", "http://en.wikipedia.org/wiki/Cave", "", ""], ["fruits.jpg", "", "", ""], ["autumn.jpg", "", "", ""] ], autoplay: [true, 2500, 2], //[auto_play_boolean, delay_btw_slide_millisec, cycles_before_stopping_int] persist: false, scaleimage: 'both', //valid values are 'both', 'width', or 'none' fadeduration: 500, //transition duration (milliseconds) oninit:function(){ //event that fires when gallery has initialized/ ready to run //Keyword "this": references current gallery instance (ie: try this.navigate("play/pause") }, onslide:function(curslide, i){ //event that fires after each slide is shown //Keyword "this": references current gallery instance (ie: try this.navigate("play/pause") //curslide: returns DOM reference to current slide's DIV (ie: try alert(curslide.innerHTML) //i: integer reflecting current image within collection being shown (0=1st image, 1=2nd etc) } })
First and foremost, note the "mygallery
" variable
in bold red- this should be an arbitrary but unique variable that
identifies this instance of the Gallery on your page. For multiple instances,
use a different variable name each time.
-
Wrapperid
: Must be set to the ID of the empty DIV you've manually added on your page. -
dimensions
: The dimensions of the gallery, in pixels-pixels such as [500, 300], or percentage-pixels, such as ['50%', 300]. In the later case, the gallery becomes responsive, with its width changing depending on the width of its parent container. Make use of CSS media queries at the same time to adjust the height of the gallery at certain breaking points. -
imagearray
: An array containing the images to be shown in the following format:["path_to_image", "optional_link", "optional_linktarget", "optional_textdescription"].
For the parameters that are optional, set it to a blank string ("") if you don't want a particular one enabled.
-
autoplay
: An array that lets you set whether the gallery should play automatically when the page loads, and if so, the pause between slides and cycles to run before stopping:/[auto_play_boolean, delay_btw_slide_millisec, cycles_before_stopping_int]
Setting the first parameter to false makes the later two irrelevant.
-
persist
: Boolean on whether gallery should remember and recall last viewed slide within a browser session. -
scaleimage
: v1.5 option: Sets how the images inside the gallery should scale to fit in the container. Valid values are: "both
", "width
", or "none
". In "both", the image's width and height will both be examined to ensure they fit inside the gallery. In "width", only the image's width will be examined and scaled down if necessary (with the height adjusted proportionally). In "none", the image's dimensions are left untouched. -
preloadfirst
: v1.4 option: Boolean on whether slideshow should only start after all images have preloaded. Default value is true even if this option is not defined. -
fadeduration
: The duration of the fade effect, in milliseconds. -
oninit:function()
: Event handler that fires once when the page has loaded and the gallery initialized, just about to fade the first image into view. You can use this event handler to define any custom variables that will be used by the gallery. -
onslide:function(curslide, i)
: Event handler that fires each time a slide fades into view. See "Customizing: The navigate() method, oninit() and onslide event handlers".
Toggling whether slideshow should only begin after all images within the slideshow have preloaded
Starting in Simple Gallery v1.4, each slideshow by default will
only start after all images within the slideshow have preloaded. This ensures an
always smooth transition between image change, especially if the slideshow is set to
automatically rotate. You can turn this behaviour off if you like by setting the
option setting.preloadfirst
to false within the initialization code
above for that slideshow:
preloadfirst:false, //v1.4 option on whether slideshow should only start after all images have preloaded
One situation you may wish to do this is when slideshow is set to manually rotate and the chances are good the upcoming image will have preloaded already by the time the user requests it. In this case it might make sense to disable this option and have the slideshow become interactive as soon as possible instead of wait for all images to preload first.
Adding a description to a slide
As seen in the 2nd Demo above, you can add a description to a slide by populating the very last element of the array containing the slide information:
imagearray: [ ["http://i26.tinypic.com/11l7ls0.jpg", "http://en.wikipedia.org/wiki/Swimming_pool", "_new", "There's nothing like a nice swim in the Summer."], ["http://i29.tinypic.com/xp3hns.jpg", "http://en.wikipedia.org/wiki/Cave", "", ""], ["http://i30.tinypic.com/531q3n.jpg", "", "", "Eat your fruits, it's good for you!"], ["http://i31.tinypic.com/119w28m.jpg", "", "", ""] ],
Here the first and 3rd slides will carry a description, which are shown inside a gliding Panel at the top of the gallery.
The DIV that houses the description carries a CSS class of "gallerydesctext
".
Style this DIV on your page if desired, such as adjusting the padding around it:
.simplegallery .gallerydesc .gallerydesctext{ width: auto; color: white; text-align: left; padding: 5px; /* padding inside description panel */ }
Tweaking the Navigation Controls Panel
At the top of simplegallery.js is where you'll find the settings for the Navigation Panel that glides up when the user mouses over the Gallery:
var simpleGallery_navpanel={ loadinggif: 'ajaxload.gif', //full path or URL to loading gif image panel: {height:'45px', opacity:0.5, paddingTop:'5px', fontStyle:'bold 11px Verdana'}, //customize nav panel container images: [ 'left.gif', 'play.gif', 'right.gif', 'pause.gif'], //nav panel images (in that order) imageSpacing: {offsetTop:[-4, 0, -4], spacing:10}, //top offset of left, play, and right images, PLUS spacing between the 3 images slideduration: 500 //duration of slide up animation to reveal panel }
It allows you to modify the path to the 4 images used by the
Panel, among other things. For example, if you've customized the images to your
own, you may find the need to modify the Panel's height (panel.height
)
accordingly. The setting imageSpacing
lets you change individually
the vertical offset of the 3 images from their default position, plus the
spacing between them, in that order.
Here's a tip- you can effectively hide the Navigational Panel
altogether by setting panel.height
to 0. If you do so, With the
Panel hidden, you can still let users control the Gallery via custom controls
that call galleryinstance.navigate()
. See "Customizing: The navigate()
method, oninit() and onslide event handlers"
for more info.
Making your gallery responsive
Simple Controls Gallery can easily be made responsive to cater to changes in layout size and mobile devices. See the supplementary page "Creating a responsive gallery" for more info.
Table Of Contents
This script consists of an index page plus 1 supplementary page: