parsley: update

parsley.md

@@ -1,83 +1,57 @@
 ---
 title: Parsley.js
-layout: default-ad
+updated: 2017-10-19
+weight: -1
+layout: 2017/sheet
+keywords:
+  - "data-parsley-validate"
+  - "$('#form').parsley()"
+  - errorClass
+  - successClass
+  - classHandler
+  - errorsContainer
+  - errorsWrapper
+  - errorTemplate
+intro: |
+  [Parsley](http://parsleyjs.org/doc/) provides frontend form validation.
 ---
 
+## Parsley
+{: .-three-column}
+
 ### Enabling
 
+#### via HTML
+
 ```html
-<form data-parsley-validate> <!-- not preferred -->
+<form data-parsley-validate>
+<!-- not preferred -->
 ```
 
+#### via JavaScript
+
 ```js
 $('#form').parsley(/* options */)
 ```
 
-### [Options](http://parsleyjs.org/doc/annotated-source/defaults.html)
+It's preferrable to explictly call `$.fn.parsley()`.
 
-```js
-// Supported & excluded inputs by default
-  inputs: 'input, textarea, select'
-  excluded: 'input[type=button], input[type=submit], input[type=reset], input[type=hidden]'
+### API
 
-// Stop validating field on highest priority failing constraint
-  priorityEnabled: true
-```
-
-### Options (Field only)
-
-```js
-// identifier used to group together inputs (e.g. radio buttons…)
-  multiple: null
-
-// identifier (or array of identifiers) used to validate only a select group of inputs
-  group: null
-```
-
-### Options (UI)
-
-```js
-// Enable\Disable error messages
-  uiEnabled: true
-
-// Key events threshold before validation
-  validationThreshold: 3
-
-// Focused field on form validation error. ‘first’|’last’|’none’
-  focus: 'first'
-
-// $.Event() that will trigger validation. eg: keyup, change…
-  trigger: false
-
-// Class that would be added on every failing validation Parsley field
-  errorClass: 'parsley-error'
-  successClass: 'parsley-success'
-
-// 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'
-  classHandler: function (ParsleyField) {}
-
-// Return the $element where errors will be appended Could also be (and given directly from DOM) a valid selector like '#div'
-  errorsContainer: function (ParsleyField) {}
-
-// ul elem that would receive errors’ list
-  errorsWrapper: '<ul class="parsley-errors-list"></ul>'
-
-// li elem that would receive error message
-  errorTemplate: '<li></li>'
-```
-
-### Form API
+#### Form
 
 ```js
 $('#myform').parsley()
-  .isValid()  // true or null
+  .isValid()  // → true | null
   .validate()
-
   .reset()
   .destroy()
+```
 
+#### Input
+
+```js
 $('#myform input').parsley()
-
   .isValid()
   .validate() // returns errors
 ```
@@ -86,38 +60,235 @@ $('#myform input').parsley()
 
 ```html
 <input ...>
+```
 
+#### Required
+
+```html
   required
-  type='email'
+```
 
+#### 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'
+```
 
-  type='url'
-  data-parsley-type='url'
+#### Range
 
-  maxlength='6'
-  data-parsley-maxlength='6'
-  minlength='10'
-  data-parsley-minlength='10'
+```html
+  type='range'
+  data-parsley=range='[6, 10]'
+```
 
+```html
   max='10'
   data-parsley-max='10'
   min='6'
   data-parsley-min='6'
+```
 
-  type='range'
-  data-parsley=range='[6, 10]'
-
-  pattern='\d+'
-  data-parsley-pattern='\d+'
+#### Checkboxes
 
+```html
   data-parsley-mincheck='1'
   data-parsley-maxcheck='3'
   data-parsley-check='[1, 3]'
+```
 
+#### Confirmation
+
+```html
   data-parsley-equalto='#confirm'
 ```
+
+## Options
+
+### Form options
+
+```js
+// Supported & excluded inputs by default
+  inputs: 'input, textarea, select'
+  excluded: 'input[type=button], input[type=submit], input[type=reset], input[type=hidden]'
+```
+
+```js
+// Stop validating field on highest priority failing constraint
+  priorityEnabled: true
+```
+
+See: [Options](http://parsleyjs.org/doc/annotated-source/defaults.html)
+
+### Field options
+
+```js
+// identifier used to group together inputs
+// (e.g. radio buttons…)
+  multiple: null
+```
+
+```js
+// identifier (or array of identifiers) used to
+// validate only a select group of inputs
+  group: null
+```
+
+These options are only available for fields.
+
+### UI Options
+
+```js
+// Enable/disable error messages
+  uiEnabled: true
+```
+
+```js
+// Key events threshold before validation
+  validationThreshold: 3
+```
+
+```js
+// Focused field on form validation error. ‘first’|’last’|’none’
+  focus: 'first'
+```
+
+```js
+// $.Event() that will trigger validation. eg: keyup, change…
+  trigger: false
+```
+
+```js
+// Class that would be added on every failing validation
+// Parsley field
+  errorClass: 'parsley-error'
+  successClass: 'parsley-success'
+```
+
+```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'
+  classHandler: function (ParsleyField) {}
+```
+
+```js
+// Return the $element where errors will be appended.
+// Could also be (and given directly from DOM) a valid
+// selector like '#div'
+  errorsContainer: function (ParsleyField) {}
+```
+
+```js
+// ul elem that would receive errors’ list
+  errorsWrapper: '<ul class="parsley-errors-list"></ul>'
+```
+
+```js
+// li elem that would receive error message
+  errorTemplate: '<li></li>'
+```
+
+## Examples
+
+### Custom container
+
+```js
+$('[data-parsley]').parsley({
+  errorsContainer (field) {
+    return field.$element.closest('.block, .control')
+  }
+})
+```
+
+Appends the error to the closest `.block` or `.control`.
+
+### Custom markup
+
+```js
+$('[data-parsley]').parsley({
+  errorClass: '-error',
+  successClass: '-success',
+
+  errorsWrapper: '<ul class="parsley-error-list"></ul>',
+  errorTemplate: '<li class="parsley-error"></li>'
+})
+```
+
+Uses custom markup.
+
+### Custom fields
+
+```js
+$('[data-parsley]').parsley({
+  classHandler (field) {
+    const $parent = field.$element.closest('.input-group')
+    if ($parent.length) return $parent
+
+    return field.$element
+  }
+})
+```
+
+Applies the `errorClass` and `successClass` to the closest `.input-group`, if available.
+
+### Custom validator
+
+#### HTML
+
+```html
+<input type='text' data-parsley-multiple-of='3' />
+```
+
+#### JavaScript
+
+```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'
+    }
+  })
+```
+
+See: [Custom validators](http://parsleyjs.org/doc/index.html#custom)
+
+## Also see
+
+- [Parsley documentation](http://parsleyjs.org/doc/) _(parsleyjs.org)_