Table of ContentsInstall Design Usage API
Plugin Guide Plugins
* [Core](#core) * [air(selector, [context])](#airselector-context) * [air.Air](#airair) * [new Air(selector, [context])](#new-airselector-context) * [.dom](#dom) * [.length](#length) * [get([index])](#getindex) * [each(iterator)](#eachiterator) * [air(selector, [context])](#airselector-context-1) * [plugin(list)](#pluginlist)
* [append](#append) * [attr](#attr) * [children](#children)
* [Array Access](#array-access) * [HTML Parsing](#html-parsing) * [AJAX](#ajax) * [Element Data](#element-data) * [XML](#xml) * [Selector Extensions](#selector-extensions) * [Redundancy](#redundancy) * [Dimension](#dimension)
* [Test](#test) * [Cover](#cover) * [Lint](#lint) * [Clean](#clean) * [Dist](#dist) * [Spec](#spec) * [Instrument](#instrument) * [Readme](#readme)
Lightweight, modular DOM library.
Browser targets are relatively modern browsers from IE9+, Chrome, Firefox, Safari and modern versions of Opera (post blink integration).
This library is not designed to be a drop-in replacement for jquery, it is designed to provide a modular library that is jqueryesque therefore it is best suited to new projects.
Work in progress: not yet ready for production.
npm i air --save
DesignWhilst the API is similar to jquery some notable design decisions:
- Plugin architecture.
- No global variables.
- Stay focused, see compatibility.
To get a feel for how lightweight
airis see air.js, the core of the system is less than 100 lines of code (with comments). All other files in lib are plugins that should be loaded depending upon your application requirements.
UsageDesigned to work with browserify by default, assuming you have configured the browserify
pathsoption correctly for
var $ = require('air'); $.plugin([ require('air/event') ])
Note that the plugins are namespaced to prevent potential collisions when an application is using multiple plugin-enabled components.
APIThe main function
airwraps a set of elements in a class that may be decorated by plugins.
CoreCore functionality is the main method, the class function and the pre-defined properties and methods on the class, see air.js.
air(selector, context)Returns an
air.AirReference to the
new Air(selector, context)Class constructor.
Accepts a selector
Airinstance or array of elements.
contextargument is only applicable when a selector
Stringargument is used and should reference the parent
When an existing
Airinstance is passed the underlying array is copied but the elements are not cloned.
var $ = require('air'); $('body'); // String (selector) $(document.querySelector('body')); // Element $(document.getElementById('id')); // Element $(document.querySelectorAll('div')); // NodeList $([document.getElementById('id')]); // Array $($('body')); // Air
.domThe underlying array of elements.
.lengthThe number of encapsulated elements.
get(index)Get the element at the specified index, if no arguments are passed the
domarray is returned.
each(iterator)Iterate the underlying elements, alias for
air(selector, context)Alias to the main
airfunction, allows instance methods to wrap elements using
plugin(list)Alias to the
pluginfunction, allows instance methods to load plugins via
Plugin GuidePlugin functionality is provided by zephyr see the zephyr plugins documentation.
PluginsDefault plugins that may be loaded on demand, syntax examples assume that
airhas been aliased to
Everything except the core methods are implemented as plugins so there are many examples in lib.
appendInsert content, specified by the parameter, to the end of each element in the set of matched elements.
- File: append.js.
- Dependencies: none.
attrGet the value of an attribute for the first element in the set of matched elements or set one or more attributes for every matched element.
$(selector, [context]).attr(name); $(selector, [context]).attr(name, value); $(selector, [context]).attr(attributes);
- File: attr.js.
- Dependencies: none.
childrenGet the children of each element in the set of matched elements.
- File: children.js.
- Dependencies: none.
Plugin GroupsPlugin groups provide a convenient way to load related plugins.
AttributesElement attribute plugins.
CompatibilitySome features available in jquery that there are no plans to implement.
Array AccessAccessing the underlying DOM elements using array bracket notation
is not available, if you wish to access the encapsulated elements use the core methods.
HTML ParsingWhilst jquery allows HTML parsing (eg:
$('<p></p>')) this library does not support it and there are no plans to implement this functionality, the rationale is:
- Confuses the semantics of
- You can create elements easily by chaining function calls.
- For complex requirements a template library is a better option.
- Implementing complex expressions to prevent xss attacks is not a good idea, best to avoid potentially tainted input wherever possible.
Note that recent jquery versions now recommend
$.parseHTMLrather than passing markup to
AJAXThis is deemed to be irrelevant to DOM manipulation and is best left to one of the many capable libraries available.
dataplugin allows manipulating the
data-attributes of an element but does not store any data on the element itself. If you wish to maintain data as part of your application it would be best resolved using another pattern (eg: storage).
If you really need to assign arbitrary data to an element you can always do so by directly setting properties on the element.
XMLDesigned to work with
HTMLdocuments the behaviour when modifying
XMLdocuments is undefined.
Selector ExtensionsThe jquery library extends CSS selectors with pseudo-selectors such as
:checked, we believe this is unnecessary as all selector extension functionality can be achieved using other means.
RedundancyWe aim to provide a single way to perform a task, the jquery library often provides multiple ways to achieve the same thing, for example:
airlibrary will usually prefer the shorter and most common variant and not supply the alternatives; using the above examples the equivalent functions are
DimensionWhilst the jquery dimension methods (
innerWidth()etc.) allow setting element dimensions we prefer (for the sake of simplicity) to make these read-only as you can already set element dimensions using the
cssplugin. It is possible that this may change in the future.
DeveloperDeveloper workflow is via gulp but should be executed as
npmscripts to enable shell execution where necessary.
TestRun the headless test suite using phantomjs:
To run the tests in a browser context open test/index.html.
CoverRun the test suite and generate code coverage:
npm run cover
LintRun the source tree through jshint and jscs:
npm run lint
CleanRemove generated files:
npm run clean
DistCreate distribution builds in dist:
npm run dist
SpecCompile the test specifications:
npm run spec
InstrumentGenerate instrumented code from
npm run instrument
ReadmeGenerate the project readme file (requires mdp):
npm run readme
- Get the core plugins stable and well tested with comprehensive code coverage.
- Build a command line interface to generate custom plugin builds for various module standards including umd, requirejs and systemjs.
LicenseEverything is MIT. Read the license if you feel inclined.
Generated by mdp(1).