Learning the Markup

Since Dojo implements markup just as it is in Django's implementation, the best place to visit would be their excellent book or their excellent documentation

But in case you are just itching to know what it looks like, it's made up of some simple parts: {% tags %}, {{ variables }}, and {{ variables|filtered }} and {{ variables|more:"advanced"|filtering }}. Sometimes tags have a start and an end tag, sometimes they work alone.

The Base Constructors: Templated and HtmlTemplated

We have 2 base constructors when using DTL outside of a widget: dojox.dtl.Template and dojox.dtl.HtmlTemplate.

Template works only with text. What this means is that you can't use it to do DOM manipulation, you can only use it to generate text that you might use to set a node's innerHTML.

HtmlTemplate is an extension to Templated, which means in terms of size, that it's the full size of Template plus some more code. But using HtmlTemplate, you can do direct DOM manipulation. This means that if a node is inside of an /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.javascript .imp {font-weight: bold; color: red;}
.javascript .kw1 {color: #000066; font-weight: bold;}
.javascript .kw2 {color: #003366; font-weight: bold;}
.javascript .kw3 {color: #000066;}
.javascript .co1 {color: #009900; font-style: italic;}
.javascript .coMULTI {color: #009900; font-style: italic;}
.javascript .es0 {color: #000099; font-weight: bold;}
.javascript .br0 {color: #66cc66;}
.javascript .st0 {color: #3366CC;}
.javascript .nu0 {color: #CC0000;}
.javascript .me1 {color: #006600;}
.javascript .re0 {color: #0066FF;}
{% if %} block, it will be removed from DOM if the logic is false, and will be added to DOM if the logic is true.

Both of these constructors can take either plain text, or a URL. HtmlTemplate can also accept a node.

Creating and Rendering a Template in Plain Text

Creating a new instance

As mentioned in the previous chapter, you can create a new instance of dojox.dtl.Template using either a URL or a string.

Once you've created an instance of this object (which now contains a compiled version of your template that you can render as many times as you want), you have a few options:

The update function

Every dojox.dtl.Template instance will have an update function. This function will change the innerHTML of a node, or a list of nodes. This function accepts a node, a node ID, or a dojo.query result as its first parameter, and an object or URL as its second parameter, to be used as a context.

The render function

This works exactly the same as rendering a template in Django.

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.geshifilter {font-family: monospace;}
.geshifilter .imp {font-weight: bold; color: red;}
.geshifilter .kw1 {color: #000066; font-weight: bold;}
.geshifilter .kw2 {color: #003366; font-weight: bold;}
.geshifilter .kw3 {color: #000066;}
.geshifilter .co1 {color: #009900; font-style: italic;}
.geshifilter .coMULTI {color: #009900; font-style: italic;}
.geshifilter .es0 {color: #000099; font-weight: bold;}
.geshifilter .br0 {color: #66cc66;}
.geshifilter .st0 {color: #3366CC;}
.geshifilter .nu0 {color: #CC0000;}
.geshifilter .me1 {color: #006600;}
.geshifilter .re0 {color: #0066FF;}

Use dojo.query

With the dojo.query extension, you don't even need to create a template instance. What this means is that repeatedly rendering a template will be slightly slower, but your code will be more compact.

To use, make sure you require the dojox.dtl.ext-dojo.NodeList module, which adds the dtl function. It accepts a string or URL as its first parameter, and an object or URL as its second parameter. Like the update function above, it will change the innerHTML values of all nodes in the dojo.query result, using the first parameter as its template and the second parameter as its context.

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.geshifilter {font-family: monospace;}
.geshifilter .imp {font-weight: bold; color: red;}
.geshifilter .kw1 {color: #000066; font-weight: bold;}
.geshifilter .kw2 {color: #003366; font-weight: bold;}
.geshifilter .kw3 {color: #000066;}
.geshifilter .co1 {color: #009900; font-style: italic;}
.geshifilter .coMULTI {color: #009900; font-style: italic;}
.geshifilter .es0 {color: #000099; font-weight: bold;}
.geshifilter .br0 {color: #66cc66;}
.geshifilter .st0 {color: #3366CC;}
.geshifilter .nu0 {color: #CC0000;}
.geshifilter .me1 {color: #006600;}
.geshifilter .re0 {color: #0066FF;}

Writing a Widget

We'll bypass how to use the raw HtmlTemplate object (we'll get into that later) and explain how to write a widget using Dojo's implementation of the Django Template Language.

Both of the solutions covered here work almost exactly like dijit._Templated, which is covered elsewhere in the book. To use the text version, mix in dojox.dtl._Templated and to use the HTML version, mix in dojox.dtl._HtmlTemplated.

These objects will use templatePath, templateString, and use the dojoAttachPoint and dojoAttachEvent node attributes.

They add a single function: render. This function is to be used in the event of re-rendering. One of the main reasons for re-render would be if not all data was available during instantiation. The template will be rendered during creation even if you don't call the render function.

The template will be rendered using the widget object as its context. If you don't want this behavior, you can pass your own Context object to the render function.

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.geshifilter {font-family: monospace;}
.geshifilter .imp {font-weight: bold; color: red;}
.geshifilter .kw1 {color: #000066; font-weight: bold;}
.geshifilter .kw2 {color: #003366; font-weight: bold;}
.geshifilter .kw3 {color: #000066;}
.geshifilter .co1 {color: #009900; font-style: italic;}
.geshifilter .coMULTI {color: #009900; font-style: italic;}
.geshifilter .es0 {color: #000099; font-weight: bold;}
.geshifilter .br0 {color: #66cc66;}
.geshifilter .st0 {color: #3366CC;}
.geshifilter .nu0 {color: #CC0000;}
.geshifilter .me1 {color: #006600;}
.geshifilter .re0 {color: #0066FF;}

New "Contributed" Tags and Filters for a the Browser and Dojo

To Use

These tag/filter sets can be included with either dojo.require, or the /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.javascript .imp {font-weight: bold; color: red;}
.javascript .kw1 {color: #000066; font-weight: bold;}
.javascript .kw2 {color: #003366; font-weight: bold;}
.javascript .kw3 {color: #000066;}
.javascript .co1 {color: #009900; font-style: italic;}
.javascript .coMULTI {color: #009900; font-style: italic;}
.javascript .es0 {color: #000099; font-weight: bold;}
.javascript .br0 {color: #66cc66;}
.javascript .st0 {color: #3366CC;}
.javascript .nu0 {color: #CC0000;}
.javascript .me1 {color: #006600;}
.javascript .re0 {color: #0066FF;}
{% load %} tag.

Attribute Tags

Before we get to the list, it's important to note that HtmlTemplate considers attributes to be a full-fledged part of the template system. What this means is that there are new tags that have been introduced that use named attributes in order perform new actions. For the curious tag author, this is accomplished by registering a named tag with "attr:" in front of it

dojox.dtl.contrib.dijit

These tags are only applicable to the HTML version of the template system. If you want the same behavior in a text-based environment, you have to use the dojox.dtl._Templated mixin on a widget. These tags will work even if they are used outside of dojox.dtl._HtmlTemplated.

• Node Attribute: dojoType: If widgetsInTemplate is set on a widget, or if the global dojox.dtl.contrib.dijit.widgetsInTemplate is set, the node will be instantiated as a widget of that type.
• Node Attribute: dojoAttachPoint: Works exactly the same as the Dijit templated equivalent
• Node Attribute: attach/dojoAttachPoint: Works exactly the same as the Dijit templated equivalent
• Node Attribute: dojoAttachEvent: Works exactly the same as the Dijit templated equivalent
• Note Attribute: onclick/onmouseover/etc: The string you have in its value is the name of the function to call when that action is performed. eg onclick="goHome"

dojox.dtl.contrib.html

These are also only applicable to the HTML version. The html tag is especially important because, without it, the variable contents are always rendered as text.

• html: If you want to render a variable as HTML, you have to use {% html varName %}
• Node Attribute: tstyle: Use if you want to change style attributes during rendering. eg tstyle="top: {{ y }}px;"

dojox.dtl.contrib.data

This allows you to take a given data store, a given list of items, and assign them to a single variable that can be used as if each item was a normal variable.

In the example below, /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.javascript .imp {font-weight: bold; color: red;}
.javascript .kw1 {color: #000066; font-weight: bold;}
.javascript .kw2 {color: #003366; font-weight: bold;}
.javascript .kw3 {color: #000066;}
.javascript .co1 {color: #009900; font-style: italic;}
.javascript .coMULTI {color: #009900; font-style: italic;}
.javascript .es0 {color: #000099; font-weight: bold;}
.javascript .br0 {color: #66cc66;}
.javascript .st0 {color: #3366CC;}
.javascript .nu0 {color: #CC0000;}
.javascript .me1 {color: #006600;}
.javascript .re0 {color: #0066FF;}
{{ item.title }} will be the equivalent of calling: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.javascript .imp {font-weight: bold; color: red;}
.javascript .kw1 {color: #000066; font-weight: bold;}
.javascript .kw2 {color: #003366; font-weight: bold;}
.javascript .kw3 {color: #000066;}
.javascript .co1 {color: #009900; font-style: italic;}
.javascript .coMULTI {color: #009900; font-style: italic;}
.javascript .es0 {color: #000099; font-weight: bold;}
.javascript .br0 {color: #66cc66;}
.javascript .st0 {color: #3366CC;}
.javascript .nu0 {color: #CC0000;}
.javascript .me1 {color: #006600;}
.javascript .re0 {color: #0066FF;}
store.getValue(item, "title"};

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.geshifilter {font-family: monospace;}
.geshifilter .imp {font-weight: bold; color: red;}
.geshifilter .kw1 {color: #000066; font-weight: bold;}
.geshifilter .kw2 {color: #003366; font-weight: bold;}
.geshifilter .kw3 {color: #000066;}
.geshifilter .co1 {color: #009900; font-style: italic;}
.geshifilter .coMULTI {color: #009900; font-style: italic;}
.geshifilter .es0 {color: #000099; font-weight: bold;}
.geshifilter .br0 {color: #66cc66;}
.geshifilter .st0 {color: #3366CC;}
.geshifilter .nu0 {color: #CC0000;}
.geshifilter .me1 {color: #006600;}
.geshifilter .re0 {color: #0066FF;}

You can also use: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */
.javascript .imp {font-weight: bold; color: red;}
.javascript .kw1 {color: #000066; font-weight: bold;}
.javascript .kw2 {color: #003366; font-weight: bold;}
.javascript .kw3 {color: #000066;}
.javascript .co1 {color: #009900; font-style: italic;}
.javascript .coMULTI {color: #009900; font-style: italic;}
.javascript .es0 {color: #000099; font-weight: bold;}
.javascript .br0 {color: #66cc66;}
.javascript .st0 {color: #3366CC;}
.javascript .nu0 {color: #CC0000;}
.javascript .me1 {color: #006600;}
.javascript .re0 {color: #0066FF;}
{{ item.getLabel }}, {{ item.getAttributes }}, and {{ item.getIdentity }}

Note that there's a little weirdness with getValue and getValues. If you want to be sure that getValues is called, just add an extra "s" to the end of your variable name.

Using the Extends Tag

In Django, the extends tag looks through the installed applications until it finds the named template. In a browser environment, we don't want to have to go searching for templates, so there has to be a way to reference a specific file, while not changing the markup style of the extends tag.

The "easiest" way to do this is to put an explicit reference to the template. This means that you need to specify a URL in relation to your root page. But doing it like this creates a problem if you want to move around your directory structure, or if a page in a different directory wants to use the template.

Django helps us out by allowing a variable name to be used in the extends tag. What we can do with this, then, is set a variable in the Context using dojox.moduleUrl.

If we're using the extends tag in an HTML environment, there's another factor to consider. Let's say we have a blog and there are two ways of viewing the page: a list view, and a detail view. Both of these views use a parent node that contains the page header, a menu, and a sidebar. We don't want the template system to have to redraw the DOM for their parent template, but how do we indicate that? There are two ways, one which is significantly better than the other.

The first is to use a string in the extends tag, outlined in the "easiest" way at the top. Putting "shared:" at the beginning of the string tells the extends tag to reuse the nodes between all other children that also want to share the parent.

The significantly better way is partly outlined in the section above on moduleUrl. You can use a variable containing a moduleUrl, but how do you tell the extends tag that you want to share the parent? Instead of just passing a moduleUrl call, when we have an extends tag that looks like {% extends parent %}, we can use an object that looks like this:

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

New Context Object Abilities

Unlike the page serving model of Django, we can keep our Context objects around between each template render. What we want to be able to do is quickly clone an existing context, and either reduce, or add to, the data in the object. To do this, there are two new functions:

• filter: Just put the keys you want to key in its arguments to get only those keys back in a cloned Context.
• extend: Just pass it an object to get a cloned Context containing all of the old keys, plus the new ones.

Some new functions are added to allow tags to communicate with the rendering object.

• setThis: Sets the object on which to perform operations. Used by the attach attribute tag, for example.
• getThis: Used by tags, gets the currently set this object.

Advanced Topics

While Django provides some documentation about how their compiler works, which you should definitely read before continuing this section, there are some areas in which things are done differently, such as tag and filter registration.

The other major difference in Dojo's implementation is the new HTML compiler. This section will go over how much of what we've done was accomplished, and will provide information to those curious about how the normal text-based compiler works.

Drawing with GFX

dojox.gfx

 

What is it?

dojox.gfx is a cross-platform declarative interactive graphics package. It follows SVG loosely as the underlying model. At present time SVG and VML back-ends are implemented.

What does it do?

The dojox.gfx package provides graphics rendering and manipulation. Under Firefox, Opera and Safari dojox.gfx renders the final product as SVG, under IE it renders as VML.

Potentially the gfx package can allow you to create live and interactive graphing, a web based vector drawing program, view svg files in IE.

Underlying concepts

On conceptual level dojo.gfx has a simple declarative model: All basic primitives required for 2D graphics are defined:

• 2D coordinates
• 2D linear transformation matrices
• colors

There is a surface, which serves as a visual rectangular container for shapes:

• A web page can have several surfaces defined.
• Each surface has its own local coordinate system:
  • (0, 0) point is in the left-top corner, where the X axis is horizontal pointing right, and the Y axis is vertical pointing down.
  • Positive direction of rotation is defined as counter-clockwise (CCW).

There is a notion of a shape description object, which represent a simple description of geometry, with corresponding shape objects. dojox.gfx supports following shapes:

• Rectangle (optionally with rounded corners).
• Circle.
• Ellipse.
• Line.
• Polyline/polygon.
• Path (the most versatile shape). It implements the full SVG path language.
• Image.
• Text.
• TextPath (highly experimental at the moment).

Shapes support following set of properties:

• Geometric properties:
• Shape description (shape-specific).
• Linear transformation specified by 3 x 3 2D matrix.
• Font (only for text shapes).
• Visual properties (not supported by the image shape):
  • Stroke (outline of a shape).
  • Fill (interior of a shape).

Shapes are stacked from bottom to top in an order of their definition. This z-order can be changed dynamically.

There is a group, which is a pseudo-shape. It combines other shapes (and possibly groups), and can be used to apply transformation to a group. All group members share a single z-order, but can be re-arranged within a group.

In order to draw a picture a programmer constructs a pseudo-DOM from a surface object, shapes, and groups, sets appropriate attributes, and picture is drawn automatically by a browser. Modifications of shapes change picture automatically. It is possible to attach event handlers to shapes using dojo.event.connect(). Following conventions are used:

While a path is the most universal geometric shape, which can emulate almost all other shapes (exceptions: image, and text shapes), all frequently-used shapes are provided as a convenience: rectangle (with optionally rounded corners), circle, ellipse, line, polyline/polygon.

All shape description properties are defined using a duck-typing technique. Incomplete shape description definitions are supported. All missing members will be taken from corresponding default shape definitions listed in common.js or from the current shape description object. Example: rect.setShape({width: 200}) - all missing members will be taken from dojo.gfx.defaultRect object making it equivalent to rect.setShape({x: 0, y: 0, width: 200, height: 100, r: 0}).

All shape description objects and visual property objects have a member called "type", which uniquely identifies a property type. This is a provision for a possible serialization.

Certain shape properties can be defined using shortcuts:

• Path can be defined as a string of path commands (more on path later):
  • path.setShape("m 0,0 l 100, 100 e") is equivalent to path.setShape({path: "m 0,0 l 100, 100 e"}).
• Polylines/polygons can be defined as an array of points:
  • poly.setShape([{x: 0, y: 0}, {x: 100, y: 100}]) is equivalent to poly.setShape({points: [{x: 0, y: 0}, {x: 100, y: 100}]}).
• Stroke can be defined by specifying a color as a string:
  • shape.setStroke("black") is equivalent to shape.setStroke({color: "black"}).

All methods without an apparent return type return their object itself. It is used for chaining multiple operations:

• surface.createRect({x: 100, y: 50}).setFill("red").setStroke("blue");

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

Using Dojo Offline

Let's dive in and start using Dojo Offline.

Download Dojo Offline SDK

First download the Dojo SDK and unzip it.

SDK Layout

When you unzip the SDK, you will find the following directories:

• dojo - The core of Dojo
• dijit - The Dojo widget system, named Dijit
• dojox - Optional Dojo extensions

Dojo Offline is an optional Dojo extension, and is therefore located in the dojox directory.

If you are looking to track down Dojo Offline's source code, most of it is in dojox/off/. The Dojo SQL layer is in dojox/_sql/, while Dojo Storage is in dojox/storage/. An autogenerated, JavaDoc-like API is available. When looking at the API docs or source code, many advanced options are available to deeply customize Dojo Offline; you can almost always safely ignore these unless you are an advanced user, and they usually say "For advanced usage; most developers can ignore this" in their documentation.

Demos

Dojo Offline has three main demos, a Hello World example, a more complicated web-based editor named Moxie that includes an example server-side written in Java, and a demo of Dojo Offline's SQL cryptography. You can play with hosted versions of the Hello World example here; a hosted version of the Moxie editor here; and the SQL cryptography demo here. 

If you want to study the demo examples' source code, the Hello World example is located in dojox/off/demos/helloworld/, while the Moxie editor is located in dojox/off/demos/editor/. You can see the SQL cryptography demo source in dojox/_sql/demos/customers/customers.html.

The Hello World example has no server-side requirement; Moxie, however, includes a full Java server-side that you can use as a template and scaffolding. Running the server-side of Moxie is simple. Make sure you have Java 1.5+ installed, and then just type: java -jar editor.jar
while inside the directory dojox/off/demos/editor/server/, and the Moxie server-side will start running, with an embedded web-server (Jetty) and relational database (Derby) already set up for you.

In a web-browser, you can now go to the following URL:

http://localhost:8000/dojox/off/demos/editor/editor.html
to run Moxie against the local server you just started.

For more details on the server-side portion of Moxie and how to build see the README file at dojox/off/demos/editor/server/README.

Creating an Offline Application

Now that you have awareness of the SDK, it's file layout, and the provided demos, let's get down to illustrating what you need to do to create an offline-aware application using Dojo Offline.

Bring in Dojo and Dojo Offline

For our example source code we will pretend that you are creating your application with the Dojo Offline SDK in a subdirectory named offline-sdk.

First, bring in Dojo and Dojo Offline: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}

isDebug is a useful flag that when set to true will print out debug messages, and when set to false will hide them. In your own code you can add console.debug("some message"); to have these printed out to help with debugging. If you are using Firefox in conjunction with Firebug then these messages will print out to the Firebug console; otherwise they will print on to the web page itself, such as in Internet Explorer.

Notice that we do not bring in Dijit; Dojo Offline has no dependencies on Dijit, the Dojo Widget system, helping to keep your code size smaller. We only include it in the SDK because Moxie, the example editor, uses the Dijit rich text editor.

Next, bring in Dojo and Dojo Offline's style sheets:
/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}

Dojo Offline Widget

Dojo Offline includes a default offline widget that does much of the hard work of providing a good offline UI to your end-users. It updates the user with online and offline feedback; provides sync messages; and delivers help and instructions on using your application offline. If Dojo Offline did not provide these you would have to roll them yourself, so providing a default UI makes developing offline applications easier.

Getting this widget is as easy as adding a bit of HTML to your page, with a special, predefined ID:
/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}

When the page loads, Dojo Offline will automatically find an element with the ID dot-widget and automagically embed the offline widget.

The offline widget is a small, self-contained unit that provides feedback to the user, giving you a bunch of great functionality for free.

Here is a screenshot of Moxie, with the offline widget circled:

For more screenshots of the offline widget and a full description of what it gives you for free, see here. It is recommended that you use the offline widget in your own offline applications unless you are an advanced developer; information on customizing its look and feel, including dropping it, can be found here.

JavaScript

Let's take a look at our JavaScript now. All you have to do is set your application name:
/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

The Offline Widget will use your application name to customize it's user-interface; that is how the offline widget, for example, can insert "Learn How to Use Hello World Offline" into its instructions without you having to manually edit the offline widget's HTML.

Slurp! Bringing Your Application's Files Offline

For your application to be able to work offline, you must make sure that all of your JavaScript, HTML, CSS, etc. are available even when away from the network. While the browser may have these in its cache, you can't depend on this. The underlying Google Gears plugin that Dojo Offline uses makes it possible to specify what files you want to have available when offline, such as your JavaScript.

It can be tedious, however, to build up a full list of all your files, especially if you have many images and supporting libraries and are doing rapid development. Dojo Offline provides a single method, named slurp(), that will slurp the page and automatically figure out all of the resources you need to have available offline:
/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;} The slurp() method is awesome; it will automatically scan your page and quickly figure out all your JavaScript and CSS files; grab any IMG tags in your source; and even grab any background URLs you might have in your attached CSS. The only thing it doesn't do is look at inline styles or scan your JavaScript for dynamic additions.

You can also manually add files if you want or need to; more information here.

slurp() has a nice debug method if you want to see all the files that have been slurped; make sure that Dojo's isDebug is true, and call dojox.off.files.printURLs() after the page and Dojo Offline are finished loading (more details on how to know when Dojo Offline is done loading in the next section).

During development, as you hit your offline application, it will always be pulled from the Google Gears file cache first, even if you are online. This can sometimes make development tricky and tedious. If you just made a change locally, hitting your web application, even if you are offline, will cause the older version to be pulled in first.

To make this process easier, I have created a bookmarklet that you can drag to your links toolbar in your browser. View this page to get the bookmarklets for Firefox and Internet Explorer.

These bookmarklets clear the Google Gears cache, removing all of the files that slurp() added offline. Press it during development when you have made a new change that you want to show up; you must press it when you are at your web application (i.e. it won't work if you just press it when you are at a different or blank page). Then, refresh the page to see your change.

Knowing When Dojo Offline Can Be Used

Dojo Offline can't be used until the page is finished loading and Dojo Offline itself is finished initializing (such as the offline widget finishing being placed into the page). You should wait until the page and Dojo Offline are finished loading, and then your application can start doing its own custom thing:

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

myApp is some object that will hold all of the methods for our application; myApp.initialize() is the method in particular that would initialize our application on page and Dojo Offline load in some way. We use dojo.connect to connect to the dojox.off.ui.onLoad event; when this fires, myApp.initialize() is called. At this point we could begin to manipulate the DOM on the page, since it is loaded, or do further actions specific to your application; in this case we just print an alert message.

The final call to dojox.off.initialize() is there to tell Dojo Offline that we are done configuring it, and that it can now initialize itself; we don't want Dojo Offline to initialize itself before we have set our appName and called slurp(), for example, so this final call tells Dojo Offline that we are finished doing configuration.

Let's look at all of our code so far in this tutorial:

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}

Important: I've noticed over and over in the frameworks I have created, such as Dojo Storage and the Really Simple History library, that developers get confused about an important point. Notice that configuring Dojo Offline must be done before the page loads:

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}