Add a gesture-based image gallery to a mobile website
Using the open source script PhotoSwipe, you'll learn how to add a gesture-based, fully interactive image gallery into your mobile website that replicates the "native" photo application bundled with iOS devices. Ste Brennan also gives a quick rundown of the events that are made available by mobile browsers
A common requirement for many websites is a simple and intuitive way for visitors to browse and navigate around images. Indeed, there are literally hundreds of scripts available out there that achieve this.
This requirement is also true for mobile websites. However, many solutions out there are tailored for the desktop rather than mobile devices. Features such as using your finger to "swipe" through images and using multi-touch gestures to zoom and rotate images are missing.
Mobile users are used to browsing their photo library with the built-in applications that come bundled with their device’s operating system and it's only fair therefore, that mobile website developers to try and replicate this intuitive experience for visitors.
PhotoSwipe (developed by Code Computerlove) makes adding this functionality simple. Inspired by the built-in iOS photo viewer application and Google Images for mobile, PhotoSwipe is a free HTML/CSS/JavaScript based image gallery specifically targeting mobile devices. The current version supports mobile handsets running WebKit-based browsers, ie iOS, Android and BlackBerry 6, and it also runs on desktop browsers including Chrome, Firefox, Safari and Internet Explorer 8 and above. Best of all, PhotoSwipe is completely free and open source. For more advice, see our mobile website design tips.
Getting started
Getting started with PhotoSwipe is simple. Visit the website and click the download link to download the latest release.
Alternatively, you can visit GitHub to download the release and its source code, raise a support issue or actively contribute to the project!
When you uncompress the release package, you will see an "examples" folder, which contains a set of comprehensive demos that you can study and follow. These examples range from using the mobile WebKit-optimised implementation (index.html) to using PhotoSwipe with jQuery (jquery-engine.html) and jQuery Mobile (jquery-mobile.html).
Get top Black Friday deals sent straight to your inbox: Sign up now!
We curate the best offers on creative kit and give our expert recommendations to save you time this Black Friday. Upgrade your setup for less with Creative Bloq.
It's important to note that PhotoSwipe is completely configurable in terms of its visual appearance and how it's embedded within your mobile website. It doesn't enforce how you organise your HTML, CSS or JavaScript. It's also important to note that PhotoSwipe comes in two distinct flavours:
- A non-jQuery, mobile WebKit optimised version:This version is self-contained and does not require jQuery. It's written to be as optimised as it can be for mobile web browsers based on WebKit (ie iOS, Android and BlackBerry 6 devices). It will also run on desktop WebKit browsers such as Chrome and Safari as well as Firefox 4 and above, which is useful for development purposes. This version will not run on Internet Explorer.
- A jQuery version:Use this implementation if you require a wider browser support - for example Internet Explorer - or you need to integrate PhotoSwipe into a jQuery Mobile site.
To get started with either version:
- Create a “gallery style” HTML page that includes the PhotoSwipe CSS file and has a list of thumbnail images on it
- Each thumbnail image should link to the URL of the full-size image
- Each thumbnail image can have an optional “alt tag” value that PhotoSwipe will use as the image’s caption
<!DOCTYPE html><html><head> <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0;" name="viewport" /> <link href="photoswipe.css" type="text/css" rel="stylesheet" /> <!-- PhotoSwipe script will go here --></head><body> <div id="Gallery"> <div class="gallery-row"> <div class="gallery-item"> <a href="images/full/001.jpg"><img src="images/thumb/001.jpg" alt="Image 001" /></a> </div> <div class="gallery-item"> <a href="images/full/002.jpg"><img src="images/thumb/002.jpg" alt="Image 002" /></a> </div> <div class="gallery-item"> <a href="images/full/003.jpg"><img src="images/thumb/003.jpg" alt="Image 003" /></a> </div> </div> <div class="gallery-row"> <div class="gallery-item"> <a href="images/full/004.jpg"><img src="images/thumb/004.jpg" alt="Image 004" /></a> </div> <div class="gallery-item"> <a href="images/full/005.jpg"><img src="images/thumb/005.jpg" alt="Image 005" /></a> </div> <div class="gallery-item"> <a href="images/full/006.jpg"><img src="images/thumb/006.jpg" alt="Image 006" /></a> </div> </div> </div></body></html>It's not a requirement that these thumbnail images are arranged in divs: they can be equally arranged in unordered lists or any other formatting preference you have.
To set up PhotoSwipe using the “mobile WebKit optimised” version:
- Include "simple-inheritance.min.js" and the latest minified version of PhotoSwipe, eg "code-photoswipe-1.0.16.min.js"
- On the "DOM content loaded" event, tell PhotoSwipe where to find your thumbnails, eg
<script type="text/javascript" src="simple-inheritance.min.js"></script><script type="text/javascript" src="code-photoswipe-1.0.16.min.js"></script><script type="text/javascript"> document.addEventListener('DOMContentLoaded', function(){ Code.photoSwipe('a', '#Gallery'); }, false);</script>To set up PhotoSwipe using the jQuery version:
- Include the latest version of jQuery
- Include "simple-inheritance.min.js" and the latest minified version of PhotoSwipe for jQuery, eg "code-photoswipe-jQuery-1.0.16.min.js"
- Optionally include the jQuery Animate Enhanced plug-in by Ben Barnett. This will provide smoother animations if your browser supports CSS transitions
- On "document ready", call the PhotoSwipe jQuery plug-in; for example:
<script type="text/javascript" src="jquery-1.6.1.min.js"></script><script type="text/javascript" src="jquery.animate-enhanced.min.js"></script><script type="text/javascript" src="simple-inheritance.min.js"></script><script type="text/javascript" src="code-photoswipe-jQuery-1.0.16.min.js"></script><script type="text/javascript"> $(document).ready(function(){ $("#Gallery a").photoSwipe(); });</script>Configuring PhotoSwipe
As well as amending the PhotoSwipe CSS file to tweak its visual appearance, the script comes complete with a set of comprehensive configuration settings that allows you to fine-tune your implementation covering:
- Setting the speed of any animations
- How sensitive the swipe and double tap gestures are
- How PhotoSwipe scales your image to fit the viewport
- How PhotoSwipe locates your full size images if you have a different markup layout
- Whether a user can zoom and rotate an image, etc
A full list detailing these settings and default values are available in the “README.md” file in the release package. They are also viewable online at github.com/codecomputerlove/PhotoSwipe.
Example of supplying settings for the mobile WebKit optimised version:
<script type="text/javascript"> document.addEventListener('DOMContentLoaded', function(){ Code.photoSwipe('a', '#Gallery', { allowRotationOnUserZoom: false, maxUserZoom: 6.0, minUserZoom: 0.2 }); }, false);</script>Example of supplying settings for the jQuery version:
<script type="text/javascript"> $(document).ready(function(){ $("#Gallery a").photoSwipe({ allowRotationOnUserZoom: false, maxUserZoom: 6.0, minUserZoom: 0.2 }); });</script>Some useful mobile JavaScript events
PhotoSwipe relies on a number of JavaScript events that are made available to developers from mobile browsers:
Touch Events - "touchstart, touchmove, touchend, touchcancel"
These events are triggered when the user touches the screen. Your event handler function can obtain information from a touch event such as the number of fingers touching the screen (event.touches) and for each touch, the corresponding X and Y co-ordinates (event.touches[0].pageX), eg
document.addEventListener('touchstart', function(event){ // This will log the number of fingers touching the screen console.log(event.touches.length);}, false);Or, if you are using jQuery:
$(document).bind('touchstart', function(event){ // This will log the number of fingers touching the screen console.log(event.originalEvent.touches.length);});It's important to remember that when using jQuery to access these events, you must reference the "originalEvent" property of the event object. This is due to the way jQuery wraps up events in its own event object.
Gesture Events - "gesturestart, gesturechange, gesturend" (iOS only)
These events are triggered during a multi-touch sequence, typically pinching and rotating gestures. Gesture event objects pass in useful information such as scale and rotation. PhotoSwipe uses these when handling image scaling and rotating on iOS devices.
Screen Orientation - "orientationchange"
This event is triggered every 90 degrees of rotation (portrait and landscape modes). You can obtain the current orientation through window.orientation.
- 0 = "Portrait"
- -90 = "Landscape (right, screen turned clockwise)"
- 90 = "Landscape (left, screen turned counter clockwise)"
- 180 = "Portrait (upside-down portrait)"
Device Motion Events - "devicemotion" (iOS only)
From the official Safari reference documentation, these "are created when significant change in motion occurs. The event object for devicemotion encapsulates the measurements of the interval, rotation rate, and acceleration of a device".
This event is useful for detecting when the user shakes or moves the device.
More information about these events can be found on the Safari Developer site:
and
Wrapping up
Hopefully, this tutorial has given you a quick insight into how to add a "native like", gesture-based image viewer into your mobile websites using PhotoSwipe.
I also hope the quick run-down of events that are made available via mobile browsers will fire your imagination as you come up with new and innovative ways of using the technology to enhance your mobile websites.
Thank you for reading 5 articles this month* Join now for unlimited access
Enjoy your first month for just £1 / $1 / €1
*Read 5 free articles per month without a subscription
Join now for unlimited access
Try first month for just £1 / $1 / €1
The Creative Bloq team is made up of a group of design fans, and has changed and evolved since Creative Bloq began back in 2012. The current website team consists of eight full-time members of staff: Editor Georgia Coggan, Deputy Editor Rosie Hilder, Ecommerce Editor Beren Neale, Senior News Editor Daniel Piper, Editor, Digital Art and 3D Ian Dean, Tech Reviews Editor Erlingur Einarsson and Ecommerce Writer Beth Nicholls and Staff Writer Natalie Fear, as well as a roster of freelancers from around the world. The 3D World and ImagineFX magazine teams also pitch in, ensuring that content from 3D World and ImagineFX is represented on Creative Bloq.
