Needlessly Promiscuous, Modularize!

    vue-rawmodel
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.2 • Public • Published

    NPM Version Dependency Status

    vue-rawmodel

    RawModel.js plugin for Vue.js v2. Form validation has never been easier!

    This plugin integrates RawModel.js framework into your Vue.js application.

    RawModel.js is a simple framework which provides a strongly-typed JavaScript object with support for validation and error handling. It has a rich API which significantly simplifies server-side and client-side data validation and manipulation. Because it's an unopinionated framework it flawlessly integrates with popular modules like vuex, apollo-client and other related libraries.

    RawModel.js together with Vue.js represents a web framework on steroids. Thanks to its powerful and flexible model objects, a form validation has never been easier. This plugin brings even more elegant way to do form validation using RawModel.js and still leaves you freedom to customize and fine-tune the integration.

    Make sure you check RawModel.js API page for details about the framework.

    This is a light weight open source package for Vue.js written with TypeScript. It's actively maintained and ready for production environments. The source code is available on GitHub where you can also find our issue tracker.

    Related Projects

    • RawModel.js: Strongly-typed JavaScript object with support for validation and error handling.

    Installation

    Run the command below to install the package.

    $ npm install --save vue-rawmodel rawmodel
    

    This package uses promises thus you need to use Promise polyfill when promises are not supported.

    When used with a module system, you must explicitly install vue-rawmodel via Vue.use().

    import Vue from 'vue';
    import VueRawModel from 'vue-rawmodel';
     
    Vue.use(VueRawModel);

    Getting Started

    This package provides a special class called ReactiveModel which extends from Model class provided by RawModel.js. You don't need to attach the plugin to Vue. ReactiveModel is completely independent thus you can use it directly. Below is an example of a simple reactive model called User with a single field name.

    import {ReactiveModel} from 'vue-rawmodel';
     
    class User extends ReactiveModel {
      constructor (data = {}) {
        super(data); // initializing parent class
     
        this.defineField('name', { // defining class property `name`
          type: 'String', // setting type casting
          validate: [ // field validations
            { // validator recipe
              validator: 'presence', // validator name
              message: 'is required' // validator error message
            }
          ]
          // check the API for all available options
        });
      }
    }

    We can optionally pass models to the root Vue instance as the models option. This will populate the $models property which is then injected into every child component.

    const app = new Vue({
      models: { User }, // [optional] injecting models into child components (later available as this.$models.User)
      ...
    });

    Form Example

    Object validation has been one of the incentives for creating RawModel.js framework. This plugin brings even more elegant way to do form validation.

    <template>
      <form novalidate v-on:submit.prevent="submit">
        <!-- input field -->
        <input type="text" v-model="user.name" placeholder="User name"/>
        <span v-if="user.getField('name').hasErrors()">
          {{ user.getField('name').errors | firstMessage }}
        </span>
        <!-- buttons -->
        <button v-bind:disabled="user.hasErrors()">Submit</button>
      </form>
    </template>
     
    <script>
    export default {
      data () {
        return {
          user: new this.$models.User({
            vm: this, // instance of Vue's VM
            dataKey: 'user', // name of data model key
            name: 'John Smith' // initializing the `name` field
          })
        };
      },
      methods: {
        submit () {
          // Send data to the remote server
        }
      }
    }
    </script> 

    Use the $populate() method to reactively apply data to your model.

    export default {
      ...
      created () {
        this.user.$populate({
          name: 'John Smith'
        });
      }
    }

    Use Vue watchers to install real-time form validation.

    export default {
      ...
      watch: {
        user: {
          handler: (user) => user.$validate({debounce: 300}), // reactively validate fields and display errors
          deep: true, // always required
          immediate: true // set this to validate immediately after the form is created
        }
      }
    }

    Check the RawModel.js API page and this package API section for details.

    API

    This plugin extends RawModel.js functionality, which help us write reactive code in Vue. If you don't need reactivity then you can use RawModel.js directly.

    ReactiveModel

    ReactiveModel({vm, dataKey, parent, ...data})

    Abstract reactive class which represents a strongly-typed JavaScript object. This class extends from Model and adds new reactive capabilities.

    Option Type Required Default Description
    vm Vue No - Vue VM instance.
    dataKey String No - The name of the data key.
    parent Model No - Parent model instance.
    data Object No - Data for populating model fields.

    ReactiveModel.prototype.$applyErrors(errors): ReactiveModel

    A reactive alternative of method applyErrors() which deeply populates fields with the provided errors (useful for loading validation errors received from the server).

    Option Type Required Default Description
    errors Array No [] An array of errors.

    ReactiveModel.prototype.$clear(): ReactiveModel

    Reactive alternative of method clear() which sets all fileds to null.

    ReactiveModel.prototype.$fake(): ReactiveModel

    Reactive alternative of method fake() which resets fields then sets fields to their fake values.

    ReactiveModel.prototype.$forceUpdate (): ReactiveModel

    Force the vm instance to re-render.

    ReactiveModel.prototype.$handle (error, {quiet, debounce}): Promise

    Reactive alternative of method handle() which handles the error and throws an error if the error can not be handled.

    Option Type Required Default Description
    error Any Yes - Error to be handled.
    quiet Boolean No true When set to false, a handled validation error is thrown. This doesn't affect the unhandled errors (they are always thrown).
    debounce Boolean 0 - Number of milliseconds to wait before running validations.

    ReactiveModel.prototype.$invalidate (): ReactiveModel

    Reactive alternative of method invalidate() which removes fields errors.

    ReactiveModel.prototype.isReactive (): Boolean

    Returns true when reactive properties (vm and dataKey) are set.

    ReactiveModel.prototype.$populate (data): ReactiveModel

    Reactive alternative of method populate() which applies data to a model.

    Option Type Required Default Description
    data Object Yes - Data object.

    ReactiveModel.prototype.$rebuild (): ReactiveModel

    Rebuilds model's reactivity system.

    ReactiveModel.prototype.$reset (): ReactiveModel

    Reactive alternative of method reset() which sets each model field to its default value.

    ReactiveModel.prototype.$rollback (): ReactiveModel

    Reactive alternative of method rollback() which sets each field to its initial value (value before last commit).

    ReactiveModel.prototype.$validate({quiet, debounce}): Promise(ReactiveModel)

    Reactive alternative of method validate() which validates the model fields and throws a validation error if not all fields are valid unless the quiet is set to true.

    Option Type Required Default Description
    quiet Boolean No true When set to true, a validation error is thrown.
    debounce Boolean 0 - Number of milliseconds to wait before running validations.

    Filters

    firstMessage

    Extracts the first error message from a list of errors.

    Example

    An example is available in the ./example folder which you can run with the npm run example command. There is also vue-example app available which you should take a look.

    Tutorials

    See vue-js-cheatsheet for more.

    License (MIT)

    Copyright (c) 2016 Kristijan Sedlak <xpepermint@gmail.com>
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
    

    Install

    npm i vue-rawmodel

    DownloadsWeekly Downloads

    13

    Version

    1.2.2

    License

    MIT

    Last publish

    Collaborators

    • xpepermint