2015-11-06 05:32:00 +00:00
|
|
|
|
---
|
|
|
|
|
title: Parsley.js
|
2020-07-04 13:33:09 +00:00
|
|
|
|
updated: 2018-12-06
|
2017-10-19 02:50:51 +00:00
|
|
|
|
weight: -1
|
2018-12-06 22:15:40 +00:00
|
|
|
|
category: JavaScript libraries
|
2017-10-19 02:50:51 +00:00
|
|
|
|
keywords:
|
|
|
|
|
- "data-parsley-validate"
|
|
|
|
|
- "$('#form').parsley()"
|
|
|
|
|
- errorClass
|
|
|
|
|
- successClass
|
|
|
|
|
- classHandler
|
|
|
|
|
- errorsContainer
|
|
|
|
|
- errorsWrapper
|
|
|
|
|
- errorTemplate
|
|
|
|
|
intro: |
|
|
|
|
|
[Parsley](http://parsleyjs.org/doc/) provides frontend form validation.
|
2015-11-06 05:32:00 +00:00
|
|
|
|
---
|
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
## Parsley
|
|
|
|
|
{: .-three-column}
|
|
|
|
|
|
2017-10-19 02:55:15 +00:00
|
|
|
|
### Installing via NPM
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
npm install --save parsleyjs
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
[parsleyjs](https://www.npmjs.com/package/parsleyjs) is the Parsley form validator. ('parsley' is a different package)
|
|
|
|
|
|
2015-11-06 05:32:00 +00:00
|
|
|
|
### Enabling
|
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
#### via HTML
|
|
|
|
|
|
2015-11-06 05:32:00 +00:00
|
|
|
|
```html
|
2017-10-19 02:50:51 +00:00
|
|
|
|
<form data-parsley-validate>
|
2017-10-19 02:55:15 +00:00
|
|
|
|
<!-- ✗ not preferred -->
|
2015-11-06 05:32:00 +00:00
|
|
|
|
```
|
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
#### via JavaScript
|
|
|
|
|
|
2015-11-06 05:32:00 +00:00
|
|
|
|
```js
|
|
|
|
|
$('#form').parsley(/* options */)
|
|
|
|
|
```
|
|
|
|
|
|
2017-10-22 11:08:21 +00:00
|
|
|
|
It's preferable to explicitly call `$.fn.parsley()`.
|
2017-10-19 02:50:51 +00:00
|
|
|
|
|
|
|
|
|
### API
|
|
|
|
|
|
|
|
|
|
#### Form
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
$('#myform').parsley()
|
|
|
|
|
.isValid() // → true | null
|
|
|
|
|
.validate()
|
|
|
|
|
.reset()
|
|
|
|
|
.destroy()
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Input
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
$('#myform input').parsley()
|
|
|
|
|
.isValid()
|
|
|
|
|
.validate() // returns errors
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Validators
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
<input ...>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Required
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
required
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Types
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
type='email'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
type='url'
|
|
|
|
|
data-parsley-type='url'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Length
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
maxlength='6'
|
|
|
|
|
data-parsley-maxlength='6'
|
|
|
|
|
minlength='10'
|
|
|
|
|
data-parsley-minlength='10'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Numeric
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
pattern='\d+'
|
|
|
|
|
data-parsley-pattern='\d+'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
type='number'
|
|
|
|
|
data-parsley-type='number'
|
|
|
|
|
data-parsley-type='integer'
|
|
|
|
|
data-parsley-type='digits'
|
|
|
|
|
data-parsley-type='alphanum'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Range
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
type='range'
|
|
|
|
|
data-parsley=range='[6, 10]'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
max='10'
|
|
|
|
|
data-parsley-max='10'
|
|
|
|
|
min='6'
|
|
|
|
|
data-parsley-min='6'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Checkboxes
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
data-parsley-mincheck='1'
|
|
|
|
|
data-parsley-maxcheck='3'
|
|
|
|
|
data-parsley-check='[1, 3]'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Confirmation
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
data-parsley-equalto='#confirm'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Options
|
|
|
|
|
|
|
|
|
|
### Form options
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
// Supported & excluded inputs by default
|
|
|
|
|
inputs: 'input, textarea, select'
|
|
|
|
|
excluded: 'input[type=button], input[type=submit], input[type=reset], input[type=hidden]'
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
2015-11-06 05:32:00 +00:00
|
|
|
|
// Stop validating field on highest priority failing constraint
|
|
|
|
|
priorityEnabled: true
|
|
|
|
|
```
|
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
See: [Options](http://parsleyjs.org/doc/annotated-source/defaults.html)
|
|
|
|
|
|
|
|
|
|
### Field options
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
|
|
|
|
```js
|
2017-10-19 02:50:51 +00:00
|
|
|
|
// identifier used to group together inputs
|
|
|
|
|
// (e.g. radio buttons…)
|
2015-11-06 05:32:00 +00:00
|
|
|
|
multiple: null
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
|
|
|
|
// identifier (or array of identifiers) used to
|
|
|
|
|
// validate only a select group of inputs
|
2015-11-06 05:32:00 +00:00
|
|
|
|
group: null
|
|
|
|
|
```
|
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
These options are only available for fields.
|
|
|
|
|
|
|
|
|
|
### UI Options
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
|
|
|
|
```js
|
2017-10-19 02:50:51 +00:00
|
|
|
|
// Enable/disable error messages
|
2015-11-06 05:32:00 +00:00
|
|
|
|
uiEnabled: true
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
2015-11-06 05:32:00 +00:00
|
|
|
|
// Key events threshold before validation
|
|
|
|
|
validationThreshold: 3
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
2015-11-06 05:32:00 +00:00
|
|
|
|
// Focused field on form validation error. ‘first’|’last’|’none’
|
|
|
|
|
focus: 'first'
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
2015-11-06 05:32:00 +00:00
|
|
|
|
// $.Event() that will trigger validation. eg: keyup, change…
|
|
|
|
|
trigger: false
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
|
|
|
|
// Class that would be added on every failing validation
|
|
|
|
|
// Parsley field
|
2015-11-06 05:32:00 +00:00
|
|
|
|
errorClass: 'parsley-error'
|
|
|
|
|
successClass: 'parsley-success'
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
|
|
|
|
// Return the $element that will receive these above
|
|
|
|
|
// success or error classes. Could also be (and given
|
|
|
|
|
// directly from DOM) a valid selector like '#div'
|
2015-11-06 05:32:00 +00:00
|
|
|
|
classHandler: function (ParsleyField) {}
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
|
|
|
|
// Return the $element where errors will be appended.
|
|
|
|
|
// Could also be (and given directly from DOM) a valid
|
|
|
|
|
// selector like '#div'
|
2015-11-06 05:32:00 +00:00
|
|
|
|
errorsContainer: function (ParsleyField) {}
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
2015-11-06 05:32:00 +00:00
|
|
|
|
// ul elem that would receive errors’ list
|
|
|
|
|
errorsWrapper: '<ul class="parsley-errors-list"></ul>'
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
2015-11-06 05:32:00 +00:00
|
|
|
|
// li elem that would receive error message
|
|
|
|
|
errorTemplate: '<li></li>'
|
|
|
|
|
```
|
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
## Examples
|
|
|
|
|
|
|
|
|
|
### Custom container
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
|
|
|
|
```js
|
2017-10-19 02:50:51 +00:00
|
|
|
|
$('[data-parsley]').parsley({
|
|
|
|
|
errorsContainer (field) {
|
|
|
|
|
return field.$element.closest('.block, .control')
|
|
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
Appends the error to the closest `.block` or `.control`.
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
### Custom markup
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
|
|
|
|
$('[data-parsley]').parsley({
|
|
|
|
|
errorClass: '-error',
|
|
|
|
|
successClass: '-success',
|
|
|
|
|
|
|
|
|
|
errorsWrapper: '<ul class="parsley-error-list"></ul>',
|
|
|
|
|
errorTemplate: '<li class="parsley-error"></li>'
|
|
|
|
|
})
|
2015-11-06 05:32:00 +00:00
|
|
|
|
```
|
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
Uses custom markup.
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
### Custom fields
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
|
|
|
|
$('[data-parsley]').parsley({
|
|
|
|
|
classHandler (field) {
|
|
|
|
|
const $parent = field.$element.closest('.input-group')
|
|
|
|
|
if ($parent.length) return $parent
|
|
|
|
|
|
|
|
|
|
return field.$element
|
|
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
Applies the `errorClass` and `successClass` to the closest `.input-group`, if available.
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
### Custom validator
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
#### HTML
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```html
|
|
|
|
|
<input type='text' data-parsley-multiple-of='3' />
|
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
#### JavaScript
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
```js
|
|
|
|
|
window.Parsley
|
|
|
|
|
.addValidator('multipleOf', {
|
|
|
|
|
// string | number | integer | date | regexp | boolean
|
|
|
|
|
requirementType: 'integer',
|
|
|
|
|
|
|
|
|
|
// validateString | validateDate | validateMultiple
|
|
|
|
|
validateNumber (value, requirement) {
|
|
|
|
|
return 0 === value % requirement
|
|
|
|
|
},
|
|
|
|
|
|
|
|
|
|
messages: {
|
|
|
|
|
en: 'This value should be a multiple of %s'
|
|
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
```
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
See: [Custom validators](http://parsleyjs.org/doc/index.html#custom)
|
2015-11-06 05:32:00 +00:00
|
|
|
|
|
2017-10-19 02:50:51 +00:00
|
|
|
|
## Also see
|
|
|
|
|
|
|
|
|
|
- [Parsley documentation](http://parsleyjs.org/doc/) _(parsleyjs.org)_
|