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 themixins
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 objectkeys
-- the properties inside the data object that you want to map into form componentvalidate-callback
-- the validation callback function defined in main Vue instance to be called by form component before the data are saved or updateddelete-button
-- set totrue
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 callsetErrors()
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 totrue
to indicate a new data. Otherwise, its value will be set tofalse
.
# 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 validation callback (if defined). If the validation fails, then exit.
- Copy all the changes from
input
todata
- Dispatch the
dataform:stored
ordataform:updated
event depending on the valid ofisNew
.
- Check if the data in the form has been modified (e.g. different from the original values). If not, the
# 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 givendata
to theinput
object. It will also set the value ofisNew
property depending on the content of the given argument.Note: This method is called when
dataform:set-data
event was received. You should usedataform: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, returnfalse
.
# 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 fieldname
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 usedataform:set-errors
event when possible.
# clearErrors
-
Description:
Set the internal
errors
property tonull
.
# clearForm
-
Description:
Set all input inside data form to empty string
''
.
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
``` bash
# 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.