jQuery DOM Line plugin

Quick Links

Basic Rundown

Draw a line on a page between two arbitrary points using a DOM element (usually a div). No SVG, no VML, no canvas.

Requirements

jQuery version 1.4.3 or later.
Louis-Remi Babé’s jQuery transform CSS hook – included by default in the minified version of this plugin

Reference

Usage

$.line(fromPoint, toPoint[, options]);

Draws a line from fromPoint to toPoint using a DOM node (a <div> by default).

fromPoint and toPoint are objects containing x and y (numeric) properties that define points on the page (relative to the top left corner of the page, not the screen).

options is an optional (duh) object as defined below.

Options

The options object can have the following parameters:

elem: DOM node or jQuery selector; If provided, the provided element will be used to make the line, useful for re-using a single element for subsequent lines. If not provided, or left falsey, a new <div> is created.
className: String; CSS class to add to a newly-created <div> – only used if elem option is falsey.
lineWidth: Integer; Desired width (thickness) of the line in pixels.
lineColor: String; Colour of the line – can be any valid CSS colour value.
returnValues: Boolean; If true, returns an object with the calculated dimensions for the line (see Return Values section), instead of a jQuery object. This can be useful for calculating the end point of an animation without changing the DOM node.

Defaults

Default options are defined in the $.line.defaults object as shown:

$.line.defaults = {
    elem: '',   // if falsey, creates a new <div>
    className: 'jquery-line',
    lineWidth: 1,
    lineColor: '#000',
    returnValues: false
};

These can be re-defined to make new default options for all subsequent calls to $.line().

Return Values

If the fromPoint or toPoint objects are not valid, the return value is false.

If the returnValues option is false (the default), the return value is a jQuery object for the line element.

If the returnValues option is true, the return value is an object containing the following properties:

from – The fromPoint argument passed to the function
to – The toPoint argument passed to the function
center – The centre point of the line (and also the point of rotation) – contains x and y properties
rotation – The amount of rotation applied to the line – contains deg (degrees) and rad (radians) properties

Why not SVG or canvas?

To be honest this was more of an experiment for my own needs than anything else, and an excuse to play around with CSS3 transforms. If it suits your needs, that’s good, but if some other solution works for you, that’s fine too.