blue-js v3.0.2

blue-js

blue-js is a super lightweight commonjs javascript dom & events library

This library is developed and maintained internally at bluegrassdigital

Installation

npm install blue-js

Upgrading from V2

The top level module exports dom , events and ps are gone, all methods are exported directly from the root module, muvh like lodash.

The pubsub implementation ps has been removed as it was somewhat outside the scope of this library - please use something like https://github.com/developit/mitt instead.

API

blue

A collection of dom utility functions

• blue
  • .addClass(el, cls)
  • .each(els, fn)
  • .filter(els, fn) ⇒ Array
  • .getWindowDimensions([w], [d]) ⇒ windowDimensions
  • .hasClass(el, cls)
  • .isHidden(el) ⇒ Boolean
  • .isVisible(el) ⇒ Boolean
  • .onReady(fn)
  • .removeClass(el, cls)
  • .toggleClass(el, cls)
  • .wrap(el, argument1, [argument2])
  • .listen(el, names, fn, capture) ⇒ Object
  • .listenCollection(els, names, fn, capture)
  • .removeListeners(els, names)
  • .trigger(el, name, [data], [eventProps])
  • static
    • .windowDimensions : Object

blue.addClass(el, cls)

Add a class to an element

blue.each(els, fn)

Iterate over a dom NodeList

blue.filter(els, fn) ⇒ Array

Filters a dom NodeList, returning an array of only those elements which match the predicate function

Returns: Array - A filtered array of dom elements

Example
Filter only foo links with class 'bar':

import { filter } from 'blue-js'

const fooLinks = document.querySelectorAll('a.foo')
const filteredLinks = filter(fooLinks, el => dom.hasClass(el, 'bar'))

Filter only visible filteredLinks:

import { filter } from 'blue-js'

const fooLinks = document.querySelectorAll('a.foo')
const newFilteredLinks = filter(filteredLinks, dom.isVisible)

blue.getWindowDimensions(w, d) ⇒ windowDimensions

Cross browser funtion for getting the dimensions of the window

Returns: windowDimensions - The window dimensions

blue.hasClass(el, cls)

Check if an element has a class

blue.isHidden(el) ⇒ Boolean

Check whether an element is hidden

Returns: Boolean - True if el is visibly hidden, otherwise false

blue.isVisible(el) ⇒ Boolean

Check whether an element is visible

Returns: Boolean - True if el is visible, otherwise false

blue.onReady(fn)

A callback that fires when the document is ready - roughly equaivalent to jQuery document ready

blue.removeClass(el, cls)

Remove a class from an element

blue.toggleClass(el, cls)

Toggle a class on an element

blue.wrap(el, argument1, argument2)

Wrap an html element with another element or with a wrap function

Example
Using a wrapper function:

import { wrap } from 'blue-js'

const foo = document.querySelector('#foo')
wrap(foo, html => `<div class="wrapper">${html}</div>`)

Example
Using an html element:

import { wrap } from 'blue-js'

const foo = document.querySelector('#foo')
const wrapper = document.createElement('div')
wrap(foo, wrapper)

Example
Using two strings:

import { wrap } from 'blue-js'

const foo = document.querySelector('#foo')
wrap(foo, '<div class="wrapper">', '</div>')

blue.listen(el, names, fn, capture) ⇒ Object

Listen for one or more events (custom or standard)

Returns: Object - An object with a remove method to remove the listener later

Example
Add a listener:

import { listen } from 'blue-js'

const fooLink = document.querySelector('a.foo')

listen(fooLink, 'click', (event) => {
  event.preventDefault()
  const { target } = event
  target.classlist.add('.is-clicked')
})

Example
Remove listener later:

import { listen } from 'blue-js'

const fooLink = document.querySelector('a.foo')

const listener = listen(fooLink, 'click', (event) => {
  event.preventDefault()
  const { target } = event
  target.classlist.add('.is-clicked')
})
//Some time later
listener.remove()

Example
Remove listener immediately:

import { listen } from 'blue-js'

const fooLink = document.querySelector('a.foo')

const listener = listen(fooLink, 'click', (event) => {
  event.preventDefault()
  const { target } = event
  target.classlist.add('.is-clicked')
  listener.remove()
})

blue.listenCollection(els, names, fn, capture)

Same as events.listen, excpet for NodeList rather than a single Element

blue.removeListeners(els, names)

Remove one or more events from one or more targets

Example

import { removeListeners } from 'blue-js'

const fooLinks = document.querySelectorAll('a.foo')
removeListeners(fooLinks, 'click mouseenter')

blue.trigger(el, name, data, eventProps)

Trigger any event on a dom element, optionally pass data

Example

import { listen, trigger } from 'blue-js'

const fooLink = document.querySelector('a.foo')
trigger(fooLink, 'Link:Event', { foo: 'bar' })

// Listen for custom event and use the custom data passed to trigger
listen(fooLink, 'Link:Event', event => {
  console.log(event.detail.foo) // -> 'bar'
})

blue.windowDimensions : Object

Kind: static typedef of blue
Properties

Contributing to blue-js

Standard JS applies

camelCase for function and variable names

Github Flow - branch, submit pull requests

Getting set up

• Pull the repo
• run npm install
• run npm start to run all unit tests, lint the codebase, and build the API docs

Contribute

First off, thanks for taking the time to contribute! Now, take a moment to be sure your contributions make sense to everyone else.

Reporting Issues

Found a problem? Want a new feature? First of all see if your issue or idea has already been reported. If it hasn't, just open a new clear and descriptive issue.

Submitting pull requests

Pull requests are the greatest contributions, so be sure they are focused in scope, and do avoid unrelated commits.

• Fork it!
• Clone your fork: git clone https://github.com/<your-username>/blue-js
• Navigate to the newly cloned directory: cd blue-js
• Create a new branch for the new feature: git checkout -b my-new-feature
• Install the tools necessary for development: npm install
• Make your changes.
• npm test to make sure your change doesn't break anything.
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request with full remarks documenting your changes.