Peter Wilson

CraneJS

CraneJS is a micro-JavaScript library containing just the basics of DOM manipulation.

By default, CraneJS uses a simple selector engine (adapted from ess.js) but defers to Sizzle if it exists.

Events are based around Dean Edward’s addEvent and there is much inspiration from jQuery.

The returned object is very similar to the jQuery object – an apparent array of elements.

Download now or clone the GitHub Repo.

We don’t need another library

My motivation for making this was to teach myself JavaScript, a secondary consideration was to make a library with just the basics.

API

Selectors

The default selector engine accepts three types of selectors:

  • IDs,
  • Classes,
  • Elements,
  • decendant selectors, and,
  • comma separated selectors

Examples of valid selectors include:

crane('.js-hook');
crane('#js-hook');
crane('div');

crane('.js-hook div');
crane('.js-hook div, #js-hook span');

Examples of invalid selectors include:

//over qualified selectors
crane('li.js-hook');

//child combinators
crane('#js-hook > div')

These and other more complex selectors require using Sizzle for your selector engine.

Class manipulation

CraneJS includes the classic class manipulation functions

crane('.js-hook').addClass('active');
crane('.js-hook').removeClass('active');

You can use hasClass to check if an element has a class already. This function can not be chained as it returns true or false.

crane('.js-hook').hasClass('active');

If the crane object includes multiple elements, true is returned if any of the elements include the class.

Events

Adding and removing events are handled with addEvent and removeEvent, both accept the same arguments:

  • type: the event type,
  • handler: the function to run on the event

function blur_event(e) {
  console.log( 'Song Two' );
}

//add the blur event
crane('.js-hook').addEvent( 'blur', blur_event );

//remove the blur event
crane('.js-hook').removeEvent( 'blur', blur_event );

Shortcut functions exist for adding common events to elements, these include

  • click
  • focus
  • keydown
  • keyup
  • keypress
  • mouseenter
  • mouseleave

These functions accept one argument only, the event handler

crane('.js-hook').blur( blur_event );

The hover function is a shortcut for adding both mouse in and out events

crane('.js-hook').hover( mousein_event, mouseout_event );

DOM manipulation

Adding elements to the DOM can be done using append and prepend.

Both accept a single argument, the element to be added to the DOM.

This argument can be passed in a number of formats:

  • a string,
  • an element,
  • a nodeList,
  • an HTMLcollection,
  • a craneJS object, or,
  • an array of elements

Valid examples to append paragraphs include:

//add a single, new paragraph
var para = document.createElement( 'p' );
crane('.js-hook').append( para );
crane('.js-hook').append( 'p' );

//append all paragraphs in the document
var paragraphs = element.getElementsByTagName( 'p' )
crane('.js-hook').append( paragraphs );
crane('.js-hook').append( crane('p') );

Appending an existing element, as in the last two examples, will remove the element from its original location and move it into the new location. If there are multiple new locations, it will be cloned.

Removing elements from the DOM

Elements can be removed from the DOM using the remove function:

crane('.js-hook').remove();

Traversing

find

Find allows you to select elements with a certain context (or contexts) only.

//find paragraphs under .js-hook
crane('.js-hook').find('p');

Sub-sets

You can limit crane to a subset of elements the following functions.

These are more reliable when using Sizzle.

//the nth selected element
crane('.js-hook').eq(n);

//the nth last selected element
crane('.js-hook').eq( -n );

//the first selected element
crane('.js-hook').first(); //equivalent to
crane('.js-hook').eq(0);

//the last selected element
crane('.js-hook').last(); //equivalent to
crane('.js-hook').eq( -1 );

//the nth selected element as a native JavaScript node
crane('.js-hook').get(n);

//the nth last selected element as a native JavaScript node
crane('.js-hook').get( -n );

Various other bits and bobs I haven’t got around to documenting

Things like

  • data
  • sort
  • splice
  • push
  • other items added after this document was written