Perimeter.js

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

Fork me on GitHub

Use cases


Specs


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 it 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. When this property is left out the document will be used as monitor.
outline {Number|Array} The actual 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.

Examples

Example 1




Code example

new Perimeter({
    target: 'square',
    debug: true,
    outline: 50,
    onBreach: function () {
        this.target.innerHTML = 'breach!';
    },
    onLeave: function () {
        this.target.innerHTML = 'left perimeter';
    }
});

Example 2

Pass a custom element that needs monitoring, if you leave it out Perimeter will use the document as monitoring area.

Note: when using, for example, the parent element as monitoring area you will need to make sure it completely fits,
i.e. if the perimeter overlaps the monitoring element it will not trigger a breach properly.


Code example

Perimeter({
    target: 'target2',
    monitor: $('#example-2')[0],
    debug: true,
    outline: 20,
    onBreach: function () {
        this.target.innerHTML = 'breach!';
    },
    onLeave: function () {
        this.target.innerHTML = '';
    }
});

Example 3

Let's say you have a page with a fair amount of widgets, including one where users can upload files. Now, this widget will most likely not be used every time a user visits the page. This is where Perimeter.js comes in handy. By setting a large enough perimeter you're able to lazy-load fileupload.js when the perimeter is breached.


Code example

new Perimeter({
    target: 'target3',
    debug: true,
    outline: [50, 500, 50, 0],
    onBreach: function () {
        if ( this.breaches.length === 1 ) {
            $.getScript('script.js');
        }
    }
});

Example 4

Besides passing an ID as target, you can also pass a DOM element.


Code example

Perimeter({
    target: $('#target4')[0],
    debug: true,
    outline: 20,
    onBreach: function () {
        this.target.innerHTML = 'breach!';
    },
    onLeave: function () {
        this.target.innerHTML = '';
    }
});

Example 5

Animating the target element when entering the perimeter. Now, this is just simple animation, but you can imagine sky is the limit when it comes to animating the target element and getting the user's attention.


Code example

Perimeter({
    target: $('#target5')[0],
    debug: true,
    outline: 20,
    onBreach: function () {
        $(this.target).stop().animate({
            'width': this.target.clientWidth*1.5,
            'height': this.target.clientHeight*1.5
        }, 300);
    },
    onLeave: function () {
        // animate to default values
    }
});

Unit tests


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:


About the author

Perimeter.js is written by Boye, a seasoned front-end developer with over eleven years of in-depth web development experience and passionate about web standards. Graduated in 2008 from the Rotterdam University (Media Technology, BICT). Always aiming for semantic, cross-browser & cross-platform consistent and maintainable code.


License

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