https://github.com/virtuallycreative/aresdom

A micro JS library for DOM manipulation and more!
https://github.com/virtuallycreative/aresdom
Last synced: 10 months ago
JSON representation
A micro JS library for DOM manipulation and more!
Host: GitHub
URL: https://github.com/virtuallycreative/aresdom
Owner: VirtuallyCreative
License: mit
Created: 2019-03-29T20:08:31.000Z (about 7 years ago)
Default Branch: master
Last Pushed: 2024-10-22T05:29:43.000Z (over 1 year ago)
Last Synced: 2024-10-23T07:52:42.266Z (over 1 year ago)
Language: JavaScript
Homepage: https://docs.virtuallycreative.ca/aresdom/
Size: 123 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 6
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

          # aresDOM v0.1

#### A tiny micro-lib

I really dislike bloated frameworks that try to either "do it all" or provide so much overhead to do the smallest of things that aresDOM was created to handle just this type of niche use-case.

It's my personal swiss-army knife using the best framework of all, [VanillaJS](http://vanilla-js.com) and it's helped me on many projects over the years.

### What's the Deal

* Lightweight & Customizable. Just ~3KB (minified + gzipped).

* Uses jQuery-style syntax for familiarity!

* Supports method chaining too.

* Great for quick wireframing/prototyping.

* Depends on my favourite framework, VanillaJS.

### The Nitty-Gritty

* aresDOM's polyfill for `document.querySelectorAll()` is limited to browser CSS support and is not as fast as some dedicated selector engines. This means no `input[type=text]` or `p:nth-child(even)` selectors with ancient browsers (looking at you, IE6...).

Fortunately modern browser don't need this polyfill. This is because under the hood aresDOM relies a lot on `document.querySelectorAll()` and `window.getComputedStyle` so try to avoid legacy browsers that don't support this otherwise you're gonna have a bad time.

### Browser Support

aresDOM has been tested with and supports the following browsers:

* Android Browser 2.1 or higher

* Blackberry Browser 6 or higher

* Blisk v10.x

* Chrome

* Chrome Android

* Firefox 3.5 or higher

* Firefox Mobile

* Internet Explorer 8 or higher

* Opera 10 or higher

* Opera Touch

* Vivaldi 2.x

aresDOM, in theory, should also work with any other browser that supports `document.querySelectorAll()`.

### Installation

Grab the latest release [here](https://github.com/vip3rousmango/aresDOM/) or

```sh

yarn add aresDOM

```

### Modify, build, contribute

```sh

yarn

npm run start

```

### Using aresDOM

aresDOM syntax is as close to jQuery as possible: `$(selector).method()`. 

It intentionally uses the same `$` namespace as jQuery because micro-libraries and robust libraries shouldn't mingle.

aresDOM's supports standard CSS selectors but you can also pass in DOM elements directly:

##### CSS selector

```js

$("p") // Returns an array of all paragraph elements

$("p").hide() // Hides all paragraphs

$("#foo").show() // Shows element with id equal to "foo"

$(".foo").hide() // Hides elements with "foo" CSS class

```

##### A DOM element selector, pointless

```js

$(document.getElementsByTagName('p')).hide() // Hides all paragraphs

```

##### A more interesting DOM element selector

```js

$($('p')[0]).hide() // Hides first paragraph

```

### Methods

aresDOM supports method chaining `$(selector).method().anothermethod().evenmoremethods()` of any method not returning a value (string, boolean, etc.).

#### $().ready(handler)

*Fires handler when the DOM is ready.*

Use to fire a function when the DOM is ready. Including a selector makes no sense for this method, don't do it.

```js

$().ready(function(){

	// Do awesome

});

```

or perhaps

```js

function foo() {

	// Do awesome

}

$().ready(foo);

```

#### $().loaded(handler)

*Fires handler when the page is loaded.*

Use to fire a function when the page is loaded. Including a selector makes no sense for this method, don't do it.

```js

function foo() {

	// Do awesome

}

$().loaded(foo);

```

#### $(selector).each(function)

*Executes a function on each matching element*

**each** passes each matching element to the specified function.

```html

Foo

Bar


	function foo(elm) {

		elm.style.color = "red";

	}

    $('p').each(foo); // Executes the foo function (sets the element style color to red) on all paragraph elements

    

    // An alternative way to achieve the above

    $('p').each(function(elm) {

		$(elm).css('color','red');  

    })

    

    

```

#### $(selector).first()

*Finds the first matching element.*

**first** will return an array containing the first matching element, useful when working with crappy browsers like IE6 with weak CSS pseudo support, especially when combined with method chaining.

#### $(selector).last()

*Finds the last matching element.*

**last** will return an array containing the last matching element.

#### $(selector).odd()

*Finds matching odd elements.*

**odd** will return an array containing matching odd elements.

#### $(selector).even()

*Finds matching even elements.*

**even** will return an array containing matching even elements.

```html

Foo

Bar

Foo

Bar


    $('p').first(); // returns an array containing the first paragraph element

    $('p').last(); // returns an array containing the fourth paragraph element

    $('p').odd(); // returns an array of odd paragraph elements

    $('p').even(); // returns an array of even paragraph elements

```

#### $(selector).hide()

*Hides matching elements.*

```html

Foo

Bar


	$('p').hide(); // hides all paragraph elements

```

#### $(selector).show()

*Shows matching elements.*

```html

p {display:none}

Foo

Bar


	$('p').show(); // shows all paragraph elements

```

#### $(selector).toggle()

*Toggles visibility of matching elements.*

```html

Foo

Bar


	$('p').toggle(); // shows the second paragraph element, hides the first paragraph element

```

#### $(selector).remove()

*Removes matching elements from the DOM tree.*

```html

Foo

Bar


	$('p').remove(); // removes all the paragraph elements from the DOM tree

```

#### $(selector).css(property, value)

*Gets or optionally sets the CSS property for matching elements.*

**css** with no *value* will return the CSS property string of the first matching element found. **css** will return the computed property value if the property isn't explicitly set which can vary between browsers. For example, an element with no explicit font weight will return 'normal' in Opera and Webkit browsers but '400' in Firefox and Internet Explorer browsers.

*value* will set the value of the CSS property for all matching elements.

```html

.bold {font-weight:900}

Foo

Bar


	$('p').css('font-weight'); // returns the "font-weight" of the first paragraph element

	$('p').css('color','red'); // sets all paragraph elements color to red

```

#### $(selector).getClass()

*Gets class for first matching element found.*

```html

.bold {font-weight:900}

.red {color:red}

.mono {font-family:monospace}

Foo

Bar

Foo

Bar


	$('div').getClass(); // returns 'red', the class of the first div element

	$('p').getClass(); // returns undefined as the first paragraph element has no class set

```

#### $(selector).setClass(class)

*Sets the class of all matching elements replacing any existing element class with this class.*

```html

.bold {font-weight:900}

.red {color:red}

.mono {font-family:monospace}

Foo

Bar


	$('p').setClass('red bold'); // sets the class to "red" and "bold" for all paragraph elements

```

#### $(selector).addClass(class)

*Adds a class to all matching elements.*

```html

.bold {font-weight:900}

.red {color:red}

.mono {font-family:monospace}

Foo

Bar


	$('p').addClass('mono'); // adds the "mono" class to all paragraph elements

```

#### $(selector).removeClass(class)

*Removes class from all matching elements.*

```html

.bold {font-weight:900}

.red {color:red}

.mono {font-family:monospace}

Foo

Bar


	$('p').removeClass('mono'); // removes the "mono" class from all paragraph elements

```

#### $(selector).toggleClass(class)

*Toggles class for matching elements.*

```html

.bold {font-weight:900}

.red {color:red}

.mono {font-family:monospace}

Foo

Bar


	$('p').toggleClass('mono'); // toggles the mono class on all paragraph elements

```

#### $(selector).hasClass(class)

*Returns true if first matching element found includes the class.*

```html

.bold {font-weight:900}

.red {color:red}

.mono {font-family:monospace}

Foo

Bar

Foo

Bar


	$('div').cls('red'); // returns true as the first div element includes the 'red' class

	$('p').cls('mono'); // returns undefined as the first paragraph element doesn't include the 'mono' class

```

#### $(selector).html(html)

*Gets or optionally sets the inner HTML of matching elements.*

**html** with no arguments will return the HTML string of the first matching element found.

If the *html* argument is specified, this will replace the inner HTML of all matching elements.

```html

Foo

Bar


	$('p').html(); // returns an inner HTML "Foo" of the first paragraph element

	$('p').html('<i>Foobar</i>'); // Sets the inner HTML of all paragraph elements to "<i>Foobar</i>"

```

#### $(selector).htmlBefore(value)

*Inserts html before all matching elements.*

```html

Foo

Bar


	$('p').htmlBefore('<i>Foobar</i>'); // Inserts "<i>Foobar</i>" before all paragraph elements

```

#### $(selector).htmlAfter(value)

*Inserts html after all matching elements.*

```html

Foo

Bar


	$('p').htmlAfter('<i>Foobar</i>'); // Inserts "<i>Foobar</i>" after all paragraph elements

```

#### $(selector).htmlAppend(value)

*Inserts html after all matching elements inner elements.*

```html

Foo

Bar


	$('p').htmlAppend('<i>Foobar</i>'); // Inserts "<i>Foobar</i>" after all paragraph child elements

```

#### $(selector).htmlPrepend(value)

*Inserts html before all matching elements inner elements.*

```html

Foo

Bar


	$('p').htmlPrepend('<i>Foobar</i>'); // Inserts "<i>Foobar</i>" before all paragraph child elements

```

#### $(selector).attr(property, value)

*Gets or optionally sets the property for all matching elements.*

**attr** with no value argument will return the property string of the first matching element found.

*value* will set the value of the property for all matching elements.

```html

Foobar


	$('a').attr('href'); // returns the "href" property value "http://en.wikipedia.org/wiki/Foobar" of the first link element

	$('a').attr('target','_blank'); // sets the "target" property for all link elements to "_blank"

```

#### $(selector).data(key, value)

*Gets or optionally sets the data key value for all matching elements.*

**data** with no *value* argument will return the data key value of the first matching element found.

*value* will set the value of the data key for all matching elements.

```html





	$('p').data('test'); // returns "foo" for data key "test" of first paragraph element found

	$('p').data('test','foobar'); // sets the date key "test" value to "foobar" on all matching paragraph elements

```

#### $(selector).val(value)

*Gets or optionally sets the value of matching form elements.*

**val** with no arguments will return the value string of the first matching form element found. For select lists, aresDOM will return the selected option value string, if any. For select lists with multiple selects, aresDOM will return an array of selected option value strings, if any.

*value* will set the value of matching form field elements. For select lists, this will select the option matching this value. For select lists with multiple selects, passing an array of values will select all options in the select list matching these values.

```html

	Foo

	Bar

	$('input').val(); // returns "Foobar"

	$('input').val('Foo Bar'); // sets the value for all input elements to "Foo Bar"

	$('select').val(); // returns "bar", the selected option value 

	$('select').val('foo'); // selects the option matching "foo"

	$('select').val(['foo','bar']); // selects the options matching "foo" or "bar" values

```

#### $(selector).checked(boolean)

*Gets or optionally sets checked status of checkbox or radio elements.*

**checked** with no arguments will return the checked boolean of the first matching element found.

*boolean* will set the checked status of matching checkbox or radio elements.

```html

	$('input').checked(true); // checks the checkbox

	$('input').checked(); // returns true

	$('input').checked(false); // unchecks the checkbox

	$('input').checked(); // returns false

```

#### $(selector).on(event, listener)

*Adds an event listener to all matching elements.*

**on** adds an event listener to all matching elements. There is no need to use the HTML event format ('on' + event) as aresDOM will automatically prefix the event as required. **on** also supports passing `window` and `document` as the selector.

```html

Foo

Bar


	function foo() {

		// Do awesome

	}

	$('p').on('click',foo); // adds the 'foo' click event listener to all paragraphs

```

#### $(selector).off(event, listener)

*Removed an event listener from all matching elements.*

**off** removed an event listener from all matching elements. There is no need to use the HTML event format ('off' + event) as aresDOM will automatically prefix the event as required. **off** also supports passing `window` and `document` as the selector.

```html

Foo

Bar


	function foo() {

		// Do awesome

	}

	$('p').on('click',foo); // adds the 'foo' click event listener to all paragraph elements

	$('p').off('click',foo); // removes the 'foo' click event listener from all paragraph elements

```

#### $(selector).get(url, callback, nocache, nojsonp)

*Sends a GET AJAX request, optionally firing a callback with the XHR `responseText` and `status`. Alias of $(selector).ajax with GET method*

When *nocache* is true, a `_ts` time stamp is added to the URL to prevent caching, yes, I'm looking at you Android Browser and iOS 6.

**get** supports JSON as a selector ({name:value}), useful for when you want to send data without using form elements.

For cross-domain requests, **get** uses JSONP by default but this is overridden when *nojsonp* is true. JSONP requests will apply any *callback* to `callback=?` or similar in the **get** url.

```html

	// XHR all form data using "GET" to "ajax.html"

	$('form').get('ajax.html');

	// XHR the JSON using "GET" to "ajax.html"

	$({text:'Foo Bar'}).get('ajax.html');

```

```html

	// JSONP

	$().get('https://api.github.com/users/vip3rousmango/repos?sort=created&direction=asc&callback=?',function(data,status){

		// Do awesome

	});

	// JSONP with JSON query

	$({sort: "created", direction: "asc", callback: "?"}).get('https://api.github.com/users/vip3rousmango/repos',function(data,status){

		// Do awesome

	});

```

#### $(selector).post(url, callback, nocache)

*Sends a POST AJAX request, optionally firing a callback with the XHR `responseText` and `status`. Alias of $(selector).ajax with POST method*

When *nocache* is true, a `_ts` time stamp is added to the URL to prevent caching.

**post** supports JSON as a selector ({name:value}), useful for when you want to send data without using form elements.

```html

	// XHR the JSON using "POST" to "ajax.html"

	$({text:'Foo Bar'}).post('ajax.html');	

	

	// XHR all form data using "POST" to "ajax.html", returns responseText and status, adds a cache busting time stamp

	$('form').post('ajax.html',function(data,status){

		// Do awesome

	},true);

```

#### $(selector).ajax(url, method, callback, nocache, nojsonp)

*Sends an AJAX request, optionally firing a callback with the XHR `responseText` and `status`*

**ajax** uses the GET method if none is specified. When *nocache* is true, a `_ts` time stamp is added to the URL to prevent caching.

**ajax** supports JSON as a selector ({name:value}), useful for when you want to send data without using form elements.

For cross-domain requests, **ajax** uses JSONP by default but this is overridden when *nojsonp* is true. JSONP requests will apply any *callback* to `callback=?` or similar in the **ajax** url. The *method* is obviously always `GET` for JSONP requests.

```html

	// XHR all form data using "GET" to "ajax.html"

	$('form').ajax('ajax.html');

	// XHR the JSON using "GET" to "ajax.html"

	$({text:'Foo Bar'}).ajax('ajax.html');

	// XHR all form data using "POST" to "ajax.html", returns responseText and status, adds a cache busting time stamp

	$('form').ajax('ajax.html',"POST",function(data,status){

		// Do awesome

	},true);

```

```html

	// JSONP

	$().ajax('https://api.github.com/users/vip3rousmango/repos?sort=created&direction=asc&callback=?','GET',function(data,status){

		// Do awesome

	});

	// JSONP with JSON query

	$({sort: "created", direction: "asc", callback: "?"}).ajax('https://api.github.com/users/vip3rousmango/repos','GET',function(data,status){

		// Do awesome

	});

```
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/virtuallycreative/aresdom

Awesome Lists containing this project

README
