chrisbuttery/virtual-app

Provides redux-like, unidirectional state management paired with virtual-dom.

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 action
• callback Function – callback that provides action, state, and oldState 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 Object
  • action.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 action
• initialState 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 Object
  • action.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 by require('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)
})

License

MIT