v-api-form

A Vue package for managing FormData that is used as ajax parameters.

Usage no npm install needed!

<script type="module">
  import vApiForm from 'https://cdn.skypack.dev/v-api-form';
</script>

README

v-api-form

A Vue package for managing FormData that is used as ajax parameters.

Installation

npm i v-api-form --save

Preparation

First, set parameters in Vue.

new Vue({
    el: '#app',
    data: {
        params: {
            email: '',
            password: '',
            categories: [], // e.g. multiple checkboxes
            nested_values: [
                {id: 1, names: ['John', 'Mike']},
                {id: 2, namess: ['Max']},
                {id: 3, name: ['Ann', 'Christine']},
            ]
        }
    },

params is default data property for this package.
In this case, errors is also set by default.

And bind their data properties as usual.

<input type="text" v-model="params.email">
<input type="password" v-model="params.password">

Usage

FormData

You can get parameters through FormData().

const params = this.getFormData();

// Or with extra parameters

const params = this.getFormData({
    _method: 'PUT',             // string
    numbers: [1, 2, 3, 4, 5],    // array
    nested_values: [
        {id: 1, names: ['John', 'Mike']},
        {id: 2, namess: ['Max']},
        {id: 3, name: ['Ann', 'Christine']},
    ]
});

Errors

This package rearrange errors that has only first messages of errors through setFormErrors().

onSubmit: function() {

    axios.post(url, params)
        .then((response) => {

            // ..

        })
        .catch((error) => {

            this.setFormErrors(error);

        });

},

Now this.errors will be changed to rearranged errors when you get errors.

Note:
If your error has a key which includes dot-notation like photos.0, the message will be Object as follows.

{
    "0":"The photos.0 must be a file of type: jpg.",
    "1":"The photos.1 must be a file of type: jpg."
    "2":"The photos.2 must be a file of type: jpg."
}

The rearrangement is mainly for axios and Laravel response.
Please override getFormErrors() if you'd like to use other data construction.

methods: {
    getFormErrors(error) {
    
        // Your code here.
    
        return errors;
    
    }
}

If you'd like to retrieve an error by key or dot notation string, use getFormError() as follows.

const error = this.getFormError('email');

// with Default Value

this.getFormError('users.0.email', 'Default Value');

// or specify target

this.getFormError('email', 'Default Value', 'customErrors');

File

If you'd like to set <input type="file"> in your page, use v-file-model in the same way as v-model .

<input type="file" v-file-model="params.profile">

or in v-for

<div v-for="(file,i) in params.files">
    <input type="file" v-file-model="'params.files.'+ i">
</div>

In this case, set File or FileList as the default parameter.

data: {
    params: {
        profile: File
    }
}

Or multiply

<input type="file" v-file-model="customParams.profiles" multiple>

data: {
    params: {
        profiles: FileList
    }
}

Note:

When you use multiple for file input, parameter name is automatically changed.
For example, profiles[] is the name in the above case.

Clear and reset

Parameters

this.clearFormParams();     // inputs & files
this.clearInputParams();    // only inputs
this.clearFileParams();     // only files

// or

this.resetFormParams(); // change params to default values

Errors

this.clearFormErrors();

Multiple usage

You may use several form in the same page.
In a case like that, you can use setApiFormParams() to set multiple parameters.

beforeMount: function() {

    this.setApiFormParams([
        {
            params: 'params',
            errors: 'errors'
        },
        {
            params: 'customParams',
            errors: 'customErrors'
        }
    ]);
    
}

Now you have 2 form parameters.

Specify target

You can specify target parameters/errors when using each methods in multiple parameter's environment.

FormData

const params = this.getFormData({}, 'customParams');

Errors

this.setFormErrors(error, 'customParams');

Clear and reset

// Parameter
this.clearFormParams('customParams');   // inputs & files
this.clearInputParams('customParams');  // only inputs
this.clearFileParams('customParams');   // only files
this.resetFormParams('customParams');   // reset params

// Error
this.clearFormErrors('customErrors');

Resize image

You can automatically resize selected image(s) by setting max-image-width or max-image-height as follows.

<!-- Width -->
<input type="file" 
    accept="image/*" 
    max-image-width="300" 
    v-file-model="params.images">

<!-- Height -->
<input 
    type="file" 
    accept="image/*" 
    max-image-height="300" 
    v-file-model="params.images">
    
<!-- Both -->
<input 
    type="file" 
    accept="image/*" 
    max-image-width="300" 
    max-image-height="300" 
    v-file-model="params.images">

Note: If your application need to support ie 11, use JavaScript Canvas to Blob.

License

This package is licensed under the MIT License.

Copyright 2018 Sukohi Kuhoh