A simple, backbone inspired view helper.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci
__tests__
bin
src
.gitignore
.npmignore
CHANGELOG.md
LICENSE.md
README.md
package.json
washi.js
webpack.config.js
yarn.lock

README.md

washi

A small (2.2kb gzipped), Backbone-inspired, library for greater organization on small projects.

  1. Installation
  2. Basic Usage
  3. API

Installation

package.json

Washi is available on npm:

npm install --save washi

global

If npm isn't your thing, or you'd rather include Washi as vendor code, download it from the unpkg CDN:

https://unpkg.com/washi

This is a UMD module. It should interop perfectly with CommonJS and AMD, or otherwise as a global by accessing Washi.

Basic usage

var Washi = require('washi');
var $     = Washi.$;

var Sample = {
  ui: {
    title: '.title',
  },
  events: {
    // Use ui helper selectors as aliases with {element}
    'mousedown {title}, touchstart {title}' : 'doSomething',

    // Alternatively, follow the syntax used by Backbone.Marionette
    'click @ui.title': 'doSomethingElse'
  },
  initialize: function(options) {
    this.ui.title.forEach(function(e) {
      e.innerHTML = 'Washi is for Origami'
    });
  },
  doSomething: function() {
    var text = $.map(this.ui.title, el => el.innerHTML).join(' ')
    console.log(text)
  },
  doSomethingElse: function() {
    console.log("Something else")
  }
}

var sample = Washi(Sample, {
    el: "#sample-el"
})

Corresponding with:

<div id="sample">
  <h1 class="title">Paper Crane</h1>
</div>

API

  1. Washi Components
  2. Washi Utilities

Washi Components

Create a view component based upon a configuration:

let Sample = {
  ui: {
    title: '.title',
  },
  events: {
    'click @ui.title': 'doSomething'
  },
  initialize: function(options) {
    // Startup
    console.log("Hello, world!")
  },
  doSomething: function() {
    alert("click!")
  }
}

let sample = Washi(Sample, {
  el: "#sample-el"
})

initialize(options: Object)

Invoked after the Washi instance has been created. Use this method for setup behavior.

let Widget = {
  initialize: function(options) {
    console.log('all set!')
  }
}

let component = Washi(Widget, { el: document.body }) // "all set!"

events: Object

Attach event listeners to the element associated with the component. Keys in this object are selectors, values are string references to methods on the configuration object:

let Widget = {
  events: {
    'click button': 'onClick'
  },

  onClick: function(event) {
    alert("HELLO!")
  }
}

let component = Washi(Widget, { el: '.selector' })

component.query('button').invoke('click') // "HELLO!"

ui: Object

Preselect child nodes within the element provided to Washi. These selections are available in a few places.

As aliases to their underlying selectors in the events object

In the events object, @ui.{name} is replaced with the CSS selector for the UI entry:

let Widget = {
  ui: {
    'button': 'button'
  },
  events: {
    'click @ui.button': 'onClick'
  },
  onClick: function(event) {
    alert("HELLO!")
  }
}
As entries in this.ui

Reference the selected elements associated with a ui entry under this.ui:

let Widget = {
  ui: {
    'button': 'button'
  },
  initialize: function() {
    // An array of DOM elements
    this.ui.button.forEach(el => el.click())
    // Alternatively, a Washi chain
    this.ui.$button.invoke('click')
  }
}

Washi Utilities

Washi exposes a number of utility methods under the $ namespace:

  1. chain
  2. Array operations
  3. toArray
  4. extend
  5. has
  6. query
  7. queryAll
  8. invoke
  9. isBlank
  10. isDOM
  11. isFunction
  12. isObject
  13. isRegExp
  14. isString
  15. isUndefined
  16. matches
  17. on
  18. off
  19. result
  20. tap
  21. template
  22. append
  23. remove
  24. addClass
  25. removeClass
  26. toggleClass

chain(target: Object | Array)

Creates a pipeline for executing multiple operatins on a value, this can be a single object or a list of values. Use valueOf() to end the chain, returning the underlying value:

const $ = Washi.$

let chain = $.chain([1,2,3]).map(i => i + 1)
let result = chain.valueOf()

console.log(result) // [2,3,4]

Passing a string to Washi.$ executes document.querySelectorAll, converting the selection into a chain:

const $ = Washi.$

$('button').on('click', () => {
  alert("HI!")
})

Array operations

Washi.$ includes most ES5 methods from the Array prototype. The primary benefit of doing this is to work around DOM APIs that return "array like" values such as NodeList:

You can use these directly, however they are primary intended for use with chaining:

const $ = Washi.$

let internalLinks = $('a').filter(el => el.href.origin === window.location.origin)

internalLinks.on('click', () => console.log("Retention! Hurrah!"))

toArray(list: Enumerable)

Convert a list-like value, such as a NodeList returned from document.querySelectorAll into an array:

const $ = Washi.$

let links = document.querySelectorAll('a')
let hrefs = $.toArray(links).map(el => el.href)

extend(target: Object, ...others)

Given a list of arguments, extend a target object with additional properties:

const $ = Washi.$

let red = { r: 200, g: 0, b: 0 }
let blue = { r: 0, g: 0, b: 220 }

let purple = $.extend({}, red, blue) // { r: 200, g: 0, b: 200 }

Important: the first argument, target, is mutated. This is a destructive operation!

has(target: Object, property: String)

Returns true if a given object has a property. This is sugar around Object.prototype.hasOwnProperty that covers some edge cases, such as null or undefined values.

const $ = Washi.$

let styles = { color: 'blue', font: '14px Helvetica' }

$.has(styles, 'color')  // true
$.has(styles, 'border') // false

query(selector: String, root: HTMLElement = document)

Select an HTML element. When no second argument is given, selection occurs on the document. When no element is found, it returns null.

const $ = Washi.$

let btn = $.query('button')

if (btn) {
  btn.click()
}

queryAll(selector: String)

Select multiple HTML elements. The resulting selection is converted into an Array, making its safe to perform operations like forEach, map, and reduce. When no element is found, it returns an empty array.

const $ = Washi.$

let items = $('ul').queryAll('li')

items.forEach(el => console.log(item.innerHTML))

invoke(list: Array, method: String, ...arguments: any[])

Execute a method on each member of a list:

const $ = Washi.$

// Operate on data
let planets = ['Mercury', 'Venus', 'Earth', 'Mars']
$.invoke(planets, 'toUpperCase') // ['MERCURY', 'VENUS', 'EARTH', 'MARS']

// Or call methods on a list of elements
$('button').invoke('click')

isBlank(value: any)

Is a value null or undefined?

const $ = Washi.$

$.isBlank('')         // false
$.isBlank(false)      // false
$.isBlank(0)          // false
$.isBlank(null)       // true
$.isBlank(undefined)  // true

isDOM(value: any)

Is a value a DOM element?

const $ = Washi.$

$.isDOM({})          // false
$.isDOM(new Image()) // true

isFunction(value: any)

Is a value a function?

const $ = Washi.$

$.isFunction({})            // false
$.isFunction(function() {}) // true

isObject(value: any)

Is a value an object? This function helps to avoid pitfalls with type checking objects. For example: typeof null === 'object'!

const $ = Washi.$

$.isObject({})            // true
$.isObject([])            // true
$.isObject(null)          // false
$.isObject(function() {}) // false

isRegExp(value: any)

Is a value a regular expression?

const $ = Washi.$

$.isRegExp({})                  // false
$.isRegExp(/[A-Z]/)             // true
$.isRegExp(new RegExp("[A-Z]")) // true

isString(value: any)

Is a value a string?

const $ = Washi.$

$.isString({})            // false
$.isString("Hello world") // true

isUndefined(value: any)

Is a value undefined?

const $ = Washi.$

$.isUndefined(null)      // false
$.isUndefined('')        // false
$.isUndefined(0)         // false
$.isUndefined(undefined) // true

matches(el: Element, selector: String)

Returns true if the provided element matches a CSS selector. When possible, this function uses the Element.matches DOM API.

const $ = Washi.$

$.matches(document.body, '.class-name')

on(el: Element, event: String, callback: Function, capture: boolean)

Safely attach an event listener with extreme browser support (IE5+).

const $ = Washi.$

$.on(document.body, 'click', event => alert("CLICK!"))

// Or chain it:
$('button').on('click', event => alert("CLICK!"))

For more information about event listening, see EventTarget.addEventListener

off(el: Element, event: String, callback: Function, capture: boolean)

Safely remove an event listener with extreme browser support (IE5+).

const $ = Washi.$

let buttons = $('button')
let handler = event => alert("CLICK!")

buttons.on('click', handler)
buttons.invoke('click') // CLICK! CLICK! CLICK!

buttons.off('click', handler)
buttons.invoke('click') // silence

result(target: any, property: String, fallback: any)

Check for ownership of a value, optionally calling it if it is a function. If the value is undefined, return the fallback value.

const $ = Washi.$

$.result({}, 'method', 'missing') // 'missing'
$.result('foobar', 'toUpperCase', 'UNKNOWN') // 'FOOBAR'

tap(target: any, fn: Function, scope: any)

Calls a function at a given scope, passing in the target value as the only argument. This is primarily intended side-effects when chaining:

const $ = Washi.$

function render(items) {
  let p = document.createElement('p')

  p.innerHTML = items.join(', ')

  document.body.appendChild(p)
}

let dates = $([new Date('01-01-2000'), new Date('02-02-2010'])

template(target: any, fn: Function, scope: any)

An extremely simple templating language. Primary used for basic string replacement. For more serious uses, particulary with DOM manipulation, use a vetted templating language such as mustachejs.

const $ = Washi.$

$.template('{foo}', { foo: 'bar' }) //=> 'bar'
$.template('{foo}') //=> '{foo}'

append(parent: Element, ...elements: Element[])

Append a list of children to an element:

const $ = Washi.$

let planets = $(['Mercury', 'Venus', 'Earth', 'Mars'])

planets.map(item => {
  var el = document.createElement('li')
  el.innerHTML = item
  return el
})

$('ul').append(planets.valueOf())

remove(elements: Element | Element[])

Remove a single HTML element from its parent, or each element within a list:

const $ = Washi.$

// Remove buttons from a form:
$('#my-form button').remove()

addClass(element: Element, classes: String)

Add one or more class names to an element:

const $ = Washi.$

let el = document.createElement('button')

el.className = 'btn'

$.addClass(el, 'btn-large')

console.log(el.className) // 'btn btn-large'

removeClass(element: Element, classes: String)

Remove one or more class names to an element:

const $ = Washi.$

let el = document.createElement('button')

el.className = 'btn btn-large'

$.removeClass(el, 'btn btn-large')

console.log(el.className) // ''

toggleClass(element: Element, classes: String, keep?: Boolean)

Toggle one or more class names to an element. When provided, adds/removes the class names based upon the keep argument

const $ = Washi.$

let el = document.createElement('button')

el.className = 'btn'

$.toggleClass(el, 'active')
console.log(el.className) // 'btn active'

$.toggleClass(el, 'active')
console.log(el.className) // 'btn'

$.toggleClass(el, 'active', false)
console.log(el.className) // 'btn'

$.toggleClass(el, 'active', true)
console.log(el.className) // 'btn active'

Code At Viget

Visit code.viget.com to see more projects from Viget.