Rye

  1. Download Rye 0.1.0 for production
  2. Download Rye 0.1.0 for development

Rye is a lightweight javascript library for DOM manipulation and events with support for all modern browsers, including IE9+. It has support for touch events/gestures, an event emitter, isolated DOM events and more.

Introduction

Rye is a browser library written from the ground-up with modern browsers in mind. It is an attempt to bring together the best practices in javascript, borrowing from both browser and node.js code patterns.

It also tries to be as minimal as possible, using standard browser APIs and ES5 methods whenever possible. Reading the source code is encouraged.

Rye is built as a collection of modules. You can use it whole, or just import specific modules you need. The API should be familiar to everyone who has worked with jQuery or Zepto, but not totally compatible; inconsistencies like .map/.each argument order and behavior have been fixed, and follow the native map/forEach methods.

One important thing to note is that Rye doesn't try to subclass Array in any way. A Rye instance is just a standard object, with the current elements selection stored in the .elements array. All standard ES5 array methods are available and operate on the elements collection; while still providing traversing methods you might know from other libraries like .next, .prev, .children, etc.

Browser compatibility

Browser Version
Chrome 6+
Safari 5+
Firefox 6+
IE 9+
Opera 11.5+
Browser Version
iOS 4.1+ (6.0.1)
Android 4.0+
Blackberry 10+
Opera Mobile 11.1+ (12.1)
Chrome (Android) 18+ (18)
Firefox (Android) 15+ (18)

Things Rye won't do

Rye

Constructor

Rye(selector[, context]) ⤳ rye collection
Rye(element) ⤳ rye collection
Rye(elements) ⤳ rye collection

Creates a Rye collection object.

Rye.define

Rye.define(name, fn)

Stores the function named by a string.

Rye.require

Rye.require(name) ⤳ function

Requires the function stored. All code in Rye is allocated as modules.

Data

Store arbitrary data associated with the matched elements.

data

.data(key[, value]) ⤳ self
.data({property: value, ...}) ⤳ self

Get or set data attached to each element in the .elements array.

@set

data.set(element, key, value)

Stores value in key for element.

@get

data.get(element, key) ⤳ mixed

Returns the value in key for element.

Traversal

find

.find(selector) ⤳ rye collection

Returns a new Rye collection containing the descendants of the current collection.elements, filtered by selector. Uses .querySelectorAll when available.

index

.index(selector) ⤳ number

Returns the index at which an element matching selector can be found. If no argument given, returns the index of the first element in the collection relative to it's siblings.

add

.add(elements) ⤳ rye collection
.add(Rye) ⤳ rye collection
.add(selector[, context]) ⤳ rye collection

Add elements to collection.elements and return a new collection. Unlike push it doesn't modify the objects .elements array.

pluckNode

.pluckNode(property) ⤳ rye collection

Uses DOM APIs to create a new set of elements. property should be a method of HTMLElement, ex. parentNode or childNodes. Filters nodes using util.isElement.

Used internally by next() and prev().

next

.next() ⤳ rye collection

Get the immediately following sibling of each element in collection.

prev

.prev() ⤳ rye collection

Get the immediately preceding sibling of each element in collection.

siblings

.siblings() ⤳ rye collection

Get all the siblings of each element in collection. Returns a unique set.

parent

.parent([selector]) ⤳ rye collection

Get the parent of each element in collection, optionally filtered by selector.

parents

.parents([selector]) ⤳ rye collection

Get the ancestors of each element in collection, optionally filtered by selector.

closest

.closest(selector) ⤳ rye collection

For each element in collection, get the first element that matches selector by testing the element itself then traversing up through its ancestors.

children

.children([selector]) ⤳ rye collection

Get the children of each element in collection, optionally filtered by selector.

Filter

filter

.filter(selector[, inverse]) ⤳ rye collection
.filter(element[, inverse]) ⤳ rye collection
.filter(Rye[, inverse]) ⤳ rye collection
.filter(fn[, inverse]) ⤳ rye collection

Returns a new collection keeping elements that match selector, element, Rye or for which fn returns true, as in Array.prototype.filter.

Provide a truthy value to inverse to reverse the result set.

filter not

.filter('!' + selector) ⤳ rye collection

Aliast to .filter(selector, inverse=true). Example: `collection.filter('!.someclass').

contains

.contains(selector) ⤳ rye collection

Returns a new collection containg elements where at least one descendant matches seletor.

is

.is(selector) ⤳ boolean
.is(element[, inverse]) ⤳ boolean
.is(Rye[, inverse]) ⤳ boolean
.is(fn[, inverse]) ⤳ boolean

Check if the current collection matches selector, element, or the provided function.

first

.first() ⤳ rye collection

Get the first element in the collection.

last

.last() ⤳ rye collection

Get the last element in the collection.

Query

Stand-alone usage: var query = Rye.require('Query')

Query utilities implemented using querySelectorAll and matchesSelector APIs.

@matches

query.matches(element, selector) ⤳ boolean
query.matches(element, element) ⤳ boolean
query.matches(element, Rye) ⤳ boolean

Check that element matches selector, element or another collection. Uses native matchesSelector when available.

@qsa

query.qsa(element, selector) ⤳ array

Perform a CSS selector query using element as root. Uses querySelectorAll, returns a standard Array.

@getClosestNode

query.getClosestNode(element, method[, selector]) ⤳ element

Traversing helper. Recursively call method on element until element matches selector. Returns HTML nodes only.

Collection

get

.get(index) ⤳ element<br>
.get() ⤳ array

Return the element at collection.elements[index]. If no argument given, return a copy of the .elements array.

eq

.eq(index) ⤳ rye collection<br>
.eq() ⤳ empty rye collection

Same as .get(), but returns the element as a Rye collection. If no argument given, return an empty collection.

forEach

.forEach(callback[, thisArg]) ⤳ array

Call Array.prototype.forEach on collection.elements. Callback receives (value, index, array).

reduce

.reduce(callback[, initialValue]) ⤳ array

Call Array.prototype.reduce on collection.elements. Callback receives (previousValue, currentValue, index, array).

reduceRight

.reduceRight(callback[, initialValue]) ⤳ array

Same as .reduce but operates from right-to-left. Callback receives (previousValue, currentValue, index, array).

indexOf

.indexOf(element[, fromIndex]) ⤳ array

Call Array.prototype.indexOf on collection.elements. Returns the first index at which the element is found, or -1 if it is not present.

map

.map(callback[, thisArg]) ⤳ rye collection

Calls Array.prototype.map on collection.elements. Returns a new array with the result of calling callback on each element of the array. Callback receives (value, index, array).

sort

.sort([fn]) ⤳ rye collection

Calls Array.prototype.sort on collection.elements, with fn as comparison function.

each

.each(callback) ⤳ self

Alias for .forEach.

iterate

.iterate(fn, context) ⤳ function

Returns a function that will call fn with context for every element in collection.elements. The function receives the current element plus the arguments given on invocation.

push

.push(element) ⤳ index

Add an element to collection.elements. Returns the new element index.

slice

.slice(start, end) ⤳ rye collection

Calls Array.prototype.slice on collection.elements.

concat

.concat(elements, ...) ⤳ rye collection

Concatenates an array to collection.elements. Accepts instances of Rye.

pluck

.pluck(property) ⤳ array

Plucks the value of property for each element in collection.elements. Alias for util.pluck.

put

.put(property, value) ⤳ array

Sets property to value for each element in collection.elements. Alias for util.put.

Manipulation

text

.text(text) ⤳ self
.text() ⤳ text

Set or get textContent. If no argument given, returns the first element's value.

html

.html(html) ⤳ self
.html() ⤳ html

Set or get innerHTML. If no argument given, returns the first element's value.

empty

.empty() ⤳ self

Sets innerHTML to an empty string '' for all elements.

append

.append(html) ⤳ self
.append(element) ⤳ self

Append html or element to each element in the collection. If the argument is an HTML element, it is cloned before each operation.

prepend

.prepend(html) ⤳ self
.prepend(element) ⤳ self

Prepend 'html' or 'element' to each element in the collection.

after

.after(html) ⤳ self
.after(element) ⤳ self

Insert html or element after each element in the collection.

before

.before(html) ⤳ self
.before(element) ⤳ self

Insert html or element before each element in the collection.

clone

.clone(deep) ⤳ rye collection

Clone elements with cloneNode(deep). deep defaults to true (copy all child nodes).

remove

.remove() ⤳ rye collection

Remove elements that are in the collection.

val

.val() ⤳ string
.val(value) ⤳ self

Get or set the value property for all elements. If no argument given, returns value for the first element only. For a <select multiple> an array of values is returned.

attr

.attr(name) ⤳ string
.attr(name, value) ⤳ self
.attr({name: value, ...}) ⤳ self

When no value is given, reads specified attribute from the first element in the collection using getAttribute.

When value or an object with key:value pairs is given, set the attribute to value on each element in the collection using setAttribute.

prop

.prop(name) ⤳ string
.prop(name, value) ⤳ self
.prop({name: value, ...}) ⤳ self

Get or set the property name for each element. Implemented as an alias to util.pluck and util.put.

Rye.create

Rye.create(html) ⤳ rye collection

Turn a string containing HTML into a DOM element tree.

@getValue

manipulation.getValue(element) ⤳ string

Get the value property of element. Returns an array of values in case element is a <select multiple>.

@getAttribute

manipulation.getAttribute(element, name) ⤳ string

Get the value of name for a given element. Falls back to getValue for getting the value attribute.

Style

show

.show() ⤳ self

Set display: block on each element; if the element has been hidden with .hide() before the display value is preserved.

hide

.hide() ⤳ self

Set display: none on each element. Saves the display value for subsequent calls.

css

.css(prop) ⤳ string
.css(prop, value) ⤳ self

Get or set style properties.

hasClass

.hasClass(className) ⤳ boolean

Check that the elements' class list contains className.

addClass

.addClass(className) ⤳ self

Add className to the elements' class list.

removeClass

.removeClass(className) ⤳ self

Remove className from the elements' class list.

toggleClass

.toggleClass(className, switch) ⤳ self

If switch is a truthy value, add className to the elements' class list, if it's falsy remove className.

@getCSS

style.getCSS(element, property) ⤳ string

Return the value of property in element.style.

@setCSS

style.setCSS(element, property, value) ⤳ element

Set property to value on element.style.

@hasClass

style.hasClass(element, className) ⤳ boolean

Returns true if className is contained in element's class list, false otherwise.

@addClass

style.addClass(element, className) ⤳ element

Add className to element's class list.

@removeClass

style.removeClass(element, className) ⤳ element

Remove className from element's class list.

Event Emitter

Stand-alone event emitter implementation. Rye itself is an instance of EventEmitter, see Rye.publish / Rye.subscribe.

addListener (on)

emitter.addListener(event, handler) ⤳ self
emitter.on(event, handler) ⤳ self

once

emitter.once(event, handler) ⤳ self

removeListener

emitter.removeListener(event[, handler]) ⤳ self

trigger

emitter.trigger(event[, data]) ⤳ self

proxy

emitter.proxy(event) ⤳ function

DOM Event Emitter

Inherits from EventEmitter while handling DOM events. The root element will receive all delegate event handlers. It's used internally to handle event binding.

Using a custom DOMEventEmitter

addListener (on)

emitter.addListener(event, fn) ⤳ self
emitter.on(element, event, fn) ⤳ self

once (one)

emitter.once(event, fn) ⤳ self
emitter.one(event, fn) ⤳ self

removeListener (off)

emitter.removeListener(event[, fn]) ⤳ self
emitter.off(event[, fn]) ⤳ self

destroy

emitter.destroy() ⤳ self

trigger

emitter.trigger(event[, data]) ⤳ self

emit

emitter.trigger(event[, data]) ⤳ self

proxy

emitter.proxy(event) ⤳ function

Events

addListener

.addListener(name, handler) ⤳ self
.on(name, handler) ⤳ self

once

.once(name, handler) ⤳ self

removeListener

.removeListener(name[, handler]) ⤳ self

trigger

.trigger(name[, data]) ⤳ self

@getEmitter

events.getEmitter(element) ⤳ DOMEventEMitter

@createEvent

events.createEvent(type[, properties]) ⤳ Event
events.createEvent(obj[, properties]) ⤳ Event

@addListener

events.addListener(element, name, handler) ⤳ self
events.on(element, name, handler) ⤳ self

@once

events.once(element, name, handler) ⤳ self

@removeListener

events.removeListener(element, name[, handler]) ⤳ self

@trigger

events.trigger(element, name[, data]) ⤳ self

Rye.subscribe

Rye.subscribe(event, handler) ⤳ self

Listen for event on the global event bus.

Rye.unsubscribe

Rye.unsubscribe(event[, handler]) ⤳ self

Stop listening for event on the global event bus.

Rye.publish

Rye.publish(event[, args...]) ⤳ self

Emit event on the global event bus. Extra arguments will be forwarded to event handlers.

Touch Events

touch events sample

Request

Rye.request()

Rye.request(url, callback) ⤳ XMLHttpRequest
Rye.request(settings, callback) ⤳ XMLHttpRequest
Rye.request(settings) ⤳ XMLHttpRequest

Create and send a new XMLHttpRequest. See default options and the XMLHttpRequest documentation.

Rye.get()

Rye.get(url, callback) ⤳ XMLHttpRequest
Rye.get(settings, callback) ⤳ XMLHttpRequest
Rye.get(settings) ⤳ XMLHttpRequest

Calls request() with method set to GET.

Rye.post()

Rye.post(url, callback) ⤳ XMLHttpRequest
Rye.post(settings, callback) ⤳ XMLHttpRequest
Rye.post(settings) ⤳ XMLHttpRequest

Calls request() with method set to POST.

serialize

.serialize() ⤳ string

Encode the form elements in the collection as a string for request submission.

@request

var request = Rye.require('Request')
request(url, callback) ⤳ XMLHttpRequest
request(settings, callback) ⤳ XMLHttpRequest
request(settings) ⤳ XMLHttpRequest

Same as .request().

@serialize

request.serialize(obj) ⤳ string

Serializes obj to a querystring.

@appendQuery

request.appendQuery(url, querystring) ⤳ string

Appends querystring to url while preserving existing values.

@defaults

method       : ['GET', 'POST', ...]
url          : [window.location]
async        : [true]
callback     : function (err, data, xhr) { ... }
timeout      : [0]
headers      : {}
data         : {}
responseType : [json, xml, html, text, arraybuffer, blob, document]
contentType  : ['application/x-www-form-urlencoded']

The object containing the default options for the request() method. Modifications affect all subsequent requests.

@get

request.get(url, callback) <span>⤳ self</span>
request.get(settings, callback) <span>⤳ self</span>
request.get(settings) <span>⤳ self</span>

Shortcut to request() with method set to GET.

@post

request.post(url, callback) <span>⤳ self</span>
request.post(settings, callback) <span>⤳ self</span>
request.post(settings) <span>⤳ self</span>

Shortcut to request() with method set to POST.

Util

Utility methods. Use with var util = Rye.require('Util').

@extend

util.extend(destination, source) ⤳ destination

Merge the contents of two objects together.

@inherits

util.inherits(child, parent) ⤳ child

Sets up prototypal inheritance through a ghost constructor.

@isElement

util.isElement(element) ⤳ boolean

Checks if element is a NODE_ELEMENT or DOCUMENT_ELEMENT.

@isNodeList

util.isNodeList(elements) ⤳ boolean

Checks if elements is a NodeList or HTMLCollection.

@unique

util.unique(array) ⤳ array

Produces a duplicate-free version of the array.

@pluck

util.pluck(array, property) ⤳ array

Pluck an attribute from each item in array.

@put

util.put(array, property, value) ⤳ array

Opposite of pluck. Set property for each item in array.

@prefix

util.prefix(property, obj) ⤳ mixed

Returns a standard or browser-prefixed methods (moz, webkit, ms, o) if found.

@applier

util.applier(direction, fn, context, args) ⤳ function
util.applier('left', fn, context, args) ⤳ function
util.applier('right', fn, context, args) ⤳ function

Returns a function that calls fn.apply(context, ...). The args array is (right or left)-joined to the function call parameters.

@curry

util.curry(fn, ...) ⤳ function

Returns a curried/partially-applied function with the rest of the arguments.

@getUid

util.getUid(element) ⤳ number

Gets an unique identifier for an element.

@type

util.type(obj) ⤳ string

Returns one of [object, function, array, date, string, number, boolean, null, undefined, math, global] by calling Object.prototype.toString on obj.

@is

util.is(type, obj) ⤳ boolean

Checks that obj is of type type (calling util.type). type can contain multiple values, i.e. util.is('string number boolean', foo).