Vue Formulate

Vue Formulate has been re-written in version 2! This version will no longer be maintained, please use @braid/vue-formualte instead.

What is it?

Vue Formulate is a Vue plugin that exposes an elegant mechanism for building and validating forms with a centralized data store.

Show and tell

You'll find an easy to use example, in the example directory as well as a live demo available at: demo.vueformulate.com.

Get Started

Download

First download the vue-formulate package from npm:

npm install vue-formulate

If you want to use ES6 features in your project (and this readme assumes you do), then you'll also need Babel:

babel-preset-env
babel-preset-stage-2

Many Vue/Vuex projects require Babel’s stage-2 preset. Best practice is to include a .babelrc in the project root:

{
  "presets": [
    ["env", { "modules": false }],
    "stage-2"
  ]
}

Installation

Install vue-formulate like any other vue plugin:

import Vue from 'vue'
import formulate from 'vue-formulate'

Vue.use(formulate)

Vuex

vue-formulate needs to be linked to your vuex store. Vuex can be configured as a single root store, or as namespaced modules and vue-formualte can work with either setup.

Vuex Module

import {formulateModule} from 'vue-formulate'

export default formulateModule('namespace')

Using a namespaced vuex module is the recommended installation method. Just be sure to replace 'namespace' with the namespace of your vuex module.

Additionally, when using a vuex namespace, you must also pass the namespace in the Vue plugin installation call:

Vue.use(formulate, {vuexModule: 'namespace'})

Alternatively, you can install vue-formulate's store elements to your vuex root store:

Root Store

import Vue from 'vue'
import Vuex from 'vuex'
import {formulateState, formulateGetters, formulateMutations} from 'vue-formulate'

Vue.use(Vuex)

const state = () => ({
  // your own state data can live next to vue-formulate's data
  // Note: formulateState is a curried function.
  your: 'data',
  ...formulateState()()
})

const getters = {
  // Your own getters can live next to vue-formulate's getters
  yourGetter (state) {
    return state.your
  },
  ...formulateGetters()
}

const mutations = {
  // Your own mutations can live next to vue-formulate's mutations
  setYour (state, payload) {
    state.your = payload
  },
  ...formulateMutations()
}

export default new Vuex.Store({
  state,
  getters,
  mutations
})

Usage

vue-formulate automatically registers two components formulate and formulate-element. These two elements are able to address most of your form building needs. Here's a simple example:

<formulate name="registration">
  <formulate-element
    name="email"
    type="email"
  />
  ...more formulate-elements
</formulate>

You can think of <formulate> elements a little bit like traditional <form> tags. You must wrap your formulate-element components in a <formulate> component. The formulate component has a single required prop name which creates the form’s key in the vuex store.

All formulate-element components nested inside a <formulate> component will automatically commit mutations directly to the store. The store becomes a live representation of all your form’s values.

The formulate-element component is a powerful component which handles field generation.

Validation Rules

There are several built-in validation methods and you can easily add your own as well.

Rule | Arguments ----------|--------------- required | none email | none confirmed | confirmation field number | none

You can add as many validation rules as you want to each formulate-element, simply chain your rules with pipes `|'. Additional arguments can be passed to validation rules by using parenthesis after the rule name:

validation="required|confirmed(confirmation_field)"

The field label used in built-in validation methods is the validation-label attribute on your formulate-element. If no validation-label is found then the label attribute is used, and if no label attribute is found it will fall back to the field’s name attribute (which is required).

Custom Validation Rules

Validation rules are easy to write! They're just simple functions that are always passed at least one argument, an object containing the field name, value of the field, validation label, error function to generate an error message, and an object containing all the values for the entire form.

Additionally, validation rules can pass an unlimited number of extra arguments. These arguments are passed as the 2nd-nth arguments to the validation rule. Their values are parsed from the optional parenthesis in the validation attribute on the formulate-element.

<formulate-element
  type="password"
  name="password"
  label="Password"
  validation="confirmed(password_confirmation_field)"
/>

Validation rules should return an error message string if they failed, or false if the input data is valid.

Adding your own validation rules is easy. Just pass an additional object of rule functions in the plugin’s installation call:

Vue.use(formulate, {
  rules: {
    isPizza ({field, value, error, values, label}) {
      return value === 'pizza' ? false : `label is not pizza.`
    }
  }
})

Styling

Absolutely zero styles are included so feel free to write your own! The form-element components have a wrapper div that receives the following classes:

formulate-element
formulate-element--has-value
formulate-element--has-errors

Full Documentation

There are many more options available, more documentation coming soon.