Dojo in XPages – 25: Badge — A Cool Image Widget that’s Hard to Explain

In this post, I’ll demonstrate how to create the Badge widget to display image thumbnails with size animation within a tabular structure. This is a cool variation of a gallery; it displays rows of image thumbnails and automatically expands and collapses them. (It’s difficult to convey the functionality until you see an example.)

Dojo in XPages Series

Dojo in XPages — All Blog Posts

dojx.Image.Badge

The Dojo documentation says that the Badge widget loops images. That’s pretty much all it says. (The rest of the page is full of lines starting with “TODO:”.)

Maybe they couldn’t figure out how to explain it, either!

Regardless of the lack of documentation, it is very cool widget to work with images. It creates a table-like structure with image thumbnails and it expands them across multiple cells on a seemingly-random basis.

Each image starts out as a thumbnail, but one at a time expands to be double its size (taking up a 2×2 area in the layout, covering 3 other images). It then shrinks back to it’s original place and another image expands.

Here’s an example of 12 images in a 2×6 layout:

Here’s an example of the same images in a 4×3 layout:

Neither of these screen shots appear to show 12 images, but they’re there. When one image is doubled, it covers 3 other images until it shrinks back down to its original size, and then another one is increased.

This looping through the images is part of the built-in functionality of the Badge widget. This is great for providing some animation on pages that may be open for awhile, but may otherwise be static.

Here are the steps to creating your own Badge widget:

1) Include Required Resources

In order for this to work, you need to make the dojox.Image.Badge module and the Image.css stylesheet available to the page.

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

2) Set the Page Property to Parse Dojo on Load

Since we’ll use a declarative approach to create this widget, the page’s Trigger Dojo parse on load property must be selected (dojoParseOnLoad="true")

3) Create a Badge DIV and Images

For the Badge container, add a div with the dojoType set to dojox.image.Badge.

Define the number of rows and columns to display the images with attributes of the div.

The children property is a selector for the images to display as thumbnails and animate. It should be set to img.[className] where the classname is a class that is applied to all image tags within the div. In this example, I set them to badgeIMG in this example.

<div dojoType="dojox.image.Badge" rows="2" cols="6" children="img.badgeIMG">
  <xp:image url="/nature1.jpg" id="image13" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature2.jpg" id="image14" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature3.jpg" id="image15" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature4.jpg" id="image16" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature5.jpg" id="image17" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature6.jpg" id="image18" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature7.jpg" id="image19" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature8.jpg" id="image20" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature9.jpg" id="image21" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature10.jpg" id="image22" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature11.jpg" id="image23" styleClass="badgeIMG"></xp:image>
  <xp:image url="/nature12.jpg" id="image24" styleClass="badgeIMG"></xp:image>
</div>

This is all you need to do to set it up! Once you load the page, you should have a live Badge widget.

The next few sections cover attributes that are available for customizing the behavior.

Image Sizing

By default, the thumbnails are 50-pixel squares. If you want to change the size, you can set the cellSize attribute of the Badge div.

This example changes the thumbnail size to 150-pixel squares.

<div dojoType="dojox.image.Badge" rows="2" cols="6" children="img.badgeIMG" cellSize="150">

Transition Delay

Another attribute you can change is the delay between resizing images. The default seems to be 2.5-3 seconds, but you can change that with the delay attribute, where you define the value in milliseconds. To extend the delay to 5 seconds, set the delay to 5000.

<div dojoType="dojox.image.Badge" rows="2" cols="6" children="img.badgeIMG" delay="5000">

If you want to annoy your users, set it to 100.

Adding Threads

The thread count is the number of images that are enlarged at a time. The default is 1, but you can increase this with the thread attribute. This can be a cool effect with a larger data set (especially because they don’t all animate at the same time — their timing is offset), but use it wisely; images will often overlap if there are too many threads. Even 3 is too many for my set of 12 images.

If you really want to annoy your users, increase the thread count while also drastically decreasing the delay.

More Examples

This Dojo demo page has additional examples of this in use.

Interestingly, if you look at the example in the upper right hand corner of the page, it looks like you can create the same effect with a bunch of div tags, rather than images.