Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/kylebarrow/chibi

A tiny JavaScript micro-library
https://github.com/kylebarrow/chibi
Last synced: 12 days ago
JSON representation
A tiny JavaScript micro-library
Host: GitHub
URL: https://github.com/kylebarrow/chibi
Owner: kylebarrow
Created: 2012-06-25T06:30:21.000Z (over 12 years ago)
Default Branch: master
Last Pushed: 2020-11-13T15:36:17.000Z (about 4 years ago)
Last Synced: 2024-11-01T06:12:31.296Z (13 days ago)
Language: JavaScript
Homepage:
Size: 129 KB
Stars: 573
Watchers: 28
Forks: 50
Open Issues: 7
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

README

        # Chibi v3.0.9

#### A tiny JavaScript micro-library

Think it's OK to serve up 30KB over 3G just to manipulate a couple of DOM elements? Of course you don't because that's an asshat move and you're no asshat. You'll probably instead use a couple of lines of vanilla JavaScript, perhaps a little CSS `:active` with transitions, all while riding a unicorn bareback through a double rainbow, no hands.

Working on something a wee bit more complex? Unlike fat, grown-up frameworks and libraries, Chibi focuses on just the essentials, melted down and mixed with optimisation rainbows to create a really light micro-library that allows you to do awesome things, asshatory free.

### The sweet, juicy bits

* Chibi is really tiny: 7KB minified, 3KB gzipped, small enough to stick inline on single page web apps, saving an extra HTTP request.

* Supports modern desktop and mobile browsers including Chrome, Firefox, Internet Explorer, Opera and Safari (see Browser Support below).

* Even supports creaky old browsers like IE6, I don't know why you would do this.

* No animation cruft, instead use CSS transitions like a nice person.

* In modern browsers, Chibi typically executes DOM manipulation 20% to 50% faster than grown-up libraries.

### The lumpy, chewy bits

* Chibi'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 IE6. Fortunately modern browser don't need this polyfill.

* Ancient browsers that support neither `document.querySelectorAll()` nor `window.getComputedStyle` can bugger off.

**Version 3 is a major update with many breaking changes. If it's difficult to embrace change, version 1 is still available [here](https://github.com/kylebarrow/chibi/tree/1.1.5).**

### Browser Support

Chibi has been tested with and supports the following browsers:

* Android Browser 2.1 or higher

* Blackberry Browser 6 or higher

* Chrome

* Chrome Android

* Firefox 3.5 or higher

* Firefox Mobile

* Internet Explorer 6 or higher

* Internet Explorer Mobile 9 or higher

* Opera 10 or higher

* Opera Mini

* Opera Mobile 10 or higher

* Safari 3.2 or higher

* Safari Mobile 3.2 or higher

* Symbian^3 Browser or higher

Chibi should also work with any other browser that supports `document.querySelectorAll()`.

### Installation

Grab it from [here](https://github.com/kylebarrow/chibi/) or

```shell

npm install chibijs

```

### Using Chibi

Chibi syntax is similar to that pioneered by jQuery: `$(selector).method()`. It intentionally uses the same `$` namespace as jQuery because micro-libraries and grown-up libraries should never mix.

Chibi'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

Chibi 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, Chibi will return the selected option value string, if any. For select lists with multiple selects, Chibi 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 Chibi 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 Chibi 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/kylebarrow/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/kylebarrow/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/kylebarrow/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/kylebarrow/repos','GET',function(data,status){

		// Do awesome

	});

```

### Modify, build, contribute

```shell

npm install

gulp

```

##### FIN