jQuery.fracs

jQuery.fracs determines some fractions for an HTML element (visible fraction, fraction of the viewport, ...) and also provides the coordinates of these areas. As a bonus there is a page outline feature as seen on the right.

See the demo to get an impression of some of the features.

The sources are available on GitHub where you'll also find a changelog.

Quick start

Fractions

To retrieve the fractions of an element use:

var fracs = $(selector).fracs();

this will return an object of type Fractions.

Or bind a callback function:

function callback(fracs: Fractions, previousFracs: Fractions) {
	...
	// context variable *this* will be the corresponding HTMLElement
	...
};

$(selector).fracs(callback);

The callback function will be called whenever fracs and previousFracs are unequal. A check will be triggered on every window resize or window scroll event. To trigger it manually use

$(selector).fracs('check');

Outline

Add a canvas to your document (use a fixed position to keep it in viewport)

<canvas id="outline" width="200" height="400"></canvas>

and then in your javascript initialize the outline with some OutlineOptions, for example

$("#outline").fracs("outline", {
	crop: true,
	styles: [{
		selector: 'header,footer,section,article',
		fillStyle: 'rgb(230,230,230)'
	}, {
		selector: 'h1',
		fillStyle: 'rgb(240,140,060)'
	}]
});

API

Static methods

document

// Returns the dimension of the whole document.
// 0.5
jQuery.fracs.document(): Rect

fracs

// Returns the fractions for an arbitrary Rect or HTMLElement and viewport,
// viewport defaults to jQuery.fracs.viewport().
jQuery.fracs.fracs(rect: Rect, [viewport: Rect]): Fractions
jQuery.fracs.fracs(element: HTMLElement, [viewport: Rect]): Fractions

// Shortcuts
// 0.9
jQuery.fracs(rect: Rect, [viewport: Rect]): Fractions
jQuery.fracs(element: HTMLElement, [viewport: Rect]): Fractions

rect

// Returns the element's dimensions in document space.
jQuery.fracs.rect(element: HTMLElement): Rect

round

// Returns the rounded value to a given precision, precision defaults to 0.
jQuery.fracs.round(value: float, [precision: int]): float

scroll

// Scrolls the viewport relative to the current position, duration
// defaults to 1000.
// 0.8
jQuery.fracs.scroll(left: int, top: int, [duration: int])

scrollState

// Returns the current scroll state.
// 0.8
jQuery.fracs.scrollState(): ScrollState

// Binds a callback function that will be invoked if scroll state has changed
// after a window resize or window scroll event.
// 0.9
jQuery.fracs.scrollState(callback(state: ScrollState, prevState: ScrollState))

scrollTo

// Scrolls the viewport, duration defaults to 1000.
// 0.4
jQuery.fracs.scrollTo(left: int, top: int, [duration: int])

viewport

// Returns the current viewport in document space.
jQuery.fracs.viewport(): Rect

Methods

'bind'

// Binds a callback function that will be invoked if fractions have changed
// after a window resize or window scroll event.
.fracs(['bind',] callback(fracs: Fractions, prevFracs: Fractions)): jQuery

'check'

// Checks if fractions changed and if so invokes all bound callback functions.
.fracs('check'): jQuery

'cursor'

// Binds a callback function to every selected element that gets triggert
// whenever the Cursor object changes for that element.
// The cursor is checked on every window mousemove event.
// 0.10
.fracs('cursor', callback(cursor: Cursor, prevCursor: Cursor)): jQuery

// Returns an Cursor object assuming that the cursor is at position x,y.
// 0.10
.fracs('cursor', x, y): Cursor

'envelope'

// Returns the smallest rectangle that containes all selected elements.
// 0.6
.fracs('envelope'): Rect

'fracs'

// Returns the fractions for the first selected element.
.fracs(['fracs']): Fractions

'max'

// Reduces the set of selected elements to those with the maximum value
// of the specified property.
// Valid values for property are 'possible', 'visible', 'viewport',
// 'width', 'height', 'left', 'right', 'top', 'bottom'.
// 0.5
.fracs('max', property: String): jQuery

// Binds a callback function to the set of selected elements that gets
// triggert whenever the element with the highest value of the specified
// property changes.
// Valid values for property are 'possible', 'visible', 'viewport',
// 'width', 'height', 'left', 'right', 'top', 'bottom'.
// 0.10
.fracs('max', property: String, callback(best: Element, prevBest: Element)): jQuery

'min'

// Reduces the set of selected elements to those with the minimum value
// of the specified property.
// Valid values for property are 'possible', 'visible', 'viewport',
// 'width', 'height', 'left', 'right', 'top', 'bottom'.
// 0.5
.fracs('min', property: String): jQuery

// Binds a callback function to the set of selected elements that gets
// triggert whenever the element with the lowest value of the specified
// property changes.
// Valid values for property are 'possible', 'visible', 'viewport',
// 'width', 'height', 'left', 'right', 'top', 'bottom'.
// 0.10
.fracs('min', property: String, callback(best: Element, prevBest: Element)): jQuery

'outline'

// Generates a document outline in a selected canvas. Will be redrawn on every window
// resize and scroll event. See an example on the right side bar ->
// 0.5
.fracs('outline', [options: OutlineOptions]): jQuery

// Manually trigger a redraw
// 0.5
.fracs('outline', 'redraw'): jQuery

'rect'

// Returns the dimensions for the first selected element in document space.
.fracs('rect'): Rect

'scrollTo'

// Scrolls to the first selected element in the specified time,
// padding defaults to 0, duration to 1000.
// 0.4
.fracs('scrollTo', [paddingLeft: int,] [paddingTop: int,] [duration: int]): jQuery

'softLink'

// Converts all selected page intern links (<a href="#...">) into soft links.
// Uses 'scrollTo' to scroll to the location.
// 0.5
.fracs('softLink', [paddingLeft: int,] [paddingTop: int,] [duration: int]): jQuery

'unbind'

// Unbinds all or the specified callback function.
.fracs('unbind', [callback: Function]): jQuery

Objects

Cursor

// 0.10
Cursor {

	// absolute distance of the pointer in x and y direction
	distX: int
	distY: int

	// minimum and maximum of distX and distY
	distMin: int
	distMax: int

	// tests if all values are equal
	equals(other: Cursor)

	// real distance of the pointer to the element
	dist(): float
}

Element

// 0.10
Element {

	element: HTMLElement
	fracs: Fractions
	prevFracs: Fractions
	rect: Rect
	prevRect: Rect

	// updates element, true if fracs or rect changed
	update(): boolean
}

Fractions

Fractions {

	// fraction of the element's max possible visibility, this value differs
	// from value visible if the element doesn't fit into the viewport
	possible: float

	// visible fraction of the element
	visible: float

	// fraction of the viewport taken by the element
	viewport: float

	// rects for the visible part of the element, transformed to
	// the different spaces, undefined if invisible
	rects: {
		document: Rect
		element: Rect
		viewport: Rect
	}

	// tests if all fractions and rectangles are equal
	equals(other: Fractions): boolean

	// tests if all fractions are equal
	fracsEqual(other: Fractions): boolean

	// tests if all rectangles are equal
	rectsEqual(other: Fractions): boolean
}

Group

// 0.10
Group {

	elements: [Element, ...]

	// returns the set of group elements that have the highest value
	// of the given property
	max(property: String, asHTMLElements: boolean): [Element, ...] / [HTMLElement, ...]

	// returns the set of group elements that have the lowest value
	// of the given property
	min(property: String, asHTMLElements: boolean): [Element, ...] / [HTMLElement, ...]
}

OutlineOptions

// default options
// 0.5
OutlineOptions {

	// crop the canvas to the used space
	crop: false

	// time to scroll into new position after clicking the outline
	// 0.8
	duration: 100

	// vertical and horizontal alignment of viewport after clicking
	// the outline
	// 0.8
	focusWidth: 0.5
	focusHeight: 0.5

	// array of styles
	styles: [OutlineStyle, ...]

	// viewport styling, selector is ignored
	// 0.8.1
	viewportStyle: OutlineStyle

	// viewport styling while dragging, selector is ignored
	// 0.8.1
	viewportDragStyle: OutlineStyle

	// invert the area that gets styled
	// 0.8.1
	invertViewport: false
}

OutlineStyle

// strokeWidth, strokeColor, fillColor may have the special values
// undefined to ignore and 'auto' to fetch values from css
// 0.5
OutlineStyle {

	// selector to use for that style
	selector: String / HTMLElement / [HTMLElement, ...] / jQuery

	// border stroke width
	strokeWidth: float / undefined / 'auto'

	// border color
	strokeStyle: String / undefined / 'auto'

	// fill color
	fillStyle: String / undefined / 'auto'
}

Rect

Rect {

	left: int
	top: int
	width: int
	height: int
	right: int
	bottom: int

	// tests if all values are equal
	equals(other: Rect): boolean

	// returns the rect's area = width x height
	area(): int

	// returns the intersection of both rectangles, undefined if none
	intersection(other: Rect): Rect

	// returns the smallest rectangle that containes both rectangles
	// 0.6
	envelope(other: Rect): Rect

	// binds a callback function that will be invoked if fractions have changed
	// after a window resize or window scroll event
	// 0.8
	bind(callback(fracs: Fractions, prevFracs: Fractions))

	// unbinds all or the specified callback function
	// 0.8
	unbind([callback: Function])

	// checks if fractions changed and if so invokes all bound callback functions
	// 0.8
	check()

	// returns the fractions for this rectangle
	// 0.8
	fracs(): Fractions
}

ScrollState

// 0.9
ScrollState {

	// width and height are between 0.0 and 1.0 or undefined if viewport shows
	// the whole document in this dimension
	width: float / undefined
	height: float / undefined

	// space in pixels that is left on each side of the viewport
	left: int
	top: int
	right: int
	bottom: int
}

Contact

Lars Jung
lrsjng [at] gmail [dot] com
@lrsjng

License

jQuery.fracs is provided under the terms of the MIT License.