vue-smart-form

    0.0.2 • Public • Published

    vue-smart-form

    npm npm vue2

    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

    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

    Install

    npm i vue-smart-form

    DownloadsWeekly Downloads

    5

    Version

    0.0.2

    License

    MIT

    Unpacked Size

    340 kB

    Total Files

    18

    Last publish

    Collaborators

    • saymon