README
virtual-app
A wrapper around virtual-dom, virtual-raf, & store-emitter that provides redux-like, unidirectional state management paired with virtual-dom.
What is this
I keep writing essentially this module with each new project I build that uses virtual-dom.
You could definitely use virtual-dom, virtual-raf, and store-emitter separately (and switch them out for other modules) if this doesn't fit your needs exactly.
Breaking Changes
- 3.0.0 : virtual-app no longer appends your app to the dom for you, it returns a dom tree that you can append or turn into an html string
Install
npm install --save virtual-app
Example
var extend = require('xtend')
var vdom = require('virtual-dom')
var createApp = require('virtual-app')
var h = vdom.h
/*
* create the app passing in virtual-dom
*/
var app = createApp(vdom)
/*
* The only way to modify state is to trigger an action
* the modifer function is where you change state based on the type of an action
*/
function modifier (action, state) {
if (action.type === 'example') {
return extend(state, { example: true })
} else if (action.type === 'title') {
return extend(state, { title: action.title })
}
}
/*
* Start the application with the modifier function and the initial state as args
* `app.start()` returns the `render()` function that's used to render your virtual tree
*/
var render = app.start(modifier, {
example: false
})
/*
* return the tree of your app for rendering
* this returns a real dom tree that can be appended to your web page
*/
var domTree = render(function (state) {
return h('.app', [
h('h1', state.title),
h('label', 'Write a new title: '),
h('input', {
type: 'text',
placeholder: state.title,
oninput: function (e) {
app.store({ type: 'title', title: e.target.value })
}
})
])
})
/*
* get the new state every time an action updates the state
*/
app.on('*', function (action, state, oldState) {
console.log('action happened so here is the new state:', state)
})
/*
* listen to only specific action types
*/
app.on('title', function (action, state, oldState) {
console.log('state has a new title:', state.title)
})
/*
* trigger an action using `app.store()`
*/
app.store({
type: 'example'
})
/*
* action objects must have a `type` property, and can have any other arbitrary properties
*/
app.store({
type: 'title',
title: 'awesome example'
})
/*
* append the dom tree to the page
*/
document.body.appendChild(domTree)
see also, example-server.js for a server-side rendering example
API
app.h
virtual-dom h
function.
Parameters
selector
options
children
app.on
Event listener
Parameters
event
String – can be an asterisk*
to listen to all actions or the type of a specific actioncallback
Function – callback that providesaction
,state
, andoldState
arguments
Examples
app.on('*', function (action, state, oldState) {
// do something with the new `state`
})
app.send
Bind an event to a component. Convenience wrapper around app.store
.
Parameters
action
Objectaction.type
String – an identifier for the type of the action
flag
String – call preventDefault on event (default: true)
Examples
app.h('button', { onclick: app.send({ type: 'increment' })}, 'click me')
app.start
Start the app.
Parameters
modifier
Function – function that determines how the state will change based on the actioninitialState
Object – the state of the application when it loads
Examples
function modifier (action, state) {
if (action.type === 'example') {
return { example: true }
}
}
var render = app.start(modifier, {
example: false
})
render(function (state) {
if (state.example) {
return app.h('h1', 'this is an example')
} else {
return app.h('h1', 'what i thought this was an example')
}
})
app.store
Trigger an event that gets passed through the modifier function to change the state. A type
property is required. You can add any other arbitrary properties.
Parameters
action
Objectaction.type
String – an identifier for the type of the action
Examples
app.store({
type: 'example'
example: true
})
createVirtualApp
Create the app.
Parameters
vdom
Object – the full virtual-dom module returned byrequire('virtual-dom')
Examples
var createVirtualApp = require('virtual-app')
var app = createVirtualApp(require('virtual-dom'))
render
Render the application. This function is returned by the app.start()
method.
Parameters
callback
Function – define the virtual tree of your application and return it from this callback
Returns
- Object - a dom tree
Examples
var render = app.start(modifier, { food: 'pizza' })
var domTree = render(function (state) {
return app.h('h1', state.food)
})