Form Component (for Vue)

Form handler component for Vue v2.

NOTE Use v1.0 branch to use this with Vue v1.

View DEMO.

Package index

• Installation
• Usage
  • Props
  • Request
  • Response
    • Redirection
  • Results
    • Props
  • Input handling
    • Props
    • Validations
  • Events
• License

Installation

Several installation options are available:

• Download the latest release.
• Install with Bower: bower install 10q-vue-form.

Usage

Add the following resources for the component to function correctly.

<!-- Required Javascript -->
<script src="vue.js"></script>
<script src="vue-resource.js"></script>
<script src="[component path]/dist/vue.form.min.js"></script>

Add the component in your vue view.

<!-- Assuming your view app is APP. -->
<div id="app">

    <vform inline-template
        action="http://some.url.com"
        method="POST"
    >

        <input type="email" v-model="request.email">

        <button @click="submit">Submit</button>

        <span v-if="isLoading">Loading...</span>

    </vform>

</div>

NOTE: inline-template must be present.

Props

List of available props to use in component:

Prop | Data Type | Default | Description --------------- | ---------- | -------- | ----------- action | String | | Action URL where to send form data. method | String | POST | Request method (i.e. GET or POST). headers | Object | | Request headers (reference). timeout | Number | | Request headers (reference). credentials | Boolean | | Flag that indicates if request has credentials (reference). emulate-http | Boolean | | Flag that indicates if request should emulate HTTP (reference). emulate-json | Boolean | | Flag that indicates if request should emulate JSON (reference). errors | Object | Object | List of default validation rules error messages. id | String | | Form given ID. key | String | | Form given loop key (i.e. in case of being used inside a v-for). response-json | Boolean | false | Forces response to be returned and parsed as JSON. response-blob | Boolean | false | Forces response to be returned as Blob.

Request

Data sent by form should be binded to the request data model. In other words, all the inputs within the form should be binded to request.

As reference, a basic contact form sample:

<div id="app">

    <vform inline-template action="http://some.url.com">

        <label for="name">Name:</label>
        <input type="text"
            id="name"
            v-model="request.name"
        />

        <label for="email">Email:</label>
        <input type="email"
            id="email"
            v-model="request.email"
        />

        <label for="message">Textarea:</label>
        <textarea id="message"
            v-model="request.message"
        ></textarea>

        <button @click="submit">Submit</button>

    </vform>

</div>

Response

Any response obtained from a request is set to the response data model.

If the following data is found, the form will auto-process the response (json) to facilitate its handling:

{
    "error": true,
    "message": "Contact information not sent."
}

This response can be displayed in the template like:

<div id="app">

    <vform inline-template>

        <div v-if="hasMessage"
            :class="{'with-error': hasError}"
        >
            {{response.message}}
        </div>

    </vform>

</div>

Computed properties to use in template:

Property | Data Type | Description -------------- | ---------- | ------------------- isLoading | Boolean | Flag that indicates if form is loading, processing or waiting for response. hasMessage | Boolean | Flag that indicates if form response returned a message to display. hasError | Boolean | Flag that indicates if form response returned as error.

Another example using Bootstrap:

<div id="app">

    <vform inline-template>

        <div v-show="hasMessage"
            class="alert"
            :class="{'alert-danger': hasError, 'alert-success': !hasError}"
        >
            {{response.message}}
        </div>

    </vform>

</div>

Redirection

If the following data is found, the form will redirect the current window to the value set in response.redirect:

{
    "error": false,
    "message": "Information sent.",
    "redirect": "http://some.url.com"
}

Results

Form comes with a child component called results. This component will facilitate the handling of data returned by request (thought for searches).

<div id="app">

    <vform inline-template>

        <label>Search:</label>
        <input type="text"
            v-model="request.q"
            @keyup.enter="submit"
        />

        <results inline-template
            v-model="response"
            fetch-on-ready="true"
            clear-on-fetch="false"
        >
            
            <div v-show="hasRecords">
                <div v-for="record in records">
                    {{record | json}}
                </div>
            </div>

        </results>

    </vform>

</div>

In the example above, results child component is handling search results returned by the response (assuming response contains only results) and it is computing them into a property called records.

NOTE: Results will compute records only if the model is an array. NOTE: inline-template must be present.

Props

List of available props to use in child component:

Prop | Data Type | Default | Description ---------------- | ---------- | -------- | ----------- model | Array | | Data to compute for results (mostly required). request | Object | | If form request is needed to be binded to results. fetch-onready | Boolean | false | Flag that forces form to submit and return response when document is ready. clear-on-fetch | Boolean | true | Flag that indicates if records should stack on every submission or not. (used for eager loading)

Another example:

<div id="app">

    <vform inline-template>

        <results inline-template v-model="response.results">
            
                <div v-for="record in records">
                    {{record | json}}
                </div>

        </results>

    </vform>

</div>

Input handling

Form comes with a second child component called input-handler. This component will facilitate the display of errors per input, improving UX.

Example using Bootstrap:

Response:

{
    "errors": [
        "email": [
            "Email is invalid.",
            "Fields is required."
        ],
        "name": [
            "Too short".
        ]
    ]
}

In template:

<div id="app">

    <vform inline-template>

        <input-handler class="form-group"
            class-error="has-error"
            listen="name"
            v-model="response"
        >
            <label for="name">Name</label>
            <input type="text"
                class="form-control"
                id="name"
                v-model="request.name"
            />
        </input-handler>

        <input-handler class="form-group"
            class-error="has-error"
            listen="email"
            v-model="response"
        >
            <label for="email">Email</label>
            <input type="email"
                class="form-control"
                id="email"
                v-model="request.email"
            />
        </input-handler>

    </vform>

</div>

In the example above, the response returned a list of errors per input. input-handler will process the response and if errors are found (response must be passed as v-model), it will add an error class to the input wrapper and will list the erros under the input using a <ul class="errors"> HTML tag.

Props

List of available props to use in child component:

Prop | Data Type | Default | Description ---------------- | ---------- | -------- | ----------- listen | String | | Name of the error key (in response) to listen to. class | String | | CSS class to apply to wrapper. (<div>) class-error | String | | CSS class to apply to wrapper when errors are available. response | Object | | Response to process. (required) validations | String | | List of validation rules to apply to input.

Validations

Form comes with a set of validation rules that can be applied to input values prior request. This are set in the validations prop, separated by |.

In the following example, the input will validate that name is not empty (is a required field) and that it has at least 8 characters:

<div id="app">

    <vform inline-template>

        <input-handler class="form-group"
            class-error="has-error"
            listen="name"
            v-model="response"
            validations="required|min:8"
        >
            <label for="name">Name</label>
            <input type="text"
                class="form-control"
                id="name"
                v-model="request.name"
            />
        </input-handler>

    </vform>

</div>

List of available rules to use:

Rule | Params | Sample | Description ---------------- | ------------------------------------------------ | ---------------------- | ----------- required | | required | Validates if value is not empty. required_if | 1) comparison field | required_if:email | Validates if value is not empty only if comparison field is not empty. email | | email | Validates if value has a valid email format. number | | number | Validates if value is numeric. min | 1) minimum string length | min:2 | Validates if value's length is not lower than the minimum value set. min_number | 1) minimum number | min_number:10 | Validates if value is not lower than the minimum value set. max | 1) maximum string length | max:10 | Validates if value's length is not bigger than the maximum value set. max_number | 1) maximum number length | max_number:15 | Validates if value is not bigger than the maximum value set. between | 1) minimum string length 2) maximum string length | between:5:10 | Validates if value's length is in between the number range set. between_number | 1) minimum number 2) maximum number | between_number:1:100 | Validates if value is in between the number range set. equals | 1) comparison field | equals:password | Validates if value is the same as comparison field's value. url | | url | Validates if value has a valid url format.

Events

Events dispatched by form:

Event | Data sent | Description ---------- | ---------------------------- | ------------------- success | | Emitted once response is returned and assigned to model response. error | e Error response returned. | Emitted on request error. (Error is thrown to console too). complete | | Emitted after request completed. (Success or error) invalid | errors List of errors. | Emitted and broadcasted when a validation ocurred.

Usage example:

<div id="app">
    <vform inline-template
        @success="eventHandlerMethod"
        @error="eventHandlerMethod"
        @complete="eventHandlerMethod"
        @invalid="eventHandlerMethod"
    ></vform>
</div>

License

Copyright (c) 2017 10Quality. Under MIT License.