Saturday, September 26, 2009

imgHighLighter - jQuery Plugin


A newer version of this plugin is now available!

imgHighLighter is a jQuery plugin I wrote (my first!) that 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 "Toolbar" link and you can see the toolbar portion of the image is highlighted (click on the image to go to the demo page).
I set up an example page here.

This is still an early version of this plugin but I know it works with IE8, FF and Chrome. Please leave me feedback if you any problems with how it works.

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 for each image you want to apply imgHighLighter functionality.

    CSS
    /* Image & descriptions */
    div.imgHL { width: 500px; margin:0 auto; }
    div.imgHL ul { text-align: center; }
    div.imgHL ul li { margin: 0; padding: 5px; list-style-type: none; float: left; }
    div.imgHL .descriptions { margin-top: 1em; clear: both; width: 450px; height: 2em; }
    div.imgHL .descriptions p {display:none;}
    
    /* General imgHighLight (overlay and highlight) */
    .imgHLOverlay { background: #000; opacity: .6; filter: alpha(opacity=60); }
    .imgHLDark, .imgHLLight, .imgHLOverlay { padding: 0; margin: 0; }
    
    /* imgHighLight Edit Mode CSS */
    .imgHLInfo { margin: 5px auto; }
    .imgHLCoords { margin: 5px auto; }
    
    HTML
    <div class="imgHL">
    <ul>
    <li><a href="#" rel="desc1:sx1,sy1,ex2,ey2">Link 1</a></li>
    <li><a href="#" rel="desc2:sx1,sy1,ex2,ey2">Link 2</a></li>
    <li><a href="#" rel="desc3:sx1,sy1,ex2,ey2">Link 3</a></li>
    </ul>
    <img class="imgHLMain" src="whole.jpg" alt="" />
    <div class="descriptions">
    <p id="desc1">Description for item #1</p>
    <p id="desc2">Description for item #2</p>
    <p id="desc3">Description for item #3</p>
    </div>
    </div>
    
    Javascript
    /* window load ensures all images are loaded */
    $(window).load(function(){
    $(".imgHL").imgHighLight();
    })
    
  • Highlights: The link's "rel" attribute contains all the information needed for the highlights.
    rel="desc1:sx1,sy1,ex2,ey2"
    desc1 = ID of the description that is associated with the highlighted area (do not include the "#")
    sx1 = Starting X position of the highlight box
    sy1 = Starting Y position of the highlight box
    ex2 = Ending X position of the highlight box
    ey2 = Ending Y position of the highlight box
    You can change the highlight properties using: borderColor, borderSize & borderType described below

  • Image: The script is set by default to find any image inside the main wrapper (.imgHL) as set by the function call
    $(".imgHL").imgHighLight();
    You can specify the exact image to modify by adding the imageID option (described below)

  • Descriptions: The wrapper class that contains the image highlight descriptions is set to "descriptions" by default. You can change this default using the descriptionWrapper option (described below). Each description within the wrapper is contained in a paragraph tag with a specific ID that matches the desc1 ID in the rel attribute.

  • 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 (as it script does while in edit mode) by setting the overlay option.
Customizing / Options
This plugin has the following options:
$(".imgHL").imgHighLight({
borderColor: '#fff',                  // Color of the highlight border
borderSize: '2',                      // Thickness of highlight border
borderType: 'solid',                  // Type of highlight border
imageID: 'img',                       // Object or ID of the main image (e.g. #myimage or just img - if it's the only img inside the container)
descriptionWrapper: '.descriptions',  // Class wrapping all the descriptions
overlay: true,                        // Activate overlay (default = true)
editMode: false                       // Enable edit mode - on screen display of the image coords so you can get the info you need easier
})
Edit Mode
  • I've included an edit mode for this plugin which should make it easier for you to obtain and add the coordinates of the edges of the highlight box.

  • Edit mode can be activated in two ways:
    1. Using the editMode option when calling the plugin (described in the last section)
    2. Add a link along with the other highligh links. This method is the best as it allows you to activate and deactive edit mode.
      <li><a href="#" class="imgHLEdit">Edit Mode</a></li>
  • While in edit mode, additional information is added into the caption area... it displays the current cursor X and Y position.
    X = 0px, Y = 0px - Click to lock/unlock coordinates
  • If you click on the image while in edit mode, it locks the displayed coordinates so moving the mouse off the image won't change the display. Hopefully this will make it easier to edit your source document with the coordinates.

  • Additionally if you hover over a link, the highlight box will display (with overlay off) to allow better visualization of the highlight box.
Bugs / Suggestions
  • At this time, the options you chose will apply to all the imgHighlighter images on the page (to be fixed in future versions)
  • 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.
  • Future versions will allow you to highlight the image from links located anywhere on the page.
  • To make suggestions or report any bugs please email me at wowmotty at g mail dot com. Additonally, this is my first plugin, so if you can help me out with any suggestions or tips on how to improve the code I would greatly appreciate it :)