eric.js
v0.1.10
Published
A fast and tiny DOM navigation and manipulation library.
Downloads
19
Readme
eric.js
eric.js
is a fast and tiny DOM navigation and manipulation library.
Many similar libraries add so many features, that they have become bloated and slow, creating noticable data traffic for your servers and your users.
eric.js
aims to replace the most utilised features of jQuery and is of similar usage.
This library is by far not extensive yet, but the most necessary features are already implemented and ready to be used.
We will update this package as required by your suggestions and our own use cases.
Using eric
instances
e(query)
Instantiate an
eric
object.
query
is either of type string
, function
or object
.
typeof query === 'string'
Select DOM-Elements.
Select elements with document.querySelectorAll(query)
.
Example:
let featureImages = e('main div.feature-image');
typeof query === 'function'
The given callback function is called when the
DOMContentLoaded
event is fired.
Example:
e(function () {
alert('DOMContentLoaded fired');
});
typeof query === 'object'
Lets you specify a list of elements, or a single one to select and use.
Valid object
types are Eric
, Array
, HTMLCollection
, NodeList
, and Node
.
If query
is of an invalid object type, the selection will be empty instead.
If query instanceof Eric
, query
will be cloned.
Examples:
let myApp1 = e(document.querySelectorAll('#app'));
// is equivalent to
let myApp2 = e('#app');
// only select frist DOM-Element with id 'wrapper'
let myWrapper1 = e(document.getElementById('wrapper'));
// is equivalent to
let myWrapper2 = e().query('wrapper').id().select();
// select *all* DOM-Elements with id 'wrapper'
let myWrappers1 = e('#wrapper');
// which is equivalent to
let myWrappers2 = e().query('#wrapper').all().select();
// and even
let myWrappers3 = e().select('#wrapper');
// cloning it
let myWrappers4 = e(myWrappers3);
More on query selectors and pushing elements to eric
instances …
// select first element of id 'demoid' and all with classname 'exampleclass'
let myElements = [
document.getElementById('demoid'),
...document.getElementsByClassName('exampleclass'),
];
// add all elements with classname 'testclass'
myElements = myElements.concat(document.getElementsByClassName('testclass'));
let mySelection = e(myElements);
// similar (but not identical) to
let myBroaderSelection = e('#demoid, .exampleclass, .testclass');
Selecting elements
e().set(elements)
Set the current selection of elements of an
eric
instance.
Valid elements
parameter types are Array
, HTMLCollection
, NodeList
and Node
.
e().select(query)
Change the current selection of an
eric
instance.
Here, query
has to be a String
.
Equivalent to e(query)
or eric.query(query).all().select()
.
e().query(query)
Change the current selection of an
eric
instance.
Here, only a string
is expected as query
parameter.
eric.query(query)
returns an object with the following methods. Each of these methods returns an object of options to
either select()
queried elements to replace the current selection, or push()
them to or unshift()
them into the
existing selection of elements; these two methods return the modified eric
instance.
eric.query(query).first().select()
,eric.query(query).first().push()
,eric.query(query).first().unshift()
Uses document.querySelector(query)
to select elements.
eric.query(query).all().select()
,eric.query(query).all().push()
,eric.query(query).all().unshift()
Uses document.querySelectorAll(query)
to select elements.
eric.query(query).id().select()
,eric.query(query).id().push()
,eric.query(query).id().unshift()
Uses document.getElementById(query)
to select elements.
eric.query(query).classname().select()
,eric.query(query).classname().push()
,eric.query(query).classname().unshift()
Uses document.getElementsByClassName(query)
to select elements.
e().find(query)
Create a new
eric
instance with any child elements of the current selection matching the given query.
Use a String
for query
.
Uses element.querySelectorAll(query)
foreach selected element to select the new ones.
e().push(query)
Append elements to the current selection of an
eric
instance.
Valid query
types are String
, Array
, HTMLCollection
, NodeList
and Node
.
If typeof query === 'string'
, this is equivalent to eric.query(query).all().push()
.
e().pop(getNode = false, empty = true)
Pop the last element off of the current selection of an
eric
instance.
If getNode = true
, the actual Node
/HTMLElement
is returned instead of a new eric
instance containing the popped element.
If the current selection is empty, whereupon no element can be popped:
- An empty eric instance will be returned by default (
empty = true
), onempty = false
,undefined
will be returned instead; - If
(getNode && empty) == true
, an emptye.emptyNode()
will be returned.
e().unshift(query)
Prepend elements to the current selection of an
eric
instance.
Valid query
types are String
, Array
, HTMLCollection
, NodeList
and Node
.
If typeof query === 'string'
, this is equivalent to eric.query(query).all().unshift()
.
e().shift(getNode = false, empty = true)
Pop the first element off of the current selection of an
eric
instance.
If getNode = true
, the actual Node
/HTMLElement
is returned instead of a new eric
instance containing the popped element.
If the current selection is empty, whereupon no element can be popped:
- An empty eric instance will be returned by default (
empty == true
), onempty = false
,undefined
will be returned instead; - If
(getNode && empty) == true
, an emptye.emptyNode()
will be returned.
e().create(tag, options = {})
Create an element and push it to the current selection.
Uses document.createElement(tag)
.
All options
will be defined as properties of the created element.
If options.prepend = true
, the created element won't be push
ed, but unshift
ed to the selection.
options.attributes
may be an object of key: value
pairs to be set as attributes (Attr
) of the created HTMLElement
.
e().attach(parent, cloneAttach = false)
Appends the selected elements as children to one or more parents.
If cloneAttach = false
, the selected elements will be attached to the first element matching the parent
query.
If cloneAttach = true
, the selected elements will be cloned and attached to all elements matching the parent
query.
If parent
is not an existing eric
instance, it will be used in a new eric
constructor.
e().append(elements, cloneAppend = false)
Appends the given
elements
as children to the currently selected elements.
If cloneAppend = false
, the given elements
will be appended to the first currently selected element.
If cloneAppend = true
, the given elements
will be cloned and appended to all currently selected elements.
If elements
is not an existing eric
instance, it will be used in a new eric
constructor.
e().parents(getNodes = false)
Get all parents of the currently selected elements.
If getNodes = true
, an array of Nodes will be returned instead of a new eric
instance containing the parents.
Get selected elements
If getNode = true
a Node
/HTMLElement
will be returned instead of a new eric
instance containing the first
element of the selection.
If empty = false
and no elements are currently selected, undefined
is returned instead of a new empty eric
instance (with getNode = false
), or an empty e.emptyNode()
(with getNode = true
).
e().first(getNode = false, empty = true)
Returns the first of the selected elements.
e().last(getNode = false, empty = true)
Returns the last of the selected elements.
e().get(n, getNode = false, empty = true)
Returns the nth selected element.
Where n
is your wanted index and typeof n === 'number'
.
Manipulate elements
e().each(callback)
Executes the
callback
function for each selected element.
Calls e.forEach(elements, callback)
with the given callback
on the selected elements.
e().class(classnames)
Manipulate classnames of the selected elements.
Returns an object with the following methods. If the returnClass
parameter is true
, these methods will return this
same object, instead of the respective eric
instance, to make method chaining easier.
e().class(classnames).add(returnClass = false)
Add the given classnames to each selected element’s
classList
.
Example:
e('nav .menu-item').class('is-active').add();
e().class(classnames).remove(returnClass = false)
Remove the given classnames from each selected element’s
classList
.
Example:
e('nav .menu-item').class('is-active').remove();
e().class(classnames).toggle(returnClass = false)
Toogle the given classnames on each individual selected element’s
classList
.
Example:
e('nav .menu-item').class('is-active').toggle();
e().class(classnames).unify(returnClass = false)
If the first selected element’s
classList
contains the givenclassnames
, they will be added to the others. If it does not contain them, they will be removed from all other elements.
Example:
e('nav .menu-item').class('is-active').unify();
// Ensures that all selected elements either do or do not have the desired class before toggling.
e('nav .menu-item').class('is-active').unify(true).toggle();
e().class(classnames).has()
Returns a boolean, whether the first element’s
classList
contains the givenclassnames
.
Example:
if (e('nav .menu-item').class('is-active').has()) {
// First selected element has class 'is-active'.
}
e().class(classnames).have()
Returns a boolean, whether all selected element’s
classList
s contain the givenclassnames
.
Example:
if (e('nav .menu-item').class('is-active').have()) {
// All selected elements have class 'is-active'.
}
e().class(classnames).any()
Returns a boolean, whether any of the selected element’s
classList
s contain the givenclassnames
.
Example:
if (e('nav .menu-item').class('is-active').any()) {
// At least one of the selected elements has class 'is-active'.
}
e().attr(key, value = null)
Manipulate attributes of the selected elements.
- If only a
key
is given, orvalue = null
, the current value of the first selected element’s corresponding attribute is returned.
Example:
<img id="my-img" alt="An Example Image" src="/images/example.jpg" />
let src = e('#my-img').attr('src');
// src === '/images/example.jpg'
- If the given
value
is notnull
orfalse
, the attribute’s value is changed accordingly on all selected elements.
Example: (HTML as above)
e('#my-img').attr('alt', 'A Beautiful Picture');
Results in:
<img id="my-img" alt="A Beautiful Picture" src="/images/example.jpg" />
- If
value = false
, the given attribute is removed from all selected elements.
Example: (HTML as above)
e('#my-img').attr('src', false);
Results in:
<img id="my-img" alt="A Beautiful Picture" />
e().data(key, value = null)
Manipulate data-attributes of the selected elements.
Same functionality as eric.attr(key, value)
, but prefixes attribute names with data-
, to simplify data-attribute
access.
Example:
<input id="my-input" data-old="old input value" />
let myInput = e('#my-input');
let oldValue = myInput.data('old');
// oldValue === 'old input value'
// => Thus:
myInput.data('old', false);
myInput.data('info', 'example value');
<!-- => results in: -->
<input id="my-input" data-info="example value" />
e().text(value = null)
Get the
innerText
property of the first selected element or changetextContent
on all.
e().getTextContent()
Get the
textContent
property of the first selected element.
e().html(value = null)
Get the
innerHTML
property of the first selected element or change it on all.
e().val(value = null)
Get the
value
attribute of the first selected element or change it on all.
Manipulate the DOM structure
e().remove(retain = false)
Delete all selected elements from the DOM.
If retain = true
, the removed elements are not removed from the eric
instance's selected elements list.
e().empty(textContentMode = true, retainText = false)
Delete all child elements of the selected elements.
If textContentMode = true
, each elements textContent
property is set to an empty String
(generally faster).
If textContentMode = false
, each elements innerHTML
property is set to an empty String
instead.
If retainText = true
, direct child TextNodes
and comments will be retained. In this case textContentMode
will be
ignored.
User interactions
e().focus()
Focus the first selected element.
e().bind(event, callback, whileCapture = false)
Attach an event handler to the selected elements.
e('button').bind('click', function (event) {
alert('button clicked')
});
e().trigger(event)
Trigger an event on the selected elements.
Use an instance of Event
, or a String
to create a new Event(event)
with as parameter.
Static methods
These can be used independently of eric
instances.
e.forEach(elements, callback, thisArg = undefined)
[static] Call a function for each element of a given array.
Signature of callback
: function(element, index, array)
e.isNode(o)
[static] Check if
o
actually is an instance ofNode
. Returns boolean.
e.isElement(o)
[static] Check if
o
actually is an instance ofElement
. Returns boolean.
e.isHTMLElement(o)
[static] Check if
o
actually is an instance ofHTMLElement
. Returns boolean.
e.mix(controller, mix)
[static] Add all properties of
mix
as properties tocontroller
.
e.listElements(elements = [])
[static] Create an array from a given
HTMLCollection
,NodeList
,Array
orNode
.
e.emptyNode()
[static] Create an empty
TextNode
.
e.create(tag)
[static] Create an
eric
instance with an element.
Uses document.createElement(tag)
.