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
Drop the remaining jQuery dependency from the published JavaScript
runtime and move the validation flow to native DOM APIs.
ClientSideValidations.enable(), validate(), isValid(), disable(), and
reset() now work with DOM elements and DOM collections instead of
jQuery objects. Validation callbacks and local validators also receive
native nodes, which keeps custom integrations aligned with the new
runtime surface.
Replace jQuery event wiring with native CustomEvent dispatch and
addEventListener hooks. Update visibility checks, dataset state,
uniqueness handling, and helper utilities so the runtime can traverse
forms and inputs without jQuery while preserving the existing
validation behavior.
Refresh the QUnit suite to build fixtures with plain DOM methods and
assert against native events and callback arguments. Regenerate the
bundled assets, switch the test harness to a neutral QUnit CDN, and
remove jquery from the package metadata.
Document the 24.0.0 breaking changes in the README and changelog, and
bump the gem and npm package versions for the release.
Please note that CSV depends on jQuery >= 3.7.1 (jQuery slim is fine).
59
+
ClientSideValidations no longer depends on jQuery.
60
+
If you previously installed `jquery-rails`, `jquery_ujs`, or custom jQuery startup code only for ClientSideValidations, you can remove that integration when upgrading to 24.x.
60
61
61
62
#### When using Webpacker ####
62
63
63
-
Make sure that you are requiring jQuery.
64
-
65
64
Add the following package:
66
65
67
66
```sh
@@ -92,42 +91,77 @@ detect `window.Turbolinks` and attach its event handlers.
92
91
93
92
#### When using Sprockets ####
94
93
95
-
Since ClientSideValidations can also be used via webpacker, it does not require
96
-
by default `jquery-rails` gem.
94
+
Add the following to your `app/assets/javascripts/application.js` file:
97
95
98
-
Make sure that `jquery-rails` is part of your bundled gems and `application.js`,
99
-
otherwise add:
96
+
```js
97
+
//= require rails.validations
98
+
```
100
99
101
-
```ruby
102
-
gem 'jquery-rails'
100
+
If you are using [Turbolinks](https://github.com/turbolinks/turbolinks),
101
+
make sure that `rails.validations` is required **after**`turbolinks`, so
102
+
ClientSideValidations can properly attach its event handlers.
103
+
104
+
If you need to copy the asset files from the gem into your project, run:
105
+
106
+
```
107
+
rails g client_side_validations:copy_assets
103
108
```
104
109
105
-
to your `Gemfile`, run `bundle`, and add
110
+
Note: If you run `copy_assets`, you will need to run it again each time you update this project.
111
+
112
+
## Migration Guide ##
113
+
114
+
### 24.x Breaking Changes ###
115
+
116
+
If you are upgrading to 24.x, update your integration code to use the `ClientSideValidations` object directly.
117
+
118
+
The old jQuery plugin methods are removed. Use the DOM-first public API instead:
106
119
107
120
```js
108
-
//= require jquery
121
+
ClientSideValidations.enable(form)
122
+
ClientSideValidations.validate(form)
123
+
ClientSideValidations.isValid(form, validators)
124
+
ClientSideValidations.disable(form)
125
+
ClientSideValidations.reset(form)
109
126
```
110
127
111
-
to your `app/assets/javascripts/application.js` file.
128
+
These methods accept native DOM elements and DOM collections. They do not accept jQuery objects or CSS selector strings.
112
129
113
-
Then, add the following to your `app/assets/javascripts/application.js` file
114
-
after `//= require jquery`.
130
+
Custom validators, form builders, and callbacks now receive native DOM nodes instead of jQuery wrappers. Update any custom code to use DOM APIs such as `.value`, `.form`, `.closest()`, and `querySelector()`.
131
+
Local validators are called as `(element, options)`. Form callbacks receive `(form, eventData)`, and element callbacks receive either `(element, message, callback)` or `(element, callback)` depending on the event.
115
132
116
-
```js
117
-
//= require rails.validations
133
+
All runtime-owned validation state attributes are now namespaced under `csv`. If you read or write these attributes in custom selectors, callbacks, or validators, update them to the scoped names:
If you are using [Turbolinks](https://github.com/turbolinks/turbolinks),
121
-
make sure that `rails.validations` is required **after**`turbolinks`, so
122
-
ClientSideValidations can properly attach its event handlers.
142
+
The matching dataset properties are `element.dataset.csvChanged`, `element.dataset.csvValid`, `element.dataset.csvValidate`, and `element.dataset.csvNotLocallyUnique`. `csvChanged` is stored as the string values `'true'` and `'false'`.
123
143
124
-
If you need to copy the asset files from the gem into your project, run:
144
+
**jQuery namespaced events are removed.** Events are now plain native DOM custom events. If your application listens to or unbinds events using jQuery-style namespacing, you must update those calls.
// store and pass the handler reference to removeEventListener when unbinding
128
158
```
129
159
130
-
Note: If you run `copy_assets`, you will need to run it again each time you update this project.
160
+
The full list of native events dispatched by ClientSideValidations: `form:validate:before`, `form:validate:after`, `form:validate:pass`, `form:validate:fail`, `element:validate:before`, `element:validate:after`, `element:validate:pass`, `element:validate:fail`.
161
+
162
+
If you are upgrading from a version older than 23.0.0, the `data-csv-*` renaming above is required for any custom code that still reads or writes the old attribute names. If you are already on 23.x, the new 24.x upgrade step is to update any local uniqueness integrations that still reference `data-not-locally-unique` or `element.dataset.notLocallyUnique`.
163
+
164
+
If your application vendors the compiled asset with `rails g client_side_validations:copy_assets`, run that generator again after upgrading so your copied asset matches the current jQuery-free bundle.
131
165
132
166
## Initializer ##
133
167
@@ -324,11 +358,11 @@ If you need to change the markup of how the errors are rendered you can modify t
Finally we need to add a client side validator. This can be done by hooking into the `ClientSideValidations.validator` object. Create a new file `app/assets/javascripts/rails.validations.customValidators.js`
The names of the callbacks should be pretty straight forward. For example, `ClientSideValidations.callbacks.form.fail` will be called if a form failed to validate. And `ClientSideValidations.callbacks.element.before` will be called before that particular element's validations are run.
452
486
453
-
All element callbacks will receive the element in a jQuery object as the first parameter and the eventData object as the second parameter. `ClientSideValidations.callbacks.element.fail()` will receive the message of the failed validation as the second parameter, the callback for adding the error fields as the third and the eventData object as the third. `ClientSideValidations.elementValidatePass()` will receive the callback for removing the error fields. The error field callbacks must be run in your custom callback in some fashion. (either after a blocking event or as a callback for another event, such as an animation)
487
+
All element callbacks receive the DOM element as the first parameter and the native event object as the second parameter. `ClientSideValidations.callbacks.element.fail()` receives the failed message as the second parameter, the callback for adding error fields as the third parameter, and the eventData object as the fourth parameter. `ClientSideValidations.callbacks.element.pass()` receives the callback for removing the error fields as the second parameter. The error field callbacks must still be invoked by your custom callback.
454
488
455
-
All form callbacks will receive the form in a jQuery object as the first parameter and the eventData object as the second parameter.
489
+
All form callbacks receive the DOM form element as the first parameter and the native event object as the second parameter.
456
490
457
-
Here is an example callback for sliding out the error message when the validation fails then sliding it back in when the validation passes:
491
+
Here is an example callback that animates the error message when validation fails:
458
492
459
493
``` javascript
460
-
// You will need to require 'jquery-ui' for this to work
Finally uncomment the `ActionView::Base.field_error_proc` override in `config/initializers/client_side_validations.rb`
@@ -506,22 +547,21 @@ By default, ClientSideValidations will automatically validate the form.
506
547
If for some reason you would like to manually validate the form (for example you're working with a multi-step form), you can use the following approach:
0 commit comments