type: widget

release: 0.0

status: in planning

documentation: N/A

demo: http://jquery-ui.googlecode.com/svn/branches/labs/photoviewer/demos/index.html#photoviewer|default

1 - Description:

An alternative to Lightbox and its various clones, with the sole purpose of displaying images: One or more thumbnails point at the full resolution image, and instead of displaying that image on a new page, its displayed, above an overlay, on the current page.

When a group of anchors with thumbnails is selected, the user can navigate with mouse and keyboard to rotate through the images. 

2 - Visual Design:

(Initial wireframe mockup, followed by more detailed designs of the various configurations, options and states.)

3 - Functional Specifications/Requirements:

Options/Methods/Callbacks

• options:
• loop (boolean, default: true)
• when enabled, advancing the last item in a gallery displays the first, and the other way round
• when disabling, nothing happens
• has no effect when the gallery contains a single image
• overlay (boolean, default: true)
• displays an element above the page, below the image, to give more focus to the image and prevent interaction with the page
• when disabled, the overlay isn't displayed at all
• related options are showOverlay and hideOverlay
• selector (string, default "a[href]:has(img[src])")
• used in the context of the widget elements to find anchors that trigger the photoviewer
• default assumes anchors with a href-attribute, containing an image element with src-attribute, a thumbnail of the image to show
• can be customized to use links without thumbnails
• titleSuffix (string, default: " - Click anywhere to close (or press Escape), use keyboard arrows or mousewheel to rotate images")
• english text indicating usage of the interface, click to close, cursor keys and mousewheel to rotate through images
• rotateIn (function, default: directional drop effect)
• called to show the next image in a gallery
• thisObject (DOMElement) has to be shown (via show(), fadeIn() or others)
• only argument direction indicates the direction: "down" when the next image is displayed, "up" when the previous image is displayed, useful to pass through to jQuery UI effects
• rotateOut (function, directional drop effect)
• called to hide the next image in a gallery
• thisObject (DOMElement) has to be hidden (via hide(), fadeOut() or others)
• first argument direction indicates the direction: "up" when the next image is displayed, "down" when the previous image is displayed, useful to pass through to jQuery UI effects
• second argument is a function that must be called for cleanup, it removes the DOM element
• for a cross-fade, use rotateIn with fadeIn(), and trigger the rotateOut callback when the fade is complete, works best when all images have the same size
• show (function, default: fade in)
• called to open the photoviewer
• thisObject (DOMElement) has to be shown (via show(), fadeIn() or others)
• hide (function, default: fade out)
• called to hide the photoviewer
• thisObject (DOMElement) has to be hidden (via show(), fadeIn() or others)
• only argument is a function that must be called for cleanup, it removes the DOM element
• showOverlay (function, default: fade in)
• called to show the overlay
• thisObject (DOMElement) has to be shown (via show(), fadeIn() or others)
• hideOverlay (function, default: fade out)
• called to hide the overlay
• thisObject (DOMElement) has to be hidden (via show(), fadeIn() or others)
• only argument is a function that must be called for cleanup, it removes the DOM element
• methods:
• next
• shows the next image in a gallery
• nothing happens when there is only a single image, or the last image is already displayed and loop is false
• prev
• shows the previous image in a gallery
• nothing happens when there is only a single image, or the first image is already displayed and loop is false
• close 
• hides the photoviewer and the overlay
• callbacks: n/a

Specifications

• requires anchor with an href attribute (selected via options.selector), assumes that href to point at an image to display
• all anchors within a photoviewer widget are considered to form a gallery
• images within a gallery can be rotated through using the cursor keys (left/up for previous image, down/right for next image) or the mousewheel (up for previous image, down for next image)
• if the anchor has a title, its also added to the photoviewer, along with options.titlePrefix
• the Escape key or a click anywhere will close the photoviewer
• when an image takes longer then 250ms to load, a loading indicator is displayed

4 - Markup & Style:

     4.1 Initial markup examples

     <div id="photoviewer">

          <a href="/photo1.jpg"><img src="photo1-thumb.jpg" /></a>

          <a href="/photo2.jpg"><img src="photo2-thumb.jpg" /></a>

     </div>

     4.2 Recommended transformed HTML markup

     no transformations are performed, just new elements created and appended to the document body:

    <div class="ui-widget-overlay"/>

    <img class="ui-photoviewer src="photo1.jpg" />

     4.3 Accessibility recommendation

    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

     4.4 CSS & Theme

    (Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 

5 - Latest version of plugin:

http://jquery-ui.googlecode.com/svn/branches/labs/photoviewer/demos/index.html#photoviewer|default

6 - Open issues being discussed

Spacebar causes the page to scroll; either just prevent that, or use for next-image.

Currently the zoom in ends with the shadow canvas popping into view. Seems like the animated width/height causes the canvas to disappear, probably related to overflow-x/y:hidden set during the animation. Fading the shadow in after the animation would work, but is unnecessary for the rotation animation, where the shadow is nicely animated. Using a fade in that case ruins the effect.

Currently the plugin doesn't provide visual affordances for navigating or closing the overlay, apart from a tooltip indicating the available actions (cursor keys, mousewheel, click or esc to close).

• One option may be to display the next image at the bottom/right, with just ~5% of the image being visible (it could move up a bit on hover, to provide a bigger hitarea). When clicked, it slides into view, while the current image drops out to the top/left. Same of the other way round.
• Another alternative would be an iPhone like drag: Drag the current image to the top/left, and once dragged more then 50%, it drops out and the next image drops in. Makes sense in combination with the above, and without that, too.
• In both cases the drop could be replaced with a full move-out-of-view animation ("drop" effect also fades; could perform better without the fade).

The current markup approach does progressive enhancement only when the links point at the plain image, which usually isn't the case on sites with non JS image galleries. See this golem.de image gallery, where each thumb leads to its own html page with the full image.

The centered loading indicator doesn't work well for the initial load. An indicator displayed on top of the thumbnail works better.