$b: Bicycle Chain - Bicycle Chain Addons

Bicycle Chain adds chainability to the Core (global) package and some new methods

Bicycle Chain Addons adds new functions and methods, DOM ready handling (credit and docs: DOMAssistant) and an AJAX Handling Object (credit and docs: Patrick Hunlock).

Function Namespace Summary
Constructor Attributes	Constructor Name and Description
	$b(els)

Bicycle Chain: Method Summary
Method Attributes	Method Name and Description
	length() Counts elements contained in stack
	get(tag, opts) Gets elements contained by current matched elements.
	add() Adds elements to the elements stack.
	item(i, grab) Extracts a specific item from the stack.
	byClass(c, tag) Shortcut to get elements by classname.
	each(fn) Iterates a function on elements stack.
	getNext() Gets next simbling element of the first element in the stack
	getPrev() Gets previous simbling element of the first element in the stack
	on(type, fn) Fires a function on a specific event on the elements stack
	removeEvent(e, h) Removes a registered event handler from elements stack
	removeEvents(e) Removes all handlers registered for the specified event(s)
	txt() Returns text of first element in the stack stripping all childs html tags
	attr(attr, val) Gets or Sets elements attribute
	Styles(prop, val) Single CSS style manipulation.
	css(o, val) Single - Multiple CSS manipulation
	toggle() Toggles visibility of stack elements by CSS
	dimension(d) Returns the dimensions in px of the first element in the stack
	position(axis, parent, scrolling) Returns the position in px of the first element in the stack.
	space() Returns an object containing dimensions and position of the first element in the stack.
	mousePosition(e) Gets the current mouse position relative to the first element in the stack.
	clear() Removes all child elements of the stack elements.
	append(c) Appends the given child(ren) element(s) to each element in the stack
	replace(e) Replaces the current children elements of each element in the stack with the passed in element(s).
	queueTo(ref, parent) Inserts stack elements inside a parent node and after a reference node.
<static>	$b.extend(obj) Static method to extend Bicycle Chain

Bicycle Chain Addons: Method Summary
Method Attributes	Method Name and Description
	items(num, offset, grab) Gets specific(s) element(s) from the stack, or returns elements stack array.
	hasClass(className) Tests if the first element in the stack has passed in class name.
	addClass(className) Adds a className to each element of the stack.
	removeClass(className) Removes a class from each element of the stack.
	toggleClass(className,switch) Removes or adds a class to each element of the stack.
	delegate(eventType, rules, prevent) Event delegation shortcut.
	html(c) Gets or Sets HTML for the first element in the stack.
	remove() Removes all the elements in the stack.
	filter(fn) Filters elements in the stack by a function.
	filterByString(filter) Filters elements in the stack by class or tag name.
	parent(str) Gets the parent element of each element in the stack.
	parents(str) Gets all parent elements of each element in the stack
	ajaxload(url, fn) Loads via AJAX content of a given file inside stack elements.
<static>	$b.preventDefault(evt) Prevents the default behaviour to be launched.
<static>	$b.cancelBubble(evt) Prevents the propagation of the event.
<static>	$b.getTarget(evt) Gets a reference to the element which triggered the event.
<static>	$b.isMouseLeaveOrEnter(e, handler) Fixes for mouseover and mouseout event handlers.
<static>	$b.ready(fn) Shortcut for $b(document).on("domready",fn).
	val(v) Gets or set form elements value.

Function Namespace Detail

$b(els)

Returns a Bicycle Chain object populating the elements' stack with passed in arguments.

Is extended by the $b.engine binding


$b("#myId",document.getElementById("otherId"),"a",".myClass",[element1,element2]);

Parameters:
{String|Array|Collection} els: Comma separated arguments can be a CSS simple string to get single class,id,tag, a DOM element, and array or Collection of Elements.

Method Detail

{Integer} length()

Counts elements contained in stack

Returns:: {Integer} elements stack count

{Object} get(tag, opts)

Gets elements contained by current matched elements. Replace previously matched elements.

Is extended by the $b.engine binding

$b("myId").get("a",{"class":"myClass"});

Parameters:
{String} tag: Search a specific tag or * for all tags
{Object} opts Optional: Object containing pairs of tag attribute : attribute value

Returns:: {Object} this

See:: getElements in bicycle-core

{Object} add()

Adds elements to the elements stack.

Is extended by the $b.engine binding


$b("#myId").add("#otherId"); //element stack is [myId,otherId]

Parameters:
{String} ...: mixed arguments

Returns:: {Object} this

See:: #$b

{Object} item(i, grab)

Extracts a specific item from the stack.


$b("a").item(0); // element stack is reduced to the first element in the stack
$b("a").item(0,true); //returns the first element reference

Parameters:
{Number|String} i: Can be the index of the element or "last" to extract the last element in the stack
grab: if set to true will the element(s) reference, else a Bicyle object will be returned

Returns:: {Object} this or element if grab is true (default: false)

{Object} byClass(c, tag)

Shortcut to get elements by classname.

$b("#myId").byClass("myClass");

Parameters:
{String} c: The searched class name
{String} tag Optional: Optional tag name

Returns:: {Object} this

See:: #get

{Object} each(fn)

Iterates a function on elements stack.

Parameters:
{Function} fn: The function to iterate takes as optional arguments the element and it's index in the stack

Returns:: {Object} this

See:: Array.map in bicycle Core

{Object} getNext()

Gets next simbling element of the first element in the stack

Returns:: {Object} this

{Object} getPrev()

Gets previous simbling element of the first element in the stack

Returns:: {Object} this

{Object} on(type, fn)

Fires a function on a specific event on the elements stack.

Bicycle Chain Addons features some additional events below the standard ones:

domready: fires a function when DOM is ready (see http://code.google.com/p/domassistant/)
mouseenter / mouseleave: Fix mouseover and mouseout events for elements containing childrens
mousewheel: Fix MouseWheel scrolling event handling (see http://www.devpro.it/javascript_id_134.html)

Other events can be attached by extending the $b.events object:


$b.events.myEvent = function () {
  // code goes here!
  // "this" refers to $b object
}


$b("#myId").on("click",myFunction);

Parameters:
{String|Array} type: Type of event, either string or events array
{Function} fn: The function to fire

Returns:: {Object} this

See:: addHlandler in bicycle-core

{Object} removeEvent(e, h)

Removes a registered event handler from elements stack

$b("#myId").removeEvent("click",myFunction);

Parameters:
{String|Array} e: Event(s) to remove, either string or events array
{Function} h: Specific handler to remove

Returns:: {Object} this

{Object} removeEvents(e)

Removes all handlers registered for the specified event(s)

$b("#myId").removeEvents("click");

Parameters:
{String|Array} e: The event(s) handler to clear, either string or events array

Returns:: {Object} this

{String} txt()

Returns text of first element in the stack stripping all childs html tags

Returns:: {String} contained text

{Object|String} attr(attr, val)

Gets or Sets elements attribute

$b("#myId").attr("title"); // get element title
$b("#myId").attr("title","new title"); // set elements title

Parameters:
{Object} attr
{Object} val Optional: value of the attribute

Returns:: {Object|String} if v is not defined returns this, else returns attribute value of the first element in the stack

{Object|String} Styles(prop, val)

Single CSS style manipulation.

Parameters:
{String} prop: The CSS property
{String} val Optional: New value for the CSS property $b("#myId").Styles("color"); //returns element color $b("#myId").Styles("color","#000"); //sets element color

Returns:: {Object|String} If val is not defined returns the CSS property value, else returns this

{Object|String} css(o, val)

Single - Multiple CSS manipulation


$b("#myId").css("color","#000"); //sets element color 
$b("#myId").css({"color","#000","margin-bottom":"10px"}); //sets element color and bottom margin

Parameters:
{Object|String} o: Object with CSS property : CSS value or a CSS property string
{String} val Optional: if o is a string, the new CSS value

Returns:: {Object|String} if o is a string and value is not defined returns the CSS propoerty value, else returns this

See:: #Styles

{Object} toggle()

Toggles visibility of stack elements by CSS

Returns:: {Object} this

{Object|String} dimension(d)

Returns the dimensions in px of the first element in the stack


$b(window).dimension("w"); // get window dimension
$b("#myId").dimension(); // {width:'100px',height:'200px'}

Parameters:
{String} d Optional: return a specific dimension: "w" for width, "h" for heigth

Returns:: {Object|String} if no specific dimension is requested returns an object {width:value,height:value}

{Object|String} position(axis, parent, scrolling)

Returns the position in px of the first element in the stack.

$b("#myId").position(); // get element position
$b("#myId").position(false,"containerId"); // position relative to containerId {x:'100px',y:'200px'}

Parameters:
{Object} axis Optional: Specific position to get "x" or "y"
{Object|String} parent Optional: The parent element to start measures from, if is a string than referes to a ID, defaults to body
{Bool} scrolling Optional: Scrolling inside of elements should be subtracted (default: true - better for absolute positioning).

Returns:: {Object|String} if no specific dimension is requested returns an object {x:value,y:value}

{Object} space()

An object containing dimensions and position of the first element in the stack.

Returns:: {Object} Object with dimensions and position

See:: #position; #dimension

{Object} mousePosition(e)

Gets the current mouse position relative to the first element in the stack.

Parameters:
{Object} e: The event attached to the mouse action

Returns:: {Object} x,y position of the mouse

{Object} clear()

Removes all child elements of the stack elements.

Returns:: {Object} this

{Object} append(c)

Appends the given child(ren) element(s) to each element in the stack

Parameters:
{Object|Array} c: Child(ren), can be either a DOM element or an array of DOM elements.

Returns:: {Object} this

{Object} replace(e)

Replaces the current children elements of each element in the stack with the passed in element(s).

Parameters:
{Object|Array} e: New child(ren) element(s). Can be either a DOM element or an array of DOM elements.

Returns:: {Object} this

{Object} queueTo(ref, parent)

Inserts stack elements inside a parent node and after a reference node.

Parameters:
{Object} ref Optional: Reference node. If None is found just appends the node element inside the parent.
{Object|String} parent Optional: Parent element, can be a DOM element or a string that refer to a ID, defaults to document

Returns:: {Object} this

<static> $b.extend(obj)

Static method to extend Bicycle Chain

$b.extend({
	myfunction : function (v) {
		alert(v);
		return this; // add this line to make this method chainable
	}
});

Parameters:
{Object} obj: An object cointaining functions to extend Bicycle

Bicycle Chain Addons Methods and Function

{Object|Array} items(num, offset, grab)

Gets specific(s) element(s) from the stack, or returns elements stack array.


$b("a").items(); // returns an array containing all link items
$b("a").items(2).attr("title","new title"); //change title to the first 2 link items
$b("a").items(2,-1).attr("title","new title"); //change title to the last two link items
$b("a").items(2,0,true); // returns an array containing just the first two link items

Parameters:
{Number} num Optional: Number of items to extract (defaults to 0, extract 1 element)
{Number} offset Optional: Start index for extraction (can be negative, defaults to 0)
grab

Returns:: {Object|Array} if num is specified and grab is false (default) returns this, else returns all elements in stack as an array

{Bool} hasClass(className)

Tests if the first element in the stack has passed in class name.
Author: Robert Nyman/DOMAssistant team: http://code.google.com/p/domassistant/.

Parameters:
{String} className: The class name to test

Returns:: {Bool} Returns true if item has passed in class

{Object} addClass(className)

Adds a className to each element of the stack.
Author: Robert Nyman/DOMAssistant team: http://code.google.com/p/domassistant/.

Parameters:
{String} className: The class to add

Returns:: {Object} this

{Object} removeClass(className)

Removes a class from each element of the stack.
Author: Robert Nyman/DOMAssistant team: http://code.google.com/p/domassistant/.

Parameters:
{String} className: The class to remove

Returns:: {Object} this

{Object} toggleClass(className,switch)

Removes or adds a class to each element of the stack checking if it's already present in the element. If switch is passed, then the add/remove operation is based on it boolean value

Parameters:
{String} className: The class to remove or add
{Bool} switch Optional: if set to true className will be applyed to elements

Returns:: {Object} this

{Object} delegate(eventType, rules, prevent)

Event delegation shortcut.

// all elements with class "myClass" inside container "myId"
// run a function on click event
$b("#myId).delegate("click",{
		"myClass": function () {
			alert($b(this).attr("href"));
		}
});

Parameters:
{String|Array} eventType: Type of event
{Object} rules: Object with Element class Name : function to fire
{Bool} prevent Optional: Prevent the default element behaviour, defaults to true

Returns:: {Object} this

See:: #on

{Object|String} html(c)

Gets or Sets HTML for the first element in the stack.

Parameters:
{String} c Optional: HTML String inject in the element

Returns:: {Object|String} If c is defined returns this else returns the content on the element as a string

{Object} remove()

Removes all the elements in the stack.

Returns:: {Object} this

{Object} filter(fn)

Filters elements in the stack by a function.

Parameters:
{Function} fn

Returns:: {Object} this

See:: Array.filter

{Object} filterByString(filter)

Filters elements in the stack by class or tag name.

$b("a").filterByString(".myClass"); //gets all link element with class "myClass"

Parameters:
{String} filter: Accepts a CSS class name (ie: ".myClass" ) or a tag name

Returns:: {Object} this

{Object} parent(str)

Gets the parent element of each element in the stack.

Parameters:
{String} str Optional: Optional filter for parent #filterByString

Returns:: {Object} this

{Object} parents(str)

Gets all parent elements of each element in the stack

$b("#myId").parents("div"); //get all div elements containing selected element

Parameters:
{String} str Optional: Optional filter for parent #filterByString

Returns:: {Object} this

{Object} ajaxload(url, fn)

Loads via AJAX content of a given file inside stack elements.

Parameters:
{String} url: Url of the filename which holds the content
{Function } fn Optional: A callback function

Returns:: {Object} this

<static> $b.preventDefault(evt)

Prevents the default behaviour to be launched.

Parameters:
{Object} evt: event

<static> $b.cancelBubble(evt)

Prevents the propagation of the event.

Parameters:
{Object} evt: event

<static> {Object} $b.getTarget(evt)

Gets a reference to the element which triggered the event.

Parameters:
{Object} evt: event

Returns:: {Object} the target reference. You can work on it using $b() wrapper

<static> $b.isMouseLeaveOrEnter(e, handler)

Fixes for mouseover and mouseout event handlers.
Author: http://www.dynamic-tools.net/toolbox/isMouseLeaveOrEnter/.

Parameters:
{Object} e: The event
{Object} handler: The object which handles the event

<static> {Object} $b.ready(fn)

Shortcut for $b(document).on("domready",fn).

Parameters:
{Function} fn: The function to fire on DOM ready

Returns:: {Object} this

See:: #on

{Object|String|Array} val(v)

Gets or set elements value.

Parameters:
{Object} v Optional: Fields value to set

Returns:: {Object|String|Array} If param v is set returns the form object, else returns the field value or an array of checked fields values (for checkboxes)

See:: $b.getForm#value

Classes

$b: Bicycle Chain - Bicycle Chain Addons

Bicycle Chain Addons Methods and Function