Simple Image Viewer With Captions

It seems that, if I am to leave a legacy after this blog is gone, it will be my Specificity, as more people read and ask about this widget than any other. I attempted to address most people concerns in last weeks Somewhat Simple Image Viewer article, but I was only partially successful, as I did not add in the second most requested feature: captions.

Article updated on Dec. 15, 2012

There is a new and improved (standalone) version SuperSimpleImageViewerV3 available.

Super Simple Image Viewer V3

Getting ready

Somewhat Simple Image Viewer Demo

The source code for the image viewer is available at https://gist.github.com/4287668.

How do it…

Users will quickly notice that the PhotoViewer function now only requires two parameters: cfg and data. Where cfg is an object containing DOM references and data is the collection of image URLs (and other meta data). Below is an example of the cfg Object:

Example 1: Configuration Object

var cfg = {
    caption: "viewer-caption", // optional
    image: "viewer-image", // required
    next: "viewer-next", // required
    prev: "viewer-prev" // required
};

While the caption value is optional, if any of the other 3 DOM references are missing, PhotoViewer will alert you and not initialize. The data can be in two different formats: an Array of image URLs or an Object where each key is the DOM ID of the anchor tag to select that set and the value is an Array of images. Here are three different valid data sets:

// 3 sets of objects, containing the image and caption
var data = {
	set1: [// this needs to be the DOM ID attribute for the anchor tag to select this set
        {image: "http://farm1.static.flickr.com/142/331222000_76f271e745.jpg?v=0", caption: "frozen landscape"},
        {image: "http://farm1.static.flickr.com/159/384269775_f8b21b5e52.jpg?v=0", caption: "mountain stream"},
        {image: "http://farm1.static.flickr.com/178/415791942_4a4e411464.jpg?v=0", caption: "mountain lake"}
    ],

	set2: [// this needs to be the DOM ID attribute for the anchor tag to select this set
        {image: "http://farm1.static.flickr.com/186/421171930_80ef8ee7b2.jpg?v=0", caption: "cool canpopy"},
        {image: "http://farm1.static.flickr.com/155/421172107_2f20ec7aeb.jpg?v=0", caption: "cool tree"},
        {image: "http://farm1.static.flickr.com/54/133256387_e99cd967ff.jpg?v=0", caption: "vibrant rose"}
    ],

	set3: [// this needs to be the DOM ID attribute for the anchor tag to select this set
        {image: "http://farm1.static.flickr.com/46/167939744_2357ffe1af.jpg?v=0", caption: "white mountains"},
        {image: "http://farm1.static.flickr.com/48/177853809_ad9454a89e.jpg?v=0", caption: "small turtle"},
        {image: "http://farm1.static.flickr.com/54/183725415_ff609f45e4.jpg?v=0", caption: "mountain sunset"}
    ]
};

// 3 sets of image URLs
var data2 = {
	set4: // this needs to be the DOM ID attribute for the anchor tag to select this set
		["http://farm1.static.flickr.com/142/331222000_76f271e745.jpg?v=0",
		"http://farm1.static.flickr.com/159/384269775_f8b21b5e52.jpg?v=0",
		"http://farm1.static.flickr.com/178/415791942_4a4e411464.jpg?v=0"],

	set5: // this needs to be the DOM ID attribute for the anchor tag to select this set
		["http://farm1.static.flickr.com/186/421171930_80ef8ee7b2.jpg?v=0",
		"http://farm1.static.flickr.com/155/421172107_2f20ec7aeb.jpg?v=0",
		"http://farm1.static.flickr.com/54/133256387_e99cd967ff.jpg?v=0"],

	set6: // this needs to be the DOM ID attribute for the anchor tag to select this set
		["http://farm1.static.flickr.com/46/167939744_2357ffe1af.jpg?v=0",
		"http://farm1.static.flickr.com/48/177853809_ad9454a89e.jpg?v=0",
		"http://farm1.static.flickr.com/54/183725415_ff609f45e4.jpg?v=0"]
};

// an array of image URLs
var data3 = [
    "http://farm1.static.flickr.com/142/331222000_76f271e745.jpg?v=0",
	"http://farm1.static.flickr.com/159/384269775_f8b21b5e52.jpg?v=0",
	"http://farm1.static.flickr.com/178/415791942_4a4e411464.jpg?v=0",
    "http://farm1.static.flickr.com/186/421171930_80ef8ee7b2.jpg?v=0",
	"http://farm1.static.flickr.com/155/421172107_2f20ec7aeb.jpg?v=0",
	"http://farm1.static.flickr.com/54/133256387_e99cd967ff.jpg?v=0",
    "http://farm1.static.flickr.com/46/167939744_2357ffe1af.jpg?v=0",
	"http://farm1.static.flickr.com/48/177853809_ad9454a89e.jpg?v=0",
	"http://farm1.static.flickr.com/54/183725415_ff609f45e4.jpg?v=0"
];

You will need to include the following JavaScript library code for SomeWhatSimpleImageViewer to work:

<!--core dom and event framework-->
<script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/yahoo-dom-event/yahoo-dom-event.js"></script>

How it works…

Data set 1 shows how to add captions into your PhotoViewer, while set 2 is exactly the same as we used last week, and set 3 is supported for those of you who don’t need multiple image collections. You can see an example of all 3, Image Viewer Demo and the JavaScript code here. The Yahoo! library is included to support DOM manipulation, events, and type checking.

Lastly, a brand new feature was added that improves the initial performance of the PhotoViewer widget. I have noticed that in some browsers, like FF2+, even though we are pre-caching the images (using circa 1999 technology), the first time we clicked to see an image it takes an exceptionally long time to load, as if it wasn᾿t pre-cached (and it probably isn’t). Browsers have become rather smart and to improve performance they don᾿t always download files, when they don&rsquot;t believe they are necessary. Therefore, to defeat the browser intelligence, I have created a hidden node at the end of the body tag, in which we will append each image that we want to cache. This tricks the browser into downloading (and pre-caching) the images, thereby drastically improving the performance the first time iterates through the images in PhotoViewer.