@zkochan/pnpm
Version:
A fast implementation of npm install
172 lines (111 loc) • 4.38 kB
Markdown
# onmount
**Run something when a DOM element appears and when it exits.**<br>
No dependencies. Legacy IE compatible. 1kb .min.gz.
[](https://travis-ci.org/rstacruz/onmount "See test builds")
<br>
## Overview
**Detecting elements:**
Run something to initialize an element on its first appearance.
```js
onmount = require('onmount')
onmount('.push-button', function () {
$(this).on('click', function () {
alert('working...')
})
})
```
**Polling for changes:**
Call `$.onmount()` everytime your code changes.
[(more...)](/docs/idempotency.md)
[(automatic?)](/docs/automatic-observation.md)
```js
$('<button class="push-button">Do something</button>')
.appendTo('body')
$.onmount()
$(".push-button").click() //=> 'working...'
```
**jQuery integration:**
jQuery is optional; use it to poll on popular events. [(more...)](/docs/idempotency.md)
```js
$(document).on('ready show.bs closed.bs load page:change', function () {
$.onmount()
})
```
**Cleanups:**
Supply a 2nd function to *onmount()* to execute something when the node is first detached.
[(more...)](/docs/cleanup.md)
```js
$.onmount('.push-button', function () {
/*...*/
}, function () {
alert('button was removed')
})
document.body.innerHTML = ''
$.onmount() //=> 'button was removed'
```
<br>
## What for?
Onmount is a safe, reliable, idempotent, and testable way to attach JavaScript behaviors to DOM nodes. It's great for common websites that are not Single-Page Apps. Read:
- [Premise](/docs/premise.md)
- [rsjs][rsjs] (Reasonable System for JavaScript Structure)
<br>
## Usage
```
npm install onmount
bower install onmount
```
```js
// With CommonJS/AMD (ie, Browserify):
onmount = require('onmount')
// with no module loaders:
window.onmount
// with jQuery:
$.onmount
```
[Bootstrap events]: http://getbootstrap.com/javascript/
[Turbolinks load]: https://github.com/rails/turbolinks#events
[idempotent]: https://en.wiktionary.org/wiki/idempotent
[Browserify]: http://browserify.org/
<br>
## API
* `onmount()`
> Runs all behaviors.
>
> When used with jQuery, this can be passed as an event handler, eg, `$(onmount)` or `$(document).on('load', onmount)`.
* `onmount(selector)`
> Runs all behaviors registered for `selector`.
* `onmount(selector, init())`
> Registers a behavior for `selector` to run the callback `init()`.
* `onmount(selector, init(b), exit(b))`
> Registers a behavior for `selector` to run the callback `init()`. The `exit()` callback will be called once the behavior is triggered again but the element is no longer attached to the DOM.
>
> The callbacks are passed an object `b`, and the same object is passed for both `init` and `exit`. This allows them to communicate and keep aware of state.
>
> An ID is also provided, `b.id`, which is guaranteed unique for every behavior-element pair.
* `onmount.reset()`
> Clears all defined behaviors. Useful for tests.
* `onmount.observe()`
> Automatically invoke when new DOM elements appear using MutationObserver API. Returns `true` if it succeeds.
* `onmount.unobserve()`
> Turns off observation previously turned on via `onmount.observe()`.
* `onmount.debug`
> Set this to `true` to see debug messages.
<br>
## Browser compatibility
All modern browsers and IE8+. For legacy IE, use it with jQuery 1.x.
Try the [test suite](https://rawgit.com/rstacruz/onmount/master/test/index.html) in your browser. Try it [with jQuery 1.x](https://rawgit.com/rstacruz/onmount/master/test/jquery.html) for legacy browsers.
<br>
## Read more
* [Read documentation →](http://ricostacruz.com/onmount/)
* [See examples →](https://github.com/rstacruz/onmount/examples)
<br>
## Thanks
**onmount** © 2015+, Rico Sta. Cruz. Released under the [MIT] License.<br>
Authored and maintained by Rico Sta. Cruz with help from contributors ([list][contributors]).
> [ricostacruz.com](http://ricostacruz.com) ·
> GitHub [@rstacruz](https://github.com/rstacruz) ·
> Twitter [@rstacruz](https://twitter.com/rstacruz)
[MIT]: http://mit-license.org/
[contributors]: http://github.com/rstacruz/onmount/contributors
[rsjs]: https://github.com/rstacruz/rsjs
[](http://git.io/col)