Dojo in XPages – 23: Using a Lightbox to Display Image Attachments

In recent posts, I showed how to create a thumbnail picker and a gallery of attached images on an XPage. In this post, I’ll show how to use the Lightbox widget to display images in a specialized dialog that provides a the ability to cycle through the images.

Dojo in XPages Series

Dojo in XPages — All Blog Posts


The Lightbox widget provides a nice way to focus on an image and display it centered on the screen in a dialog. Whatever portion of the page is unused (vertically) is darkened with an underlay so it stands out.

It is possible to create a link to open an individual image as in a Lightbox, but, in this post, I’m going to focus on how to create a group of images (based on attachments to the current document) in order to create more of a slideshow effect where you can click through the images.


The Lightbox displays one image at a time, but, when there is a group of images assigned to it, it also displays controls to move left and right through the images. There is also a button to close the dialog.

Additionally, the up and left arrow keys go back and the down and right arrow keys work go forward. The ESC key closes the dialog.

Generating the Lightbox only requires two steps — including required resources and programmatically creating the Lightbox and providing the list of images.

1) Include Required Resources

The dojox.image.Lightbox module is required, along with a corresponding stylesheet.

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

2) Creating the Lightbox and Providing Images

This code will automatically generate and display the Lightbox based on images attached to the page. Use the code in the onClientLoad event to render the Lightbox immediately or on a button or other client-side event to render it on demand.

Lines 2 and 4 retrieve the names of the file attachments on the current document and put them into an array.

Lines 8-9 programmatically create the Lightbox and initialize it.

Lines 12-14 cycle through the attachment names and add each image to the Lightbox dialog

// Add each attached image to the lightbox
// Build each URL in this format: DB.nsf.nsf/0/docUNID/$File/attachmentname
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()}";

// Initialize the Lightbox dialog 
var lbDialog = new dojox.image.LightboxDialog({});

// Add images to a group
for (var i=0; i< fileNames.length; i++) {
  lbDialog.addImage({ title:'Image: ' + fileNames[i], href:'./0/' + docID + '/$File/' + fileNames[i]}, 'imgGroup');

// Display the Lightbox, starting with the first image{group:"imgGroup", title:fileNames[0]}); 

Note: if you don’t specify the url for the first image to display, it’ll start with the first one, but display ‘undefined’ for the title. Line 17 passes in the first image title to avoid this.

Automatically Cycling Through the Images

If desired, you can easily add a timer to automatically cycle through the images, using the _nextImage() or _previousImage() methods of the Lightbox.

}, 3000);

This example works if added right after the code that creates the Lightbox. If you trigger this separately, then replace line 2 with something like this:


You’d also have to give the Lightbox widget an ID so you could refer to it this way.

Changing the Color of the Underlay

By default, it will darken the unused area at the end of your page with a black underlay. (This can look odd if you have some content on the page, but not the rest of the page, as only part of the page will be darkened.)

If you want to change the color of the underlay, you can add your own stylesheet and use a rule like this:

.dijitDialogUnderlay._underlay {

5 responses to “Dojo in XPages – 23: Using a Lightbox to Display Image Attachments”

  1. garycapra says :

    Hi Brad, I’ve implemented your post regarding using dojox lightbox and It’s working great, thanks so much for the post. I’m wondering if you might have a suggestion for an idea I’m working on: I have the lightbox loading onClinetLoad when the document is opened (from a view page), works fine. My question is: Would there be a way to close the page and return to the xpage view page when the lightbox is closed?

    Again thanks for sharing your talent with us.

    • Brad Balassaitis says :

      I haven’t tried that specifically, but the lightbox is a dialog, so maybe you can attach an event handler to the close event of the lightbox.

      I would try something like this:

      myDialog.connect(myDialog, “hide”, function(e){
      location.href = “”

  2. William Cather says :

    I’m using Notes 9.01 designer. When following your instructions the page fails on the line:
    var lbDialog = new dojox.image.LightboxDialog({}); line.
    I have the code in the onClientLoad event. It doesn’t seem that it’s loading the dojox.image.Lightbox resource. Maybe I don’t have the right code base? Any ideas.

  3. 97Hannelore says :

    I must say you have hi quality posts here.
    Your page can go viral. You need initial traffic only. How to get it?
    Search for: Etorofer’s strategies

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: