vue-smart-form

Plugin provides two mixins with basic features of form behavior and form submission

Plugin based on vuelidate package and doesn't work without it, so vuelidate should be installed and registered in application via Vue.use()

Form mixin features:

• sync with parent via v-model
• sync with parent via state prop with sync modifier
• reactive validation state
• merging of client-side and server-side validation errors to provide the easy way to display validation errors messages of both types in one place
• subforms validation with reactive validation state tree (also syncable via state.sync)
• support of multiple forms in single parent component
• sending state handling (can be used to block UI while request is performing)
• double submit protection
• server response handling
• ability to set a delay between $touch called and validation really triggered to prevent flashing of error messages in case of conditional forms switching
• is form complete detection (all rquired fields are filled with valid values)
• prefilling form with initial data
• ability to define custom function serverErrorsFormatter to fit error response from your back-end with format expected by mixin
• autofocusing desired field when form mounted
• perfectly fits with Buefy framework components <b-field> and <b-input>
• customizing validation error messages with gracefull degradation from field-specific meessages to common messages for specific validator

Submitter mixin features:

• controlling sending state passed into child component with form
• storing server response to pass into form
• submitStart, submitOk, submitFailed methods to integrate with API calls
• support of multiple forms in single parent component

Table of contents

• Installation
• Usage
• Example

Installation

npm install --save vue-smart-form

Import and register plugin

import Vue from 'vue'
import VueSmartForm from 'vue-smart-form'

Vue.use(VueSmartForm, {
  serverErrorsFormatter: function (response) {
    // custom logic to fit API errors with expected format
  }
})

Import specific mixins in your components:

Form mixin:

import { mixSmartForm } from 'vue-smart-form'

Form submitter mixin:

import { mixFormSubmitter } from 'vue-smart-form'

Usage

Form mixin

All form fields should be stored in the fields property of component's data object

Login form example

HTML template of LoginForm.vue

<template>
  <form @submit.prevent="submit()"> <!-- submit() method is mixin's submit handler -->

    <!-- EMAIL FIELD -->
    <div
      :class="[$vf.email.type]"
    >
      <input
        data-autofocus
        v-model="fields.email"
        @input="onInput('email')"
        @blur="onBlur('email')"
      />
      <p>{{ $vf.email.msg }}</p>
    </div>
    <!-- /EMAIL FIELD -->

    <!-- PASSWORD FIELD -->
    <div
      :class="[$vf.password.type]"
    >
      <input
        type="password"
        v-model="fields.password"
        @input="onInput('password')"
        @blur="onBlur('password')"
      />
      <p>{{ $vf.email.msg }}</p>
    </div>
    <!-- /PASSWORD FIELD -->

    <button :disabled="sending">Submit</button>
  </form>
</template>

Javascript part of LoginForm.vue

// import predefined validators from vuelidate
import {
  email,
  required,
  minLength,
  maxLength
} from 'vuelidate/lib/validators'
// import form mixin
import { mixSmartForm } from 'vue-smart-form'
const MIN_PASSWD_LENGTH = 6
const MAX_PASSWD_LENGTH = 25
const MAX_EMAIL_LENGTH = 254
export default {
  name: 'LoginForm.vue',
  mixins: [
    mixSmartForm
  ],
  data () {
    return {
      // all form fields should be defined inside this (`fields`) property
      fields: {
        email: null,
        password: null
      },
      // all validation messages should be described inside `vmessages` property
      vmessages: {
        // validation messages for validators of `email` field
        email: {
          required: 'Email is required',
          email: 'Invalid e-mail format',
          maxLength: 'E-mail can\'t be longer than ' + MAX_EMAIL_LENGTH + ' characters'
        },
        // validation messages for validators of `password` field
        password: {
          required: 'Password is required', // you can delete this line and the default message "This field can not be empty" for `required` validator will be used
          minLength: 'Password length can\'t be less than ' + MIN_PASSWD_LENGTH + ' characters',
          maxLength: 'Password can\'t be longer than ' + MAX_PASSWD_LENGTH + ' characters'
        },
        // the `required` property below is not the message for field with name `rquired`.
        // It's the default message for `required` validator.
        // It will be used for fields which hasn't any specific messages defined for `required` validator.
        required: 'This field can not be empty'
        // you can define default message for any validator and
        // there will be no necessity to define custom message for each field with same validator.
        // So it's up to you - use one message for particular validator through all fields where it's applyed or
        // define custom validator message for each field
      }
    }
  },
  // vuelidate validation rules definition. It's `vuelidate` only stuff, so see their docs for details
  validations: {
    fields: {
      email: {
        email,
        required,
        maxLength: maxLength(MAX_EMAIL_LENGTH)
      },
      password: {
        required,
        minLength: minLength(MIN_PASSWD_LENGTH),
        maxLength: maxLength(MAX_PASSWD_LENGTH)
      }
    }
  }
}

Form submitter mixin

Login page example

HTML template of LoginPage.vue

<template>
  <div>
    <LoginForm
      :sending="$sd.formLogin.sending"
      :server-response="$sd.formLogin.errorResponse"
      @submit="onLoginFormSubmit"
    />
  </div>
</template>

Javascript part of ``

import mixFormSubmitter from 'vue-smart-form'
import LoginForm from './LoginForm.vue' // code of this component is described above
export default {
  name: 'LoginPage',
  mixins: [
    mixFormSubmitter
  ],
  forms: ['formLogin'],
  components: {
    LoginForm
  },
  methods: {
    onLoginFormSubmit (data) {
      this.submitStart('formLogin')
      this.$api.login(data).then(
        () => {
          this.submitOk('formLogin')
        },
        (errorResponse) => {
          this.submitFailed('formLogin', errorResponse)
        }
      )
    },
  }
}

Mixins interfaces

TODO

Plugin Development

Installation

The first time you create or clone your plugin, you need to install the default dependencies:

npm install

Watch and compile

This will run webpack in watching mode and output the compiled files in the dist folder.

npm run dev

Use it in another project

While developping, you can follow the install instructions of your plugin and link it into the project that uses it.

In the plugin folder:

npm link

In the other project folder:

npm link vue-smart-form

This will install it in the dependencies as a symlink, so that it gets any modifications made to the plugin.

Publish to npm

You may have to login to npm before, with npm adduser. The plugin will be built in production mode before getting published on npm.

npm publish

Manual build

This will build the plugin into the dist folder in production mode.

npm run build

License

MIT