1 | # Vue dotnet validator
|
2 |
|
3 | A vuejs validator for .NET forms.
|
4 |
|
5 | ## Build status
|
6 |
|
7 | [![CircleCI](https://circleci.com/gh/Q42/vue-dotnet-validator/tree/master.svg?style=svg)](https://circleci.com/gh/Q42/vue-dotnet-validator/tree/master)
|
8 |
|
9 | ## Summary
|
10 |
|
11 | This package makes it possible to use .NET model validation using vue.js instead of the default jQuery validator way that microsoft dictates.
|
12 | The idea is that you use this on your server rendered HTML forms which include the data-attributes that are generated by C#'s razor template engine.
|
13 |
|
14 | ## Requirements
|
15 |
|
16 | This package (from version 0.3.0 and up) requires vue 2.x.
|
17 |
|
18 | ## Installation
|
19 |
|
20 | `npm install vue-dotnet-validator`
|
21 |
|
22 | ## Usage
|
23 |
|
24 | Using this library requires changes on two places in your application, JavaScript and your razor cshtml templates.
|
25 |
|
26 | ### JavaScript
|
27 |
|
28 | This registers the vue components so that Vue.js knows what to activate.
|
29 | Base usage:
|
30 |
|
31 | ```JavaScript
|
32 | import { validatorGroup, validator } from 'vue-dotnet-validator';
|
33 |
|
34 | Vue.component('validator-group', validatorGroup);
|
35 | Vue.component('validator', validator());
|
36 | ```
|
37 |
|
38 | ### Cshtml
|
39 |
|
40 | The following code should be added to your cshtml forms. This makes sure that the validator logic is activated and adds the required references to DOM-nodes.
|
41 |
|
42 | ```HTML
|
43 | <validator-group inline-template>
|
44 | <form asp-controller="Account" asp-action="Register" method="post" v-on:submit="validate">
|
45 | <validator value="@Model.LastName" inline-template>
|
46 | <span asp-validation-for="LastName" ref="message"></span>
|
47 | <input type="text" asp-for="LastName" ref="field" v-model="val" />
|
48 | </validator>
|
49 | <button type="submit">Register</button>
|
50 | </form>
|
51 | </validator-group>
|
52 | ```
|
53 |
|
54 | #### Explanation of the cshtml changes:
|
55 |
|
56 | `<validator-group inline-template>`
|
57 |
|
58 | This behaves as a container for the entire form, so we can maintain the state of the entire form and the validation status of the input fields in it.
|
59 |
|
60 | `v-on:submit="validate"`
|
61 |
|
62 | This adds an event listener to the `<form>` tag to make sure we prevent the default form submit event when fields are invalid.
|
63 |
|
64 | `<validator value="@Model.LastName" inline-template>`
|
65 |
|
66 | This adds a validator instance to the form. The `@Model.LastName` is the property of your model.
|
67 |
|
68 | `ref="message"`
|
69 |
|
70 | This adds a reference to the validation-message element. This makes sure the validation message is displayed at the correct position in the DOM.
|
71 |
|
72 | `ref="field"`
|
73 |
|
74 | This adds a reference to the input field, so the `<validator>` instance knows what element to watch.
|
75 |
|
76 | `v-model="val"`
|
77 |
|
78 | This adds the model binding in the `<validator>` instance.
|
79 |
|
80 | `validation-style=""` (optional, default is `after-blur`), validation-styles:
|
81 |
|
82 | - `after-blur` (default): After first blur validation will be reactive.
|
83 | - `after-change`: After first change validation will be reactive, blurring an autofocus field with no input will not trigger this.
|
84 | - `after-submit`: After first submit validation will be reactive.
|
85 |
|
86 | ## Built-in validators
|
87 |
|
88 | There are a couple of built-in validators you can use.
|
89 |
|
90 | ### Required Validator
|
91 |
|
92 | To validate if a value is not `null`, `undefined` or empty-string.
|
93 |
|
94 | ### Is True Validator
|
95 |
|
96 | To validate a value (for example a checkbox) is set to true.
|
97 |
|
98 | ### Equal To Validator
|
99 |
|
100 | To validate a value is equal to the value of another input-field based on it's name attribute.
|
101 |
|
102 | ### Regex Validator
|
103 |
|
104 | To validate a value complies to a regex.
|
105 |
|
106 | ### Range Validator
|
107 |
|
108 | To validate a numeric value is in a range between.
|
109 |
|
110 | ### String-length Validator
|
111 |
|
112 | To validate a string value length is in a range between.
|
113 |
|
114 | ### Min-length Validator
|
115 |
|
116 | To validate a string value has a minimum length.
|
117 |
|
118 | ### Max-length Validator
|
119 |
|
120 | To validate a string is not longer than a maximum length.
|
121 |
|
122 | ## Creating custom validators
|
123 |
|
124 | It is possible to create your own validators, below is an example of a very simple custom validator.
|
125 |
|
126 | ### JavaScript
|
127 |
|
128 | ```JavaScript
|
129 | import { validator, BaseValidator } from 'vue-dotnet-validator';
|
130 |
|
131 | class MyCustomValidator extends BaseValidator {
|
132 | isValid(value) {
|
133 | return !value || value == 'Hello';
|
134 | }
|
135 | }
|
136 |
|
137 | const validators = {
|
138 | MyCustomValidator
|
139 | };
|
140 |
|
141 | Vue.component('validator', validator(validators));
|
142 | ```
|
143 |
|
144 | ### Cshtml
|
145 |
|
146 | To use this custom validator in your own form, make sure your custom .NET data annotation outputs a `data-val-mycustom="MESSAGE"` attribute on your `<input>` DOM node.
|
147 |
|
148 | ## Custom validators with additional parameters
|
149 |
|
150 | You can extend the features of your custom validators using additional data-attributes on your `<input>` tag. This is a feature supported in .NET.
|
151 | For an example on the usage of this feature, see `regexvalidator.js`.
|
152 |
|
153 | ## Publish a new version
|
154 |
|
155 | Make sure you have publish rights at the Q42 organisation on NPM.
|
156 |
|
157 | ```shell
|
158 | npm version [major|minor|patch]
|
159 | npm publish
|
160 | ```
|