ImageHighlighter v1.01

ImageHighlighter is an updated version of my original imgHighLighter plugin with lot of improvements! Most are under the hood so you probably won't see too much of a difference on the surface.

This plugin allows you to highlight a portion of an image when you hover over a link. In the image below, the mouse is hovering over the different links and you can see the corresponding portion of the image becomes highlighted (there is an animate gif below, but just click on the image to go to the demo page).
I set up an demo page here.

Download: Uncompressed | Minified | Zipped Demo | Github

I have tested this plugin in IE8, Firefox and Chrome. Please leave me feedback if you any problems with how it works or if it doesn't work in other browsers.

7/6/2010: Updated this post to describe v1.01 where the editor portion of the script was moved into a plugin extension. And support for jCrop was added to allow selecting the entire box instead of just getting the mouse coordinates. Check out the updated demo page!

Setup

• This plugin requires jQuery.
• HoverIntent is an optional plugin, this plugin will use it's functionality if it is included.
• Follow this basic template with a quick summary for each image you want to apply imageHighlighter functionality. For more details, go to the specific section.
  
  HTML
  

  <div>
  <ul class="imgHL">
  <li>
  <a href="#" rel="sx1,sy1,ex2,ey2">Item #1</a>
  <p>Description for item #1</p>
  </li>
  <li>
  <a href="#" rel="sx1,sy1,ex2,ey2">Item #2</a>
  <p>Description for item #2</p>
  </li>
  <li>
  <a href="#" rel="sx1,sy1,ex2,ey2">Item #3</a>
  <p>Description for item #3</p>
  </li>
  </ul>
  <br>
  <img id="imgHL" src="myimage.jpg" alt="" />
  <div class="description"></div>
  </div>

  • In the HTML above, the highlight links are all wrapped in a div with a class name "imgHL" to make them easier to target.
    
  • The highlight links (<a>) must contain a rel attribute with the highlight box coordinates (see the Highlights section below for more detail).
    
  • Each link/description pair is wrapped together (inside an <li> in this case). See the Descriptions section below for more details.
    
  • The image is the central element. Once the script is initialized, the image will contain all of the plugin information. It is also the target of both the imageHighlighter and imageHighlighterEditor scripts.
  • The highlight description will be placed into the div with class "description". You can target a different class/Id when you modify the script options.
    
    
  CSS (basic example)
  

  /* List link: currently hovered/selected */
  a.current { color: #fff; }
  
  /* Hide & Position Descriptions */
  .imgHL p { display: none; }
  .description { margin: 1em auto; clear: both; width: 450px; height: 2.4em; }
  
  /* General imageHighlighter (overlay and highlight) */
  .imageHighlighter, .imgHLDark, .imgHLLight, .imgHLOverlay { padding: 0; margin: 0; } /* overlay and highlight divs */
  .imgHLOverlay { background: #000; opacity: .5; filter: alpha(opacity=50); } /* overlay color & opacity *

  • When a link is hovered and the image reveals the highlight box, the class "current" is applied to the link. You can use this to style the link and make it stand out.
  • The css definition ".imgHL p" hides the descriptions that appear under the image (in this example). The description is moved into the ".description" element when the highlight link is hovered.
  • The description class can be placed anywhere on the page; but because of this, the class name ".description" must be unique for each imageHighlighter instance on the page. You can easily modify this class name using the plugin options.
  • The general imageHighlighter definitions apply to the div wrapping the image (.imageHighlighter), the overlay (.imgHLOverlay & .imgHLDark) and the highlighted box (.imgHLLight). As you can see, the overlay has a background color and 50% opacity to darken the image behind the highlight. This can be set to transparent here in the CSS or disabled using the script.
    
    
  Javascript
  

  /* window load ensures all images are loaded */
  $(window).load(function(){
  $('#imgHL').imageHighlighter({
  list : '.imgHL a'
  });
  })

  • This script uses "window.load" instead of "document.ready" to ensure that all images have been loaded. This is necessary as the script needs the image dimensions in order to initialize properly.
  • In this basic example, the highlight links are targeted using the ".imgHL" div that wraps the entire list. The default list setting is "a" which is much too general to use, but the script will ignore any link that doesn't contain a rel tag.
  • There are more options that can be set. For a full list and detailed descriptions, look under the customizing/options section!
    
    
• Highlights: The highlight link's "rel" attribute contains all the information needed for the highlights.
  

  rel="sx1,sy1,ex2,ey2"
  sx1	Starting X position of the highlight box	} top left corner
  sy1	Starting Y position of the highlight box
  ex2	Ending X position of the highlight box	} bottom right corner
  ey2	Ending Y position of the highlight box

  You can change the highlight properties of each image using: borderColor, borderSize & borderType described in the Customizing/Options section below.
  
  
• Image: The image must be targeted when initializing the script. You could target the class ('.imgHL') in the example above and the script will initialize once it has found the image from that group of selections. The image contains all of the data associated with this plugin, from using the built in methods to targeting custom events.
  

  $("#imgHL").imageHighlighter();

• Descriptions: Each link/description pair should be wrapped together. In the demo where the links are in a paragraph, the link/description pairs are wrapped in a span:
  

  <span><a rel="sx1,sy1,ex2,ey2">Item #1</a><span class="desc">Description for Item #1</span></span>

  In the other example, the pair are wrapped inside of a list (<li>). Make sure that the descriptions are hidden and targeted by the "descrip" plugin option. The script will look inside the link highlight wrapper, so you don't necessarily have to have a specific class assigned to it as long as the element is unique (e.g. don't have two <p>'s inside with the highlight link otherwise the contents of both will be displayed in the description.
  
  The second part of the description is set using the "descripClass". The descriptions for the highlight will appear inside an element with this class, when hovering over a link. It can be located anywhere on the page, but the class/id needs to be set in the plugin options and unique for each instance of the plugin.
  
  
• Overlay: The overlay covers the image (darkens the background) to make the highlighted portion stand out more. You can adjust the opacity of this overlay in the CSS and you can turn off the overlay functi0nality by setting the overlay option to false.
  

Customizing / Options
This plugin has the following default options, so you will only need to include the line below if you want to change the default:

$("#imgHL").imageHighlighter({
borderColor : "#fff",         // highlight border color
borderSize  : 4,              // highlight border thickness
borderType  : "solid",        // highlight border type
list        : "a",            // links that contain the highlight coordinates (e.g. "li.imgHL a")
descrip     : "p",            // HTML tag sibling of the link, that contains the description text (hidden) (e.g. "p.desc")
descripClass: ".description", // HTML tag where description text is shown (placeholder)
overlay     : true,           // display an overlay to make the highlight stand out
current     : "current",      // class applied to link currently used to highlight the image
hoverTimeout: 100,            // hoverIntent timeout (only applied if hoverIntent plugin is loaded)
zindex      : 10              // z-index of highlight box, overlay is automatically made 1 less than this number
})

Methods
You can use the following methods to get and set the highlighted content. Note that these methods must target the image.

• Get: In the following example, the variable current will contain the current link object that has been highlighted. If nothing is currently highlighted, the script will return null.
  

  var $current = $('#imgHL').data('imageHighlighter').highlight();

• Set/Get:

Use a number (indexed from one: first, second, etc) - if the nth link doesn't exist, it will return null.


var $current = $('#imgHL').data('imageHighlighter').highlight(1); // select the first link

Search for the case-sensitive text within the link (uses the jQuery ":contains()" selector) - if the text is not found, the script will return null.


var $current = $('#imgHL').data('imageHighlighter').highlight("frames");

Search for the link with a class or ID - if the selector is not found, the script will return null.


var $current = $('#imgHL').data('imageHighlighter').highlight(".box");

Edit Mode

• Updated in v1.01:
  
  • The edit mode script was moved into an extension for the plugin. This was done because the edit script is not required once the coordinates are obtained and the script is deployed on your site.
    
  • Additionally, the script was made to work with the Jcrop plugin (included with the demo file zip) allowing you to use a resizable selection box to more easily get the coordinates.
  • If you click on the coordinates, the coordinates (contained in an input tag) become selected, so you can more easily copy them.
    
    
• Edit mode for this plugin should make it easier to obtain the coordinates of the highlight box - the coordinates added to the highlight link rel attribute.
  
  
• As of v1.01, edit mode can be activated by:
  
  
  1. Including the imageHighlighterEditor script & the jCrop plugin script, if desired.
     
  2. Set up the editor by calling the script on the same image(s) as the imageHighlighter script. You can generalize the call by targeting the ".imageHighlighter" class (applied to a div that wraps the image after the imageHighlighter script is applied to it). There is only one options, seen below:
     

     // Enable the editor and use the Jcrop plugin, if it is available
     $('div.imageHighlighter img').imageHighlighterEditor();
     
     // Enable the editor, but don't use the Jcrop plugin (even if it has been loaded)
     $('div.imageHighlighter img').imageHighlighterEditor({ useJcrop: false });

  3. Now activate or deactivate edit mode by double clicking on the image. A green bar (styled in the CSS) will appear below the image which will show the mouse coordinates (default editor) or the box coordinates (Jcrop plugin added).
     
     
• With the editor active:
  
  
  • Default editor - move the cursor over the image to find the coordinates. Then clicking on the image will lock the coordinate display and make copying these numbers easier.

    Mouse x,y coordinates (click to lock/unlock) : x,y

  • Jcrop plugin installed - single click anywhere on the image to make the a corner of the box, then drag your mouse any direction to create a resizeable box. The coordinates of the upper left and bottom right corners of the box will display under the image:

    Current box coordinates : x1,y1,x2,y2

  • Click on the coordinates (they are inside an input tag). The contents will automatically be selected, but not copied.
    
  • When you hover over a highlight link, the highlight link name and coordinates from that link is displayed above the coordinate bar.
    

Bugs / Suggestions

• When the window is repositioned, the highlights may be off until it is refreshed again when you hover over a link (especially while in edit mode), and sometimes you'll need to reload the page.
• To make suggestions or report any bugs please email me at wowmotty at g mail dot com.