You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This Ember CLI addon aims to provide a simple form validation feature. It also includes a simple async button that
4
-
is aims to be used with forms for better user experience.
3
+
This Ember CLI addon provides a simple form validation feature, aligned with the HTML5 spec. It also includes a simple async ``button`` component that aims to be used with forms for better user experience.
5
4
6
-
## Major limitations
5
+
## Browser Support
7
6
8
-
This addon is mostly targeted to simple forms (for now). But more importantly, it's only supported in browsers
9
-
that support built-in form validation (IE10+, Firefox 4+, Chrome 10+, Safari 5+, Opera 10.1+). For older IE versions,
10
-
you may use the [H5F polyfill](https://github.com/ryanseddon/H5F).
7
+
This addon is mostly targeted to simple forms (for now). But more importantly, it's only supported in browsers that support built-in form validation (IE10+, Firefox 4+, Chrome 10+, Safari 5+, Opera 10.1+). For older IE versions, you may use the [H5F polyfill](https://github.com/ryanseddon/H5F).
11
8
12
9
## Installation
13
10
@@ -17,7 +14,7 @@ Add the following line to your `package.json`:
17
14
"ember-cli-html5-validation": "0.0.*",
18
15
```
19
16
20
-
## Future work
17
+
## Future Work
21
18
22
19
* Better integration with Ember Data
23
20
* Being able to customize more easily templates
@@ -27,25 +24,23 @@ Add the following line to your `package.json`:
27
24
28
25
### Basics
29
26
30
-
This addon automatically adds validation feature to input, radio, checkbox and text areas, without any change. If
31
-
you add the following code:
27
+
This addon automatically adds validation to ``input``, ``radio``, ``checkbox``, and ``textarea`` form controls without any change. If you add the following code:
32
28
33
29
```html
34
-
{{input required='required'}}
30
+
{{input required=true}}
35
31
```
36
32
37
-
It will automatically adds an error message if you focus out from the field with an empty value, or when you submit
38
-
the form. All built-in HTML5 validation rules are supported. For instance:
33
+
This addon will automatically add an error message when the user focuses out from the field with an empty value, or when the user submits the form. All built-in HTML5 validation rules are supported. For instance:
39
34
40
35
```html
41
36
<!-- Make sure the input is required and is a valid email -->
By default, this addon comes with predefined error messages for each error ([see here](https://github.com/maestrooo/ember-cli-html5-validation/blob/master/addon/mixins/validatable-input.js#L33),
@@ -73,13 +68,13 @@ ValidatableInput.reopen({
73
68
});
74
69
```
75
70
76
-
The browser messages have the advantage of being translated, please note however that each browser have their
77
-
own messages, so you must not rely on those if you want the same messages in all browser.
71
+
The browser messages have the advantage of being translated. Please note, however, that each browser have their own messages, so you must not rely on those if you want the same messages in all browser.
78
72
79
-
#### Custom messages
73
+
**Note**: if you declare ``title`` attributes on your ``required`` input fields, their respective ``title`` values will be appended to the browser error messages.
80
74
81
-
You can use the "title" attribute on form to define a message that will be shown if validation fail. This is standard
82
-
on the spec for "pattern" messages, but I decided to extend it to any validation. For instance:
75
+
#### Custom Error Messages
76
+
77
+
The easiest way to customize your inputs' error messages is by adding the ``title``. Adding the ``title`` attribute on your form input controls will cause a message of the ``title``'s value to be shown if validation fail. This is standard on the spec for "pattern" messages, but this addon extends it to any validation. For instance:
83
78
84
79
```html
85
80
<!-- This will show "You must accept agreements" if checkbox is not checked}}
@@ -88,99 +83,111 @@ on the spec for "pattern" messages, but I decided to extend it to any validation
88
83
89
84
### Validatable forms
90
85
91
-
While you can now have built-in validation for inputs, what we want is actually being able to prevent form submission,
92
-
automatically scrolling to first field that fail...
86
+
While you can now have built-in validation for inputs, what we want is actually to prevent form submission, automatically scrolling to first field that fails validation.
93
87
94
88
To do that, you must wrap your inputs around the `validatable-form` component:
{{input id="last-name" title="Please provide a last name" value=lastName required=true}}
104
100
</div>
105
101
106
-
<input type="submit"}}
102
+
<button type="submit" title="Verify account information, and continue to profile setup">Verify and Continue</button>
107
103
{{/validatable-form}}
108
104
```
109
105
110
-
If you submit the form, Ember CLI HTML5 Validation will automatically run validation on each field, showing the
111
-
input error, and automatically scrolling to the first error. If error happen, no form submission will happen.
106
+
When the user submits the form, Ember CLI HTML5 Validation will automatically run validation on each field, showing any input errors and automatically scrolling to the first error. **Form submission will be prevented if *any* errors are encountered**.
112
107
113
-
On the other hand, if validation passes, an action will be sent to the action defined in the `validatable-form`
114
-
component.
108
+
On the other hand, if validation passes, an action will be sent to the action defined in the `validatable-form` component.
115
109
116
110
### Using with Ember-Data
117
111
118
-
This addon offers native integration with Ember-Data. To do this, you only need to pass the `model` attribute to
119
-
the validatable form:
112
+
This addon offers native integration with Ember-Data. To do this, you only need to pass the `model` attribute to the validatable form:
{{input id="last-name" title="Please provide a last name" value=lastName required=true}}
129
124
</div>
130
125
131
-
<input type="submit"}}
126
+
<button type="submit" title="Verify account information, and continue to profile setup">Verify and Continue</button>
132
127
{{/validatable-form}}
133
128
```
134
129
135
-
This will provide two things:
130
+
This will:
131
+
132
+
* Send the ``model`` along with the action (``save`` in this case)
133
+
* Extract any *server-side* errors.
134
+
135
+
When client validation successfully passes, the assigned ``action`` is bubbled up. In case of errors that are returned by server, Ember CLI HTML5 Validation will automatically extract errors (assuming that errors hash is formatted properly) and will show them along corresponding fields.
136
+
137
+
Server-side errors, in the case of the ``RESTAdapter`` or ``ActiveModelAdapter`` will typically be in the form of a nested ``Array`` in the place of the field:
138
+
139
+
*Response from server with validation messages*
140
+
141
+
```json
142
+
{
143
+
"user": {
144
+
"firstName": ["First name must be present"],
145
+
"lastName": ["Last name must be present"]
146
+
}
147
+
}
148
+
```
136
149
137
-
* The model will be send along the action.
138
-
* It also extracts server-side errors.
150
+
For more information on ``DS.Errors``, [please refer to the Ember documentation](http://emberjs.com/api/data/classes/DS.Errors.html); a working example [can be found here](http://jsfiddle.net/L96Mb/10/light/).
139
151
140
-
When client validation successfully passes, the action is submitted. In case of errors that are returned by server,
141
-
Ember CLI HTML5 Validation will automatically extracts errors (assuming that errors hash is formatted properly) and
142
-
will show them along corresponding fields.
152
+
**Note**: on some Ember-Data adapters, you may need to configure creation of ``DS.InvalidError`` object on failure (this is done out of the box if you are using ActiveModel Adapter). Furthermore, you must add an "id" on each input, that is the dasherized version of the property. For instance, if your server returns the following payload:
143
153
144
-
For this to work, you must configure Ember-Data to properly creates a DS.InvalidError object on failure (this is done
145
-
out of the box if you are using ActiveModel Adapter). Furthermore, you must add an "id" on each input, that is the
146
-
dasherized version of the property. For instance, if your server returns the following payload:
154
+
**Example of expected error response from ``ActiveModelAdapter``**
147
155
148
156
```json
149
157
{
150
-
"errors": {
151
-
"first_name": [
152
-
"Your First Name is not valid (lol)"
153
-
]
158
+
"user": {
159
+
"errors": {
160
+
"first_name": [
161
+
"Your First Name is not valid (lol)"
162
+
]
163
+
}
164
+
}
154
165
}
155
166
}
156
167
```
157
168
158
-
Your input must have an id whose value is "first-name".
169
+
In this case, the input must have an ``id`` whose value is "first-name".
159
170
160
-
> This is currently a bit hacky and I want to make this more efficient / allow to work on associations.
171
+
> This is currently a bit "hacky" and we want to make this more efficient / allow to work on associations.
161
172
162
173
### Cookbook
163
174
164
175
#### Dependent field
165
176
166
-
If you have an input that is required only if a checkbox is checked, you can do that:
177
+
If you have an input that is required only if a checkbox is checked, you can do this:
While this library is mostly aims to perform quick validations with minimal overhead, HTML5 allows you to provide
176
-
custom logic and set custom message by calling the `setCustomValidity` method on your input. When you call this method,
177
-
an `invalid` event will be triggered and the `ValidatableInput` will automatically show it.
186
+
While this library serves mostly to perform quick validations with minimal overhead, HTML5 allows you to provide custom logic and to set custom messages by calling the `setCustomValidity` method on your input. When you call this method, an `invalid` event will be triggered, and the `ValidatableInput` will automatically show it.
178
187
179
188
### Async Button
180
189
181
-
Ember-CLI-HTML5-Validation now comes with a minimal async button. This component can be used for your forms to provide
182
-
immediate feedback when the form is submitting, and then comes into an error or success state. Whenever it enters into
183
-
error or success state, it will transition back to initial state after 1.5s.
190
+
Ember-CLI-HTML5-Validation now comes with a minimal ``async`` button. This component can be used for your forms to provide immediate feedback when the form is submitting, and then comes into an ``error`` or ``success`` state. Whenever the form enters into an ``error`` or ``success`` state, this addon will transition the form back to its initial state after 1.5s.
184
191
185
192
Here are the classes added to the button depending on the status:
186
193
@@ -192,7 +199,27 @@ You can override the default template by setting your own template for the `asyn
0 commit comments