@dymantic/vue-forms

Form object and mixin for Vuejs based form

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
00Aug 10, 2018Jan 13, 2018Minified + gzip package size for @dymantic/vue-forms in KB

Readme

Vue Form Component

A minimal component to simplify working with forms in Vue. You still create the form UI yourself, but with access to form data and any validation errors that are returned upon submission. Assumes responses from the server follow a given format.

Build Status

Installation

npm install @dymantic/vue-forms

Component Props

Prop Type Required Default Note
url string yes none form is submitted by POST to this url
form-model Form (from @dymantic/vue-forms) yes none keeps track of data and error messages
redirect-to string no none if present, page will navigate here after successful submission

The Form Object

The value passed to the form-model prop must be of the type Form, imported as such: import {Form} from @dymantic/vueforms. This gives you a constructor to create a form object, by passing an object containing the default values of your form object. For example:

const form = new Form({
    username: "Harry",
    school: "Hogwarts"
});

// form.data.username === "Harry"
// form.data.school === "Hogwarts"

Continuing with the example above, the form object can be used as such:

form.data.username = "Victor"
form.data.school = "Durmstrang"

// form.data.username === "Victor"
// form.data.school === "Durmstrang"

form.resetFields();

// form.data.username === "Harry"
// form.data.school === "Hogwarts"

form.resetFields({username: "Victor"});

// form.data.username === "Victor"
// form.data.school === "Hogwarts"

form.setValidationErrors({school: ["not a recognised school"]});

// form.errors.school === "not a recognised school"
// form.errors.username === ""

form.clearErrors();

// form.errors.school === ""
// form.errors.username === ""

Using the form data and errors in your template: You can get access to the form object by destructing it out of the slot scope as such slot-scope={formData, formErrors, waiting} as seen in the example provided below. This allows you to bind form fields with v-model, and use validation errors in your template.

Component Events

Event Payload Notes
submission-okay response data fired on successful submission
submision-failed {status: [RESPONSE STATUS]} recieved a 4** or 5** response from server
form-error none a non-network error occured during submision

Note

This component assumes that if the form submission fails validation, the server will respond with a 422 status code, and include the validation error messages that follow the following format(it is default Laravel behaviour).

// in response body
{
    "errors": {
        "username": ["The username is not available", "The username contains invalid characters"]
    }
}

Example usage

As a basic sample, lets assume we are making a simple component to save/update a username

// in your own component/page

<template>
    <div>
        // ... your template code
        <vue-form url="/usernames"
                  :form-model="formModel"
                  @submisison-okay="usernamePersisted"
                  @submission-failed="handleError"
        >
            <div slot-scope="{formData, formErrors, waiting}">
                <div :class="{'has-error': formErrors.username}">
                    <label for="username">Username</label>
                    <span class="text-danger" v-show="formErrors.title">{{ formErrors.title }}</span>
                    <input type="text" name="title" v-model="formData.username" id="username">
                </div>
                <button type="submit" :disabled="waiting">
                    Save
                </button>
            </div>
        </vue-form>
        // ... more template code
    </div>
</template>

<script>
    import {Form} from "@dymantic/vue-forms"

    export default {

        data() {
            function() {
                formModel: new Form({username: "default username"})
            };
        },

        methods: {
            usernamePersisted(response_data) {
                // reponse data is what was returned by server as response. You may use it to update the form data.
                // You may also just reset the form this.form.resetFields()
            },

            handleError({status}) {
                //status is the non 200 http status code returned by server
            }
        }
    }
</script>

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.