vue-dataform-mixin

Vue Mixin util to help create data entry component

Installation

NPM

$ npm install vue-dataform-mixin

Usage

• Create a component that will contains the HTML form (will call this a form component)
• Import vue-dataform-mixin and register it in the mixins section
• Apply onSave, onCancel, onDelete methods to the form component
• Add additional data and methods to the form component as necessary
• Register the form component to main Vue instance
• Pass following data via props (these props are defined in vue-dataform-mixin)
  • data -- the data object
  • keys -- the properties inside the data object that you want to map into form component
  • validate-callback -- the validation callback function defined in main Vue instance to be called by form component before the data are saved or updated
  • delete-button -- set to true if you want to show a delete button

Properties

# keys

• Required: true

• Expect: Array

• Usage:

  Array of property names to be mapped to input object inside the data form.

  [ 'prop_a', 'prop_b', 'prop_c' ]
  

  If the property has nested object, use the following format:

  [ 'prop_a', 'prop_b', { name: 'prop_c', value: ['prop_c_1', 'prop_c_2'] } ]
  

  The nested object can also contain nested object as well.

# data

• Expect: Object

• Default: {}

• Usage:

  The data which its value will be used to populate in the data form. This data will not be modified until the changes have been committed (saved) by the user.

# validate-callback

• Expect: String

• Default: ''

• Usage:

  Name of the callback to be called for the data validation. If no callback is defined, the validation will always return true (which is considered as passed)

# delete-button

• Expect: Boolean

• Default: false

• Usage:

  Whether to display the delete button or not?

  Note: You need to make sure that the delete button will be conditionally displayed in your template and the its click event is bound to onDelete() method.

Internal Data

# input

• Default: null

• Description:

  This is where the values in the data prop will be copied to and used inside data form.

  Note: Only the values of property given in the keys prop will be copied, the rests are ignored.

# errors

• Default: null

• Description:

  If it is not null, it will contain all the validation errors of the fileds not passing validation.

  Note: Normally, this property can be set via dataform:set-errors event, which will internally call setErrors() method.

# isNew

• Default: false

• Description:

  Its value will be automatically set by setData() method. If the pass-in data is null, it will be set to true to indicate a new data. Otherwise, its value will be set to false.

# eventPrefix

• Default: dataform:

• Description:

  The prefix string that should be applied to all event emitted by the data form.

Event trigger methods

In order for the data form to work, you will need to correctly bind these methods to the corresponding buttons.

# onSave

• Usage:

    <template>
      ...
      <button @click="onSave">Save</button>
      ...
    </template>

• Description:

  When triggered, it will do the following, in order:

  • Check if the data in the form has been modified (e.g. different from the original values). If not, the dataform:no-changed event will be dispatched and exit.
  • Call the beforeValidate hook.
  • Call the validation callback (if defined). If the validation fails, then exit.
  • Call the afterValidate hook.
  • Copy all the changes from input to a new object to be passed during dispatching.
  • Call the transform hook with the modified data.
  • Dispatch the dataform:stored or dataform:updated event depending on the valid of isNew and passing the modified data.

# onCancel

• Usage:

    <template>
      ...
      <button @click="onCancel">Cancel</button>
      ...
    </template>

• Description:

  When triggered, it will dispatch the dataform:cancelled event, then exit.

# onDelete

• Usage:

    <template>
      ...
      <button @click="onDelete">Delete</button>
      ...
    </template>

• Description:

  When triggered, it will dispatch the dataform:request-delete event, then exit.

Data related methods

# setData

• Argument: {Object} data

• Description:

  This method will copy the values of the provided keys prop in the given data to the input object. It will also set the value of isNew property depending on the content of the given argument.

  This method will call beforeSetData hook before it starts setting (copying) data to internal input variable and it will call afterSetData hook just before it exits the method. See Hooks section below.

  Note: This method is called when dataform:set-data event was received. You should use dataform:set-data event when possible.

# isDirty

• Returns: boolean

• Description:

  Return true if the data in the data form has been modified to be different than the original value. Otherwise, return false.

# hasError

• Argument: {String} name (optional)

• Returns: boolean

• Description:

  Check if there is any error from validation when called without an argument.

  Or, check if there is any error for the given field.

# getError

• Argument: {String} name

• Returns: {Array} -- array of error messages of the given field name or empty array if there is no error

• Description:

  Get the array of validation error message(s) for the given field.

# setErrors

• Argument: {Array} errors

• Description:

  Set the internal errors property to the given object.

  Note: This method is called when dataform:set-errors event was received. You should use dataform:set-errors event when possible.

# clearErrors

• Description:

  Set the internal errors property to null.

# clearForm

• Description:

  Set all input inside data form to empty string ''.

Hooks

# beforeSetData

• Argument: none

• Description:

  This hook allows you to do something before setData begins to do anything

• Usage: You can define this method in your main component that uses this mixin.

# afterSetData

• Argument: none

• Description:

  This hook allows you to do something after setData has been finished. For example, you may need to call a method to calculate some values right after the data has been set to input variable.

• Usage:

  You can define this method in your main component that uses this mixin.

# beforeValidate

• Argument: none

• Description:

  This hook will be called before the validation callback is invoked.

• Usage:

  You can define this method in your main component that uses this mixin.

# afterValidate

• Argument: none

• Description:

  This hook will be called right after the validation has been called

• Usage:

  You can define this method in your main component that uses this mixin.

# transform

• Argument: {Object} data

• Description:

  This hook allows you to further transform the pass-in data before it is dispatching to the parent instance.

• Usage:

  You can define this method in your main component that uses this mixin.

  Note: You must always return the data back to the caller

Input keypress filtering

# numericInputFilter

• Arguments:

  • {String} value
  • {KeyboardEvent} event

• Usage:

    <template>
      ...
      <input type="text" v-model="input.price"
          id="inputPrice"
          @keypress="numericInputFilter(input.price, $event)">
      ...
    </template>

• Description:

  Filter the input to accept only numeric digits, decimal, and minus sign.

Events

# dataform:set-data

• Argument: {Object} data

• Type: Listening

• Description:

  You can use this event to set the data to be used in the form.

# dataform:clear-form

• Type: Listening

• Description:

  Use this event to clear all the input value in the data form.

# dataform:set-errors

• Argument: {Array} errors

• Type: Listening

• Description:

  Use this event to send the validation errors to the data form component.

# dataform:clear-errors

• Type: Listening

• Description:

  Use this event to clear all the errors by setting errors object to null.

Build Setup

# install dependencies
npm install

# serve with hot reload at localhost:8080
npm run dev

# build for production with minification
npm run build

# run unit tests
npm run unit

# run all tests
npm test

License

vue-dataform-mixin is open-sourced software licensed under the MIT license.