Dojo in XPages – 22: Displaying an Image Gallery of Attachments

In the last post, I showed how to display a scrolling ThumbnailPicker of images attached to a document in XPages. In this post, we’ll look the Gallery widget, which displays thumbnails but also displays a larger version of the selected image.

Dojo in XPages Series

Dojo in XPages — All Blog Posts


The Gallery widget combines features of the Dojo ThumbnailPicker and Slideshow widgets. It displays a list of thumbnails, has an area to display a larger version of the selected image, and displays the image title (along with a counter). (Click to see the image larger.)

Dojo 22 - A

You can scroll through the thumbnails and click on a thumbnail to display a larger version of it after fading it in.

When you hover over the larger image area, you see additional controls. You’ll have a “left” arrow if you’re past the first image. You’ll also have a “Play” icon (right arrow) on the right. When clicked, it will start a slide show that will automatically scroll through the images. You can hover again and click the “stop” icon to end the slide show and remain on the current image. (These controls are only visible when hovering over the larger image area; the screen capture does not show the cursor.)

Dojo 22 - B

This is a very similar setup to the ThumbnailPicker — I actually implemented it just by changing the dojo module, changing the div tags’ dojoType, and adding the imageLargeAttr attribute to the image map and to each image object in the data store. However, in order to allow this to stand alone, I’ll show all of the code required to set it up. (For more of an explanation on the code, refer to the previous post.)

Step 1 – Include Dojo Modules and Stylesheet

There are two dojo modules and one dojo stylesheet that need to be included in order for it to work:

  <xp:dojoModule name=""></xp:dojoModule>
  <xp:dojoModule name="dojox.image.Gallery"></xp:dojoModule>
  <xp:styleSheet href="/.ibmxspres/dojoroot/dojox/image/resources/image.css"></xp:styleSheet>

Step 2- Add a div to render the gallery

Just add a div tag, give it an id to reference and set the dojoType to dojox.image.Gallery.

<div id="galleryDisplay" dojoType="dojox.image.Gallery"
  data-dojo-props="imageHeight:400, imageWidth:600">

Step 3 – Set the page to parse dojo on load

This property runs the Dojo parser when the page loads, so it will find the div with the dojoType attribute and generate the dijit.


Step 4 – Build the image data store and attach it to the gallery

In order to build this based on attachments on the current document, we want to build that list of items dynamically.

Each image url needs to be built in this format: DB.nsf/0/[docUNID]/$File/[attachmentname]

The code below will build that structure based on the files attached to the current document. It can run in the page’s onClientLoad event.

Line 1 gets the list of attachment names with @AttachmentNames().

Line 3 parses it to be an array, because it is returned to client-side javascript as a string surrounded in square brackets, with each value separated by a comma and a space. [file1.jpg, file2.jpg, file3.jpg]

Lines 6-9 set up objects that are required by the data store for the Gallery. The itemNameMap object defines the property that points to the large image and the “thumbnail” (in quotes because we’re not really using a thumbnail — we’ll just display the actual attachment as a thumbnail).

As shown previously, the data store needs an items property that is an array of objects (each with a large property, a thumb property and a title property). Lines 12-21 build array of objects for the data store.

Lines 23-27 set up the actual ItemFileReadStore object and provide it the data. The identifer property tells it which data property to use for the image title.

Line 32 finds the div with the id galleryDisplayand connects the data store to it in order to initialize it.

var fileNames =	"#{javascript:@AttachmentNames();}";
// It comes back as a concatenated string, surrounded by square brackets, to parse into an array
fileNames = fileNames.substring(1, fileNames.length-1).split(', ');
var docID = "#{javascript:currentDocument.getDocument().getUniversalID()}";

var itemNameMap = {
  imageThumbAttr: "thumb",
  imageLargeAttr: "large"

// Build an array of image items for the thumbnail's data store
var imageData = {};
imageData.items = [];
for (var i=0; i< fileNames.length; i++) {
  var newItem = {};
  newItem.thumb = './0/' + docID + '/$File/' + fileNames[i];
  newItem.large = './0/' + docID + '/$File/' + fileNames[i];
  newItem.title = 'Image: ' + fileNames[i];


// Initialize the data store
var imageStore = new{
  identifier: 'title',
  label: 'Images',
  data: imageData

var request= {}; 

// Initialize the Gallery 
dijit.byId('galleryDisplay').setDataStore(imageStore, request, itemNameMap);

If you use an xp:div rather than a passthru HTML div, then the last line will change to this:

dijit.byId('#{id:galleryDisplay}').setDataStore(imageStore, request, itemNameMap);

Changing the Slideshow Interval

You can modify the length of time between automatic advancement of pictures in the slideshow by adding a slideshowInterval property to the data-dojo-props attribute and specifying the number of seconds. There’s only one data-dojo-props attribute — if you already have a property defined, just add the additional property to the comma-separated list.

Here’s an example of the gallery div, with image and interval settings:

<div id="galleryDisplay" dojoType="dojox.image.Gallery"
  data-dojo-props="imageHeight:250, imageWidth:500, slideshowInterval:2">

Thumbnail Image Size

As shown in the previous post, you can use CSS to define the image size for the thumbnails if you’d like to change the defaults (75px high by 100px max width).

Other Data Stores

The focus of this post was how to use the gallery to display images attached to a document in XPages, but there are also data stores to work with Flickr and Picasa directly. (If you use those with large sets of images, you’ll want to update the request object to specify the count of images per request and, optionally, the starting point.)


8 responses to “Dojo in XPages – 22: Displaying an Image Gallery of Attachments”

  1. Jason says :


    Do you happen to have a working sample database.

    I tried following your articles , but I don’t get success on my side.

    Thank you in advance.

    • Brad Balassaitis says :

      I don’t have a demo database available yet (but I’m working on it). If there’s a specific example you want, I can e-mail you the full source for any of my demo pages.

      • Jason says :

        Hi Brad,

        Thanks for reply. I will just wait for your demo database so everybody out here can follow / achieve the goal we wanted. It nice to a have it.

        Pls provide the download demo , once available.

        More power and Thank you again!!!

      • Brad Balassaitis says :

        I have an online demo with examples of several of the Dojo posts now ( If you’d like the full source of any page, let me know and I’ll be happy to send it.

  2. Stephanie Widmer says :

    Hi Brad

    is it possible to get the full source code of the gallary image page.

    Thank you

  3. Brad Balassaitis says :

    It’s used in the live example. Are you opening the page with a document that has attachments ? (The page won’t have any thing to display otherwise.)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: