UvumiTools Gallery Plugin

The UvumiTools Gallery allows you to display fancy photo galleries on your web site without requiring you to be a master programmer. All you need to do is include a couple JavaScript and CSS files. This is made possible thanks to the powerful Mootools Javascript Framework.

Here's how it works: First, the thumbnails are loaded. When they are ready, users can click a thumbnail and watch the gallery transform into a slideshow, which is then navigated by clicking the left column or by scrolling with the mouse wheel. A click on the photo being displayed brings the user back to the contact sheet view.

• Requires no Javascript knowledge: All it needs is some basic HTML to define the images, and one line of code to initialize the gallery, in which you can eventually set some options. Even your mom could do it.
• Non-obtrusive: The UvumiTools Gallery uses an existing valid HTML document as its source, so it isn't 100% JavaScript generated. This means if a user disables JavaScript or for some reason the script doesn't load or execute correctly, the pictures will still be visible as they are formatted in the basic HTML. This may require a little more work from you at first, but it really pays off in the end (see next bullet point).
• Search Engine Optimized: Non-obtrusive and degradable also means that search engines will be able to see and index your pictures. Because search engine robots don't execute JavaScript, any content generated after script execution will not be indexed. In our case this doesn't matter because search engines will see the source HTML, containing the thumbnails and links to the full-size pictures. As a result, your gallery photos will be visible to Google, Yahoo, and all other image serach engines. Also, the caption for each picture is stored in the 'ALT' attribute, giving search engines the opportunity to associate your keywords in the caption with their corresponding images.
• Cross-Browser Compatability: We tested UvumiTools Gallery in all the major browsers: Firefox 2 & 3, Internet Explorer 6 & 7, Opera 9, Safari 3, all on Windows systems. We didn't get a chance to test on Mac or Linux, so if you encounter any problems in other browser/operating system combinations, please let us know in the forum. We only support real browsers -- No need to email us with IE4 or AOL issues. We know about that, and frankly we just don't care.
• Options: We wanted to keep UvumiTools Gallery as simple as possible but also wanted to allow you to personalize it a bit. The default thumbnail size is 120px and the default spacing between them is 40px, but it is easy to change those values. Look at the example below for hints on how to change those settings.
• Progress Indicator: A progress bar shows how many thumbnails are loaded, so your impatient viewers will have some idea of how long the gallery will take to load if they are on, say, a 56K modem.
• Handles Missing Images: In case of broken links, the gallery doesn't freeze or crash. It just replaces the missing thumbnails with dummies. The thumbnail may be missing, but the full-size picture still might be there, and we need a way to view them. That's what those dummy placeholders are for. If the full-size picture can't be found, it will just let you know with a simple error message where the photo would be displayed.
• Optimized Resizing: Oversized images are resized so they always fit their container. No need to scroll around in order to see a high-res photo. However, you can still view them in their real size by clicking the direct link provided in the mouseover caption.
• Mouse Wheel Scrolling: When in slideshow mode, if you use your mouse wheel over the left column, the pictures will scroll.
• Fancy Captions: If your thumbnails contain 'ALT' attributes in the source HTML (recommended), then the script will generate captions that will be displayed when you hover the full-sized image. Those caption areas also contain direct links to the pictures, which will allow your users to click through and view high resolution images directly if they want.
• Fluidity: If you resize your window and your container has percentage or auto dimensions, the gallery will auto-adjust. You'll see the pictures moving around and repositioning themselves to make good use of available space on the page.
• Looks Awesome and Unique: Come on, you know it's rad. If you're sick of the overused Lightbox image viewer, bring something fresh and new to your web site with the UvumiTools Gallery. People will think you're cool (no guarantees).

What you'll need :

• A website where you can include javascripts: Sounds obvious, but if you are a Myspace or Facebook user, you can forget this gallery. Then if you are a blogger, it will depend of how much freedom you get on your platform. Joomla actually offers Mootools support. If you are your own webmaster, well, you'll be stoked at how easy this gallery is to include on your site.
• A thumbnail for each picture: Sorry, we are not going to make those for you. You'll have to use you favorite image editing program to make smaller copies of your pictures. Some programs like Photoshop offer great batching tools, but we don't really have the time or inclination to explain how to do that here.
• Mootools 1.2 only: If you want to use this gallery, you'll need Mootools 1.2, but if you are already using another javascript frameworks like Prototype or JQuery, you may have to decide which one you want to keep because those frameworks were not designed to work together, and they ofen conflict with each other.
  
  And yes, you actually do need version 1.2 of Mootools. If you are already using a previous version of Mootools then the gallery will not work unless you upgrade. Sure, upgrading is a hassle, but trust us, it's worth it in the long run.

• Mootools Dependencies: If your website already contains some Mootools 1.2 stuff (from this wesite or elsewhere), that's even better because you can use a single Mootools library for everything. All you'll need is the gallery script, and to make sure your library contains the following classes:

  • Core
    • Core
    • Browser
  • Native
    • Array
    • Function
    • Number
    • String
    • Hash
    • Event
  • Class
    • Class
    • Class.Extra
  • Element
    • Element
    • Element.Event
    • Element.Style
    • Element.Dimensions
  • Utilities
    • DomReady
  • Fx
    • Fx
    • Fx.CSS
    • Fx.Tween
    • Fx.Morph
  • Plugins
    • Fx.Scroll
    • Fx.Elements
    • Assets

Initialization

Arguments

• Options: An object that will allow you to modify some of the default properties of the gallery. All options are, well, optional, but use of the 'container' option is highly recommended.

Options

• container: The ID, as a string, of the element that contains all the <A> and <IMG> tags. If this option is ignored, the script will use the document body as a container (fine if your document contains nothing other than the gallery).
• caption: A boolean value that defines if a caption should be displayed when a full-size picture is moused-over. Default is TRUE.
• thumbSize: A number defining the maximum width or height, in pixels, that each thumbnail should have, regardless of the image size. The default is 120 pixels. (Hint: Make your thumbnails slightly larger, like 160px, and UvumiTools Gallery will grow them when a user hovers the thumbnail in the gallery)
• spacing: A number defining the minimum space between two thumbnails, assuming they both have the maximum allowed size. This value is also used to set the distance of the thumbnails from the borders of the container. The default is 40 pixels.
• loadingImg: URL of the loading indicator image. The URL should be absolute, or relative to the document. The default is css/ajax-loader.gif
• missingThumbClass: CSS class assigned to the missing thumbnails. Style can then be modified in your site's stylesheet by defining this class. Default is missing-thumbnail, which is the value used in the provided CSS file.
• progressClass: CSS class assigned to the progress bar. Style can then be modified in your site's stylesheet by defining this class. Default is progress-bar, which is the value used in the provided CSS file.
• errorMessageClass: CSS class assigned to the error message displayed when a picture can't be found. Style can then be modified in your site's stylesheet by defining this class. Default is error-message, which is the value used in the provided CSS file.
• legendClass: CSS class assigned to the legend displayed over the pictured when hovered. Style can then be modified in your site's stylesheet by defining this class. Default is caption, which is the value used in the provided CSS file.

Implementation

First, import the files provided in the zip archive into your document. While you can insert <script> tags anywhere, we recommend you put them inside the <head> tag for standards compliance:

Then you must prepare the HTML code for your gallery. Each image should be coded as the thumbnail, inside an anchor referencing the full-size image:

This means for each image you also need a thumbnail version. If you don't want to create thumbnails for your pictures, you can use the same image for thumbnail and fullsize, but that sort of defeats the purpose because the reason for previewing a gallery's thumbnails is to avoid loading each full sized photo up front. You can also include a caption in the alt property of the thumbnail. It's optional but recommanded for both search engine optimization and user friendliness.

Use your favorite server script or text editor to prepare a full gallery this way, then put all those images in a container, preferably a <div>, but any block element will work. Give an id to this container (this is very important):

Now you are ready to execute the script. Add the following code to your HTML document (The value for container must be the same as the gallery's id):

Mootools requires a strict Doctype to work properly. When everything is properly in place, you should have something like this:

Technically, that should work.

Finally, you can use optional parameters when you initialize the gallery:

Another example:

• Take it easy with the mouse wheel : It has been tested and debugged a lot, but there might still be some quirks especially when you go crazy on the scrolling column with the mouse wheel. We worked really hard to minimize those, but we cannot positively guarantee that it will never break. In the worst case, an image will not resize properly, no big deal. If you do find a specific bug that can be reproduced, please bring it to our attention in the forum and we'll do what we can to fix it.
• Animation heavy = slow: It may look cool, but web browsers and javascript were not designed to handle all those fancy animations. This isn't Flash programming! ;) It will run more or less smoothly depending on the visitor's machine, of course.
• Not for huge photo collections: UvumiTools Gallery doesn't support pagination yet, and all the thumbnails must load before you can start browsing. So it's fine if you have 5-40 pictures, but you might look for another alternative if you have hundreds of pics you want to show off on your web site.

• 20080722 - Version 1.0.2: Improvement: Mousewheel scroll event only captured when the mouse is hovering the left-hand column in the slideshow view. This is an improvement over the old method, which was to react to scrolling in the entire gallery area, which made it difficult to scroll the parent page.
• 20080720 - Version 1.0.1: Fixed a small bug that happens if the container's position is not set to relative or absolute prior ro initialization. Now the script sets the position to relative if none has been defined with CSS.
• 20080711 - Version 1.0.0: Initial release. Stable with Mootools 1.2