Icontem

JavaScript Hover Image Gallery: Switch images in a gallery when user hovers them

Recommend this page to a friend!
  Info   Screenshots Screenshots   View files View files (20)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2017-03-22 (16 hours ago) RSS 2.0 feedNot enough user ratingsTotal: 197 This week: 10All time: 231 This week: 3Up
Version License JavaScript version Categories
hover-gallery 1.0BSD License1.0HTML, Graphics
Description Author

This object can switch images in a gallery when user hovers them.

It can listen to mouse events on page elements with thumbnail images with a given class attributes.

When the user hovers a thumbnail image this object shows the full size image in a popup element and switches to another image when the user hovers a different thumbnail image.

Currently it supports 3 different popup positioning methods: in the center of the screen, next to the hovered thumb, and in a statically positioned element. Custom positioning methods may also be implemented.

The gallery images are cached to switch faster to the current image.

Innovation Award
JavaScript Programming Innovation award nominee
February 2014
Number 3


Prize: One year Codenvy Developer hosted cloud IDE premium plan
Usually image galleries require that the users point the images they want to see or click on buttons to move to the next image.

This object presents a more user friendly solution for image slideshows. It allows the users to just hover image thumbnails to switch to a different image. This way the users do not have to click in the images they want to see.

Manuel Lemos
  Performance   Level  
Name: Michael Milev <contact>
Classes: 1 package by
Country: Bulgaria Bulgaria
Innovation award
Innovation award
Nominee: 1x

Details
# JavaScript hover gallery

### Short description

This class creates a "hover" gallery from a set of HTML elements (thumbs). When 
the user hovers one of those elements a corresponding image is loaded in a popup. 
This way the user can view the whole gallery with no mouse clicks at all.

The class currently supports 3 different popup positioning methods - in the center 
of the screen, next to the hovered thumb and in a statically positioned element. 
Custom positioning methods can be easily created and applied.

An image caching mechanism is implemented for faster image loading.

The class is fully covered with Jasmine specs.

### Award winner

This project was nominated in the JS Classes Innovation Award in February 2014 and
won the 3rd prize. You can find more details [here](https://www.jsclasses.org/package/322-JavaScript-Switch-images-in-a-gallery-when-user-hovers-them.html).

### Dependencies

The class is using basic jQuery functionality like selectors. It has been tested 
with jQuery 1.10.2. 

### Browsers

I've tried running the Jasmine tests on Firefox, IE (7 and above), Chrome, Opera 
and Safari and got only greens.

### Example

To apply the hover gallery you need an HTML and a JavaScript part. In the HTML 
part you must provide a list of elements (thumbs). Each of those elements should 
contain an anchor tag with a href pointing to the image you want to load in the 
popup on hover. This is the default behaviour of the class but it's easily 
changeable - just override the getImageFromThumb(thumb) method and you're good 
to go with your custom HTML structure. Here is a short example HTML code:

```php
<ul>
    <li class="hover-thumb">
        <a href="images/barbarian.jpg">
            <img src="images/thumbs/barbarian.jpg" width="80" height="60" alt="barbarian" />
        </a>
    </li>
    <li class="hover-thumb">
        <a href="images/last-battle.jpg">
            <img src="images/thumbs/last-battle.jpg" width="80" height="60" alt="last-battle" />
        </a>
    </li>
    <li class="hover-thumb">
        <a href="images/map.jpg">
            <img src="images/thumbs/map.jpg" width="80" height="60" alt="map" />
        </a>
    </li>
</ul>
```

And... That's all with the HTML. Now the JavaScript - you just have to create an 
instance of the gallery class. You can configure the gallery by passing an 
options JSON when creating it or by directly changing it's properties afterwards 
(look below for a list of the supported class variables and methods). Here is a 
short example JavaScript code:

```javascript
new moHoverGallery({
    thumbs: $('.hover-thumb')
});
```

### How it works

Basically it's really simple. When a hover gallery object is created it does a 
couple of things - creates the popup, loads the image cache and binds a mouse 
move event to the document. When the user moves the mouse the class checks if it 
is over one of the thumbs or not. If so an open popup sequence starts - popup
content is loaded, the popup is positioned and made visible. When the mouse 
leaves the thumb - the popup is closed. This is the default behaviour which can 
be tweaked in many ways either by the out of the box options or by replacing 
some class methods.

### Class variables

| Variable        | Description 
| --------------- | -----------
| thumbs          | A list of the elements that open the popup when hovered.
| current         | Contains the currently opened thumb.
| popupClass      | Class of the popup container (default: null).
| popupId         | Id of the popup container (must be unique for each gallery, default: mo-hover-gallery-popup).
| imageWildcard   | It is used for creating the HTML content of the popup container while opening.
| popupTemplate   | A template that replaces the HTML of the popup container each time it is opened, here the image wildcard is replaced with a path to the opened image.
| positionPopup   | The name of the positioning function that will be used before each popup opening (default: positionPopupInScreenCenter).
| imageCache      | Container for the cached images.
| startIndex      | The index of the thumb that should be opened when the gallery is created.
| skipCreatePopup | Forces the gallery NOT to create it's own popup (default: false).
| skipClosePopup  | Forces the gallery NOT to close the popup when the mouse leaves a thumb (default: false).

### Class methods

| Method                                  | Description 
| --------------------------------------- | -----------
| createPopup()                           | Creates a new div element appended to the body if it's missing. Can be skipped by the skipCreatePopup flag.
| openPopup(thumb)                        | Loads the popup content and makes it visible only if an image can be extracted from the thumb parameter. 
| closePopup()                            | Hides the popup. Can be skipped by the skipClosePopup flag.
| positionPopupInScreenCenter()           | Puts the popup in the center of the screen.
| positionPopupRelativeToThumb()          | Puts the popup relative to the hovered thumb starting from it's center.
| positionPopupStatically()               | Leaves the popup where it is.
|                                         | You can define all kinds of other position methods and set the positionPopup variable of the class to use them.
| selectPopup()                           | Tries to select the popup of the current gallery.
| getElementCoords(element)               | Returns the coordinates of a DOM element as JSON - top, bottom, left, right.
| isPositionInElement(left, top, element) | Checks whether a certain position is within a certain DOM element.
| getThumbByCoords(left, top)             | Extracts a thumb out of the gallery thumbs collection if the passed coordinates are within it.
| getImageFromThumb(thumb)                | Extracts an image out of a thumb. Override this method if you want to make custom image path extractions.
| isOverThumb(event)                      | Can provide extra rules when checking whether the mouse is over a thumb or not. This is useful if you want a scrolling gallery for example.
| onMouseMove(event)                      | Handles mouse move events.
| loadImageCache()                        | Caches the images that are going to be loaded so things are done faster.
| destroy()                               | Removes all external relations of the gallery instance (as we know there is no easy object deletion in JavaScript). 

### How to run the tests

It can't be simpler - just open the provided tests/SpecRunner.html in your browser.

### Something has to be fixed?

This is v1.0 of the class so I'm open for all kinds of feedback - comments, 
constructive criticism, bug reports etc. I'm looking forward for improving the 
features and adding new ones when needed.
Screenshots  
  • 03-position-statically.jpg
  • 02-position-relative-to-thumb.jpg
  • 01-position-in-screen-center.jpg
  Files folder image Files  
File Role Description
Files folder imagetests (1 file, 5 directories)
Plain text file moHoverGallery.js Class The hover gallery
Accessible without login Plain text file README.md Doc. Github description

  Files folder image Files  /  tests  
File Role Description
Files folder imagecss (1 file)
Files folder imagefixtures (2 directories)
Files folder imageimages (3 files, 1 directory)
Files folder imagelib (1 file, 1 directory)
Files folder imagespec (1 file)
  Accessible without login HTML file SpecRunner.html Output Jasmine tests runner

  Files folder image Files  /  tests  /  css  
File Role Description
  Accessible without login Plain text file normalize.css Data Test styles

  Files folder image Files  /  tests  /  fixtures  
File Role Description
Files folder imagecss (1 file)
Files folder imagehtml (1 file)

  Files folder image Files  /  tests  /  fixtures  /  css  
File Role Description
  Accessible without login Plain text file moHoverGallery.css Data Test fixture

  Files folder image Files  /  tests  /  fixtures  /  html  
File Role Description
  Accessible without login Plain text file moHoverGallery.html Data Test fixture

  Files folder image Files  /  tests  /  images  
File Role Description
Files folder imagethumbs (3 files)
  Accessible without login Image file barbarian.jpg Photo Test image
  Accessible without login Image file last-battle.jpg Photo Test image
  Accessible without login Image file map.jpg Photo Test image

  Files folder image Files  /  tests  /  images  /  thumbs  
File Role Description
  Accessible without login Image file barbarian.jpg Photo Test image
  Accessible without login Image file last-battle.jpg Photo Test image
  Accessible without login Image file map.jpg Photo Test image

  Files folder image Files  /  tests  /  lib  
File Role Description
Files folder imagejasmine-2.0.0 (6 files)
  Plain text file jquery-1.10.2.min.js Class Required library

  Files folder image Files  /  tests  /  lib  /  jasmine-2.0.0  
File Role Description
  Plain text file boot.js Class Test framework
  Plain text file console.js Class Test framework
  Accessible without login Image file jasmine-favicon.png Icon Test framework
  Plain text file jasmine-html.js Class Test framework
  Accessible without login Plain text file jasmine.css Data Test framework
  Plain text file jasmine.js Class Test framework

  Files folder image Files  /  tests  /  spec  
File Role Description
  Accessible without login Plain text file moHoverGallerySpec.js Test Jasmine tests specification

 Version Control Unique User Downloads Download Rankings  
 86%
Total:197
This week:10
All time:231
This week:3Up