Gallery

dojox.image.Gallery is a widget that displays a series of thumbnail sized images, for quick browsing and selection, and a single large image. It provides a number of navigation controls for moving between images, and for playing an automated slideshow.

The Gallery works as a wrapper around two other widgets, dojox.image.ThumbnailPicker and dojox.image.SlideShow. It provides the following features:

• A row of thumbnail sized images. Clicking on a thumbnail image shows a large version of that picture in the main image pane. Navigation controls are placed to the left and right of the thumbnails, to move between them.
• A large image pane, displaying one image at a time. Navigation controls when the mouse pointer is over the image pane, allowing the user to move backwards and forwards between the images, and to start an automated slideshow. The size of the image pane is configurable using the imageWidth and imageHeight attributes.
• Reads image data from an implementation of the dojo.data.api.Read interface. This means it is completely decoupled from any particular data source, and can be used with any data source at all as long as it is a valid dojo.data store. For example, the Gallery can display images based on data in a simple text file using dojo.data.ItemFileReadStore, can show Flickr images using dojox.data.FlickrRestStore, or images from Picasa Web Albums using dojox.data.PicasaStore.
• Displays the title of each image, using a template that can be simply overridden.
• Links an image to a URL, so that clicking the image navigates to a specified web address. This is optional.

Examples

Creating a Gallery and setting a simple data source

<script type="text/javascript">
  //Define the attribute names used to access the items in the data store
  var itemNameMap = {imageThumbAttr: "thumb", imageLargeAttr: "large"};

  //Define the request, with no query, and a count of 20, so 20 items will be 
  //requested with each request
  var request = {query: {}, count: 20};
  dijit.byId('gallery1').setDataStore('imageItemStore', request, itemNameMap);
</script>

<div id="gallery1" dojoType="dojox.image.Gallery"></div>
<div jsId="imageItemStore" dojoType="dojo.data.ItemFileReadStore" url="images.json"></div>

Creating a Gallery with a FlickrRestStore

<script type="text/javascript">
  //Declare a FlickrRestStore data store.  This is used to access images from the 
  //Flickr (www.flickr.com) photo sharing website.
  var flickrRestStore = new dojox.data.FlickrRestStore();

  //Define the request, with a count of 20, so 20 items will be requested with 
  //each request. The query specifies information used to access Flickr, 
  //including a user ID (optional) and API key (required).  
  //You can also specify a sort order, tags to search for, and the matching 
  //mode for the tags, which can be "any" or "all", which equate to boolean "or" 
  //and a boolean "and" respectively
  var request = {
        query: {
            userid: "44153025@N00",//The Flickr user id to use
            apikey: "8c6803164dbc395fb7131c9d54843627",//An API key is required.
            sort: [{
                    descending: true //Use descending sort order, ascending is default.
                }
		],
                tags: ["superhorse", "redbones", "beachvolleyball","dublin","croatia"],
		tag_mode: "any" //Match any of the tags
         },
         count: 20
  };
  
  dijit.byId('gallery1').setDataStore('imageItemStore', request, itemNameMap);
</script>
  <div id="gallery1" dojoType="dojox.image.Gallery"></div>

Setting the image width and height

<div id="gallery1" dojoType="dojox.image.Gallery" imageHeight="400" imageWidth="600"></div>

Setting Page Size and AutoLoad

It is possible to define how many images are requested from the data store with each request. This affects the performance. The larger the page size, the slower a request may be, but there will be fewer requests. The smaller the page size, the quicker a request may be, but there will be more requests. It is specified by altering the pageSize attribute.

By default, the Gallery will preload one page of images at a time. This gives a better user experience, as the user will have to wait less time to view an image. However, it may download more images than the user wishes to view. The autoloading of images can be disabled by setting the autoLoad attribute to "false".

<div id="gallery1" dojoType="dojox.image.Gallery" pageSize="50" autoLoad="false" ></div>

Changing the time interval in a SlideShow

The images in the large pane of the Gallery can be made to run a slide show by clicking its "Play" button. The amount of time between changing images can be configured by setting the slideshowInterval attribute to the number of seconds required.

<div id="gallery1" dojoType="dojox.image.Gallery" slideshowInterval="5" ></div>

Lightbox

TODO: Fill in info on dojox.image.Lightbox / finish / elaborate more

dojox.image.Lightbox

A clone of Lightbox2 for dojo. A Lightbox displays images in a modal dialog. It can display single images, or image groups, with smooth transition animations in between. You can populate the Lightbox group from a dojo.data datastore, or from markup.

Basic Usage

Being a clone, it is almost completely backwards compatible with Lightbox2. The Lightbox will display the image linked to in an anchor tag. Using a Lightbox is as easy as adding a dojoType to a link tag:

show image1

Grouping images together is as simple as adding a group="" attribute. In this example, the first image is a single view, the other two popup a Lightbox with [previous] and [next] navigation, and 2 images in a group.

show image1
show image2
show image3

Your anchor text can be anything: a thumnail of the image to show, text, etc. It can also be anywhere on a page.

With JavaScript disabled, the natural link to the image will pass through, and display the image natively

Slideshow

[inline:slideshow.jpg]

The dojox.image.SlideShow widget displays a series of images, one at a time. It provides controls to move from image to the next or the previous image. It can also run an automated slideshow, moving from one image to the next every specified number of seconds.

Features

The Slideshow widget has the following features.

• Displays a single image at a time
• Provides navigation controls to move between images, and to start/stop the automated slideshow.
• Can optionally pre-load images in the background so that there is no visible delay when viewing images. While this uses more bandwidth, it provides a far better user experience.
• Links an image to a URL, so that clicking the image navigates to a specified web address. This is optional.
• Reads image data from an implementation of the dojo.data.api.Read interface. This means it is completely decoupled from any particular data source, and can be used with any data source at all as long as it is a valid dojo.data store. For example, the Slideshow can display images based on data in a simple text file using dojo.data.ItemFileReadStore, can show Flickr images using dojox.data.FlickrRestStore, or images from Picasa Web Albums using dojox.data.PicasaStore.
• Displays the title of each image, using a template that can be simply overridden.

Examples

Setting the Display Interval

It is possible to define the number of seconds between image transitions when running an automated slideshow. To do this, set the slideshowInterval attribute. For example, to set a three second interval between changing the displayed image, use the code below

<div dojoType="dojox.image.SlideShow" id="slideshow1" slideshowInterval="3"> </div>

Overriding the Title Template

The Slideshow widget has a default title template that is used to display the title of the current image, as well as it's relative position. To do this, set the titleTemplate attribute. The supported place holders are :

• @title - The title of the image is placed here
• @current - The current index of the image is placed here
• @total - The total number of images is placed here.

For example:

<div dojoType="dojox.image.SlideShow" id="slideshow1" 
    titleTemplate="My title is '@title', this is image @current out of @total"
> </div>

Setting the Maximum Image Dimensions

To override the default height and width of the widget, set the imageHeight and imageWidth attributes. Images are automatically scaled to fit either the max height or width, depending on which of their dimensions is greater. E.g

<div dojoType="dojox.image.SlideShow" id="slideshow1" 
    imageWidth="600" imageHeight="300"
> </div>

Disabling the AutoLoad

The Slideshow widget automatically preloads a number of images in the background. While this generally provides a better user experience, it uses more bandwidth, so some users may want to disable it. To do so, set the autoLoad parameter to "false". e.g.

<div dojoType="dojox.image.SlideShow" id="slideshow1" 
    autoLoad="false"
> </div>

This causes a delay when the user attempts to view an image, since it must wait to be loaded.

Disabling Resizing to Fit the Image

By default, if an image is less tall than the Slideshow widget, the widget resizes itself to fit to the image. In some circumstances this may be undesireable, such as when using an inflexible, fixed page layout. To disable this resizing behaviour, set the fixedHeight attribute to "true", e.g.

<div dojoType="dojox.image.SlideShow" id="slideshow1" 
    fixedHeight="true"
> </div>

Setting the Data Store on the Slideshow

The Slideshow widget reads the image information from dojo.data objects. To set the data source for the Slideshow widget, first create one of the available data stores, such as the dojo.data.ItemFileReadStore or dojox.data.FlickrRestStore. Next, create a request object, which optionally contains a query. e.g.

<div dojoType="dojox.image.SlideShow" id="slideshow1" > </div>
<div jsId="imageItemStore" dojoType="dojo.data.ItemFileReadStore" url="images.json"></div>
<script type="text/javascript">
dojo.addOnLoad(function() {
  //Define the request, saying that 20 records should be fetched at a time, 
  //and to start at record 0
  var request= {count:20, start:0};

  //Tell the widget to request the "large" parameter, as different 
  //stores may use different parameter names
  var itemNameMap = {imageLargeAttr: "large"};

  //Call the setDataStore function, passing it the data store, the request object, 
  //and the name map.
  dijit.byId('slideshow1').setDataStore(imageItemStore, request, itemNameMap);
});

</script>

Subscribing to Slideshow Events

The Slideshow publishes information about its state, that can be subscribed to using Dojo's Publish/Subscribe system. Two pieces of information are published to a named topic:

• Current image - whenever the displayed image changes, a JSON object with the following attributes:
  • index - The current numeric index of the image, that is, it's index in the data store
  • title - The string title of the image, if any
  • url - The URL of the image
  The name of the topic is retrieved by calling the getShowTopicName method on the widget

  dojo.subscribe(
      dijit.byId('slideshow1').getShowTopicName(), 
      function(packet) {
        alert("Got index: " + packet.index 
                   + ", url: " + packet.url 
                   + ", and title: " + packet.title);
  });

• Loaded Image - when an image finishes loading, whether in the background, or the currently displayed image, information is published about it. The name of the topic is retrieved by calling the getLoadTopicName on the widget. A Number is published, which is the index of the image in the data store. E.g.

  dojo.subscribe(
      dijit.byId('slideshow1').getLoadTopicName(), 
      function(index) {
        alert("Got index: " +index);
  });

Further Examples

For a full example of the Slideshow, see the test file at http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/image/tests/tes...

ThumbnailPicker

[inline:thumbpicker.gif]

The ThumbnailPicker is a widget that displays a series of images either horizontally or vertically, with controls to page through the images. It reads its image data from data stores, that is, implementations of the dojo.data.api.Read API.

When an image is clicked by the user, information regarding that image is published to a dojo topic, which can be used to integrate the ThumbnailPicker with other objects on the page.

The ThumbnailPicker can be configured in a number of ways:

• Number of visible images
• Data source
• Can be horizontal or vertical
• Enabling/disabling following hyperlinks when an image is selected
• Notification of load status for images

Examples

Number of Visible Images

To set the number of visible images, and thereby the width or height of horizontal and vertical widgets respectively, set the <b>numberThumbs</b> attribute, e.g.

<div dojoType="dojox.image.ThumbnailPicker" id="picker1" numberThumbs="4"> </div>

Setting the Data Source

To set the data source for the ThumnailPicker widget, first create one of the available data stores, such as the dojo.data.ItemFileReadStore or dojox.data.FlickrRestStore. Next, create a request object, which optionally contains a query. e.g.

<div dojoType="dojox.image.ThumbnailPicker" id="picker1" > </div>
<div jsId="imageItemStore" dojoType="dojo.data.ItemFileReadStore" url="images.json"></div>
<script type="text/javascript">
dojo.addOnLoad(function() {
  //Define the request, saying that 20 records should be fetched at a time, 
  //and to start at record 0
  var request= {count:20, start:0};
  //Tell the widget to request the "thumb" parameter, as different 
  //stores may use different parameter names
  var itemNameMap = {imageThumbAttr: "thumb"};

  dijit.byId('picker1').setDataStore(imageItemStore, request, itemNameMap);
});

</script>

Using a Vertical Layout

To make the ThumbnailPicker display itself vertically, set the isHorizontal attribute to "false". To leave it as horizontal, either omit the isHorizontal attribute, or set it to "true", e.g.

<div dojoType="dojox.image.ThumbnailPicker" id="picker1" isHorizontal="false"> </div>

Enabling/disabling following hyperlinks

To enable following a hyperlink when a thumbnail image is clicked, set the useHyperlink attribute to "true". By default it is false. When hyperlinks are enabled, by default the URL is opened is a new window. To open the link in the current window, set the hyperlinkTarget attribute to "this". e.g.

<div dojoType="dojox.image.ThumbnailPicker" id="picker1" useHyperlink="true" hyperlinkTarget="this"> </div>

Notification of load status for images

The ThumbnailPicker can display a notification for each image stating whether another version of it has loaded or not, for example when it is combined with the dojox.image.Slideshow widget. When this is enabled, the ThumbnailPicker relies on other code calling it's markImageLoaded method to change the notification from its loading state to loaded state.

To enable the load state notifier, set the useLoadNotifier to "true". By default, it is disabled, since it only really makes sense to use it in combination with other widgets or elements on a page. e.g.

<div dojoType="dojox.image.ThumbnailPicker" id="picker1" useLoadNotifier="true"> </div>

Full Example

This example will put a horizontal and a vertical dojox.image.ThumbnailPicker widget on a page, with a variety of settings, and using separate data stores.

<html>
<head>
  <style type="text/css">
    @import "../resources/ThumbnailPicker.css";
  </style>
  
  <script type="text/javascript" src="dojo/dojo.js" djconfig="parseOnLoad:true, isDebug: true, defaultTestTheme:'soria'"></script>
  <script type="text/javascript" src="/dijit/tests/_testCommon.js"></script>

  <script type="text/javascript" src="dojox/image/ThumbnailPicker.js"></script>
  
  <script type="text/javascript">
    /*
      The FlickrRestStore and the ItemFileReadStore data stores will be used to provide data to the widgets
    */
    dojo.require("dojox.data.FlickrRestStore"); 
    dojo.require("dojo.data.ItemFileReadStore"); 
    dojo.require("dojo.parser");  // find widgets
    
    /*
      Initializes the ThumbnailPicker with a data store that reads from the Flickr REST APIs.
    */
    function initFlickrWidget() {
      //Create a new FlickrRestStore
      var flickrRestStore = new dojox.data.FlickrRestStore();
      
      //Create a request object, containing a query with the 
      //userid, apikey and (optional) sort data.
      //Extra query parameters 'tags' and 'tag_mode' are also 
      //used to further filter the results
      var req = {
        query: {
          userid: "44153025@N00",//The Flickr user id to use
          apikey: "8c6803164dbc395fb7131c9d54843627",//An API key is required.
          sort: [
               {
              descending: true //Use descending sort order, ascending is default.
              }
               ],
          tags: ["superhorse", "redbones", "beachvolleyball","dublin","croatia"],
          tag_mode: "any" //Match any of the tags
        },
        start: 0, //start at record 0
        count: 20 //request 20 records each time a request is made
      };
      
      //Set the flickr data store on two of the dojox.image.ThumbnailPicker widgets
      dijit.byId('thumbPicker1').setDataStore(flickrRestStore, req);
    }
    
    /*
      Initializes the second ThumbnailPicker widget with a data store that
      reads information from a JSON URL.  This also tells the ThumbnailPicker
      the name of the JSON attributes to read from each data item retrieved
      from the JSON URL.
    */
    function initItemStoreWidget(){
      var itemRequest = {
        query: {},
        count: 20
      };
      var itemNameMap = {
        imageThumbAttr: "thumb",
        imageLargeAttr: "large"
      };
      
      //Set the dojo.data.ItemFileReadStore on two of the dojox.image.ThumbnailPicker widgets
      //Note the use of the 'itemNameMap', which tells the widget what attributes to
      //read from the store.  Look in the 'images.json' file in the same folder as this
      //file to see the data being read by the widget.
      dijit.byId('thumbPicker2').setDataStore(imageItemStore, itemRequest, itemNameMap);
    }
    
    //Subscribe to clicks on the thumbnails, and print out the information provided
    function doSubscribe(){
      function updateDiv(packet){
        alert("You selected the thumbnail:"
            + "Index: " + packet.index
            + "Url: " + packet.url
            + "Large Url: " + packet.largeUrl
            + "Title: " + packet.title
            + "Link: " + packet.link)
            ;
      }
      
      //When an image in the ThumbnailPicker is clicked on, it publishes
      //information on the image to a topic, whose name is found by calling
      //the 'getTopicName' function on the widget.
      dojo.subscribe(dijit.byId('thumbPicker1').getTopicName(), updateDiv);
      dojo.subscribe(dijit.byId('thumbPicker2').getTopicName(), updateDiv);
    }
    
    dojo.addOnLoad(initFlickrWidget);
    dojo.addOnLoad(initItemStoreWidget);
    dojo.addOnLoad(doSubscribe);
  </script>
</head>
<body>
  <h2>From FlickrRestStore:</h2>
  This ThumbnailPicker should have 8 thumbnails, with each of them linking
  to a URL when clicked on, changing the current page.  The cursor should also change when over an image.
  The widget is laid out in the default horizontal layout.
  <div id="thumbPicker1" dojoType="dojox.image.ThumbnailPicker" numberThumbs="8" useHyperlink="true" 
        hyperlinkTarget="this"></div>

  <h2>From ItemFileReadStore:</h2>
  This ThumbnailPicker should have 5 thumbnails. Clicking on a thumbnail should NOT
  open a URL, and the cursor should not change when over an image that is not an arrow.
  The widget is laid out in a vertical layout.
  
  <div id="thumbPicker2" dojoType="dojox.image.ThumbnailPicker" numberThumbs="5" isClickable="false"
        isHorizontal="false"></div>
  
  Create an ItemFileReadStore that reads data from the file "images.json".  This is used by the ThumbnailPicker "thumbPicker2"
  <div jsId="imageItemStore" dojoType="dojo.data.ItemFileReadStore" url="images.json"></div>

</body>
</html>

The code above would result in a page that looks like the image below:

[inline:testPage.gif] Further examples can be found in the test file at http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/image/tests/tes...

TODO: put info on dojox.image.ThumbnailPicker