washi
A small (2.2kb gzipped), Backbone-inspired, library for greater organization on small projects.
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:
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 = ;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' { thisuititle; } { var text = $ console } { console } var sample =
Corresponding with:
Paper Crane
API
Washi Components
Create a view component based upon a configuration:
let Sample = ui: title: '.title' events: 'click @ui.title': 'doSomething' { // Startup console } { } let sample =
initialize(options: Object)
Invoked after the Washi instance has been created. Use this method for setup behavior.
let Widget = { console } let component = // "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' { } let component = component // "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' { }
this.ui
As entries in Reference the selected elements associated with a ui
entry under this.ui
:
let Widget = ui: 'button': 'button' { // An array of DOM elements thisuibutton // Alternatively, a Washi chain thisui$button }
Washi Utilities
Washi exposes a number of utility methods under the $
namespace:
- chain
- Array operations
- toArray
- extend
- has
- query
- queryAll
- invoke
- isBlank
- isDOM
- isFunction
- isObject
- isRegExp
- isString
- isUndefined
- matches
- on
- off
- result
- tap
- template
- append
- remove
- addClass
- removeClass
- 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 = $let result = chain console // [2,3,4]
Passing a string to Washi.$
executes document.querySelectorAll
, converting the selection into a chain:
const $ = Washi$
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
:
join
reverse
sort
push
pop
shift
unshift
slice
splice
concat
indexOf
lastIndexOf
forEach
map
reduce
reduceRight
filter
some
every
You can use these directly, however they are primary intended for use with chaining:
const $ = Washi$ let internalLinks = internalLinks
toArray(list: Enumerable)
Convert a list-like value, such as a NodeList
returned from document.querySelectorAll
into an array:
const $ = Washi$ let links = documentlet hrefs = $
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 = $ // { 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' $ // true$ // 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 = $ if btn btn
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 = items
invoke(list: Array, method: String, ...arguments: any[])
Execute a method on each member of a list:
const $ = Washi$ // Operate on datalet planets = 'Mercury' 'Venus' 'Earth' 'Mars'$ // ['MERCURY', 'VENUS', 'EARTH', 'MARS'] // Or call methods on a list of elements
isBlank(value: any)
Is a value null or undefined?
const $ = Washi$ $ // false$ // false$ // false$ // true$ // true
isDOM(value: any)
Is a value a DOM element?
const $ = Washi$ $ // false$ // true
isFunction(value: any)
Is a value a function?
const $ = Washi$ $ // false$ // 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$ $ // true$ // true$ // false$ // false
isRegExp(value: any)
Is a value a regular expression?
const $ = Washi$ $ // false$ // true$ // true
isString(value: any)
Is a value a string?
const $ = Washi$ $ // false$ // true
isUndefined(value: any)
Is a value undefined?
const $ = Washi$ $ // false$ // false$ // false$ // 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$ $
on(el: Element, event: String, callback: Function, capture: boolean)
Safely attach an event listener with extreme browser support (IE5+).
const $ = Washi$ $ // Or chain it:
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 = let buttonsbuttons // CLICK! CLICK! CLICK! buttonsbuttons // 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$ $ // 'missing'$ // '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$ { let p = document pinnerHTML = items documentbody} let dates =
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$ $ //=> 'bar'$ //=> '{foo}'
append(parent: Element, ...elements: Element[])
Append a list of children to an element:
const $ = Washi$ let planets = planets
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:
addClass(element: Element, classes: String)
Add one or more class names to an element:
const $ = Washi$ let el = document elclassName = 'btn' $ console // 'btn btn-large'
removeClass(element: Element, classes: String)
Remove one or more class names to an element:
const $ = Washi$ let el = document elclassName = 'btn btn-large' $ console // ''
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 elclassName = 'btn' $console // 'btn active' $console // 'btn' $console // 'btn' $console // 'btn active'
Visit code.viget.com to see more projects from Viget.