Skip to content

Latest commit

 

History

History
158 lines (141 loc) · 4.51 KB

README.md

File metadata and controls

158 lines (141 loc) · 4.51 KB
Raw

Perimeter.js

Creates an invisible perimeter around a target element and monitors mouse breaches.

More info, documentation and examples @ http://github.e-sites.nl/perimeter.js/

Use cases

  • Get the user's attention, in terms of showing some sort of tooltip / popover when hovering near a certain element, like a hint or a tip.
  • Lazy load a script when the perimeter of the target element is breached (AFAIK Google does this when a user moves it's mouse towards the red 'compose' button).
  • Fetch data via AJAX and do something with it when a users navigates towards a certain element.

Specs

  • Lightweight; (~0.6kb minified / gzipped)
  • No dependencies; just plug it in and you're good to go
  • Built-in debugger to actually see where the perimeter is located (boundary.js)
  • Fully documented
  • Unit-tests available

Getting started

First and foremost, download the script and include it as follows:

<script src="perimeter.min.js"></script>

Second, just call the Perimeter constructor function and pass the corresponding options.

new Perimeter({
    target: 'square',
    outline: 20,
    onBreach: function () {
        // Breach!
    }
});

UPDATE: as from 0.2.0 is also possible to pass DOM elements as target (instead of only a string). This way you can instantiate multiple Perimeters within a loop:

var items = document.querySelectorAll('.selector'),
    i = items.length;

while (i--) {
   Perimeter({
       target: items[i],
       outline: 100
   });
}

In case you're working with perimeter.debug.js you'll need to add a bit of CSS to actually see the boundary:

.boundary {
    position:absolute;
    border:1px dotted;
    background:#E4FECB;
    background:rgba(127,255,0,0.2);
    margin:0;
    padding:0;
    z-index:-1;
}

Options

Property Type Description
target {String|HTMLElement} Either a string with the ID of the target element or a DOM element. If the corresponding element is not present the script will fail silently.
monitor {HTMLElement} Element where the mousemove event will be bound to and therefore acts as monitor for breaches.
outline {Number|Array} Outline around the target element. This can either be an array with top/right/bottom/left dimensions or just one number which acts as shorthand for all directions.
debug {Boolean} When debugging in a local environment you can pass the debug option. This will create a division that will be positioned absolutely to the body and basically shows where the perimeter is located. By default, the debug functionality is excluded from perimeter.js. So, please make sure that you include perimeter.debug.js.
onBreach {Function} Callback function that will be invoked when the monitor detects a breach.
onLeave {Function} Callback function that will be invoked when the mouse cursor leaves the perimeter.

Browser support

Tested in the latest (stable) versions of Google Chrome, Mozilla Firefox, Opera and Safari. As for Internet Explorer; I have tested in IE8+ but it should work in IE7 as well (though, it might be quirky).

Note: needless to say, since Perimeter.js listens to the mousemove event to detect breaches it will not work on mobile devices.

Road map

When I have some spare time I will try to accomplish the following:

  • Performance measurements
  • More documentation / examples
  • Unit testing

License

Copyright (C) 2013 e-sites, http://e-sites.nl/ Licensed under the MIT license.