# Form validation

Questions or comments?

## Purpose

This component provides generic validation and error message handling for Web forms.

The Merge Server-Client errors functionality allows the merging of server error from an application with client errors .

## Use when

- Web forms

## Working example

English:

- Form Validation
- Merge Server-Client Errors

French:

- Validation de formulaires
- Fusion des erreurs Serveur-Client

## How to implement

1. Add `class="wb-frmvld"` to a `div` element surrounding the `form` element

       <div class="wb-frmvld">
       	<form action="#" method="get" id="validation-example">
       	...
       	</form>

2. Optional: Wrap each form field name with `<span class="field-name">...</span>`. This specifies the prefix to use for the error message summary.

       <label for="fname1">
       	<span class="field-name">First Name</span> <strong class="required">(required)</strong>
       </label>

3. Add `required="required"` to each mandatory form field

       <input id="fname1" name="fname1" type="text" required="required" />

4. Optional: For input fields, add one of these options for specialized validation.

5. Optional: For ASP validators add the following attributes to enable the Merge Server-Client errors functionality

   `Display="Dynamic" EnableClientScript="false" CssClass="label label-danger wb-server-error"`

## Configuration options

Option | Description | How to configure | Values
--- | --- | --- | ---
`hdLvl` | Heading level for error summary. | Add `"hdLvl": "headingLevel"` to the `data-wb-frmvld` attribute or `window[ "wb-frmvld" ]` where `headingLevel` is the heading level. Use the following JavaScript code instead to configure all instances of the plugin: `window[ "wb-frmvld" ] = {"hdLvl": "headingLevel"};`. | `h2` (default): Heading level 2 `h3`: Heading level 3 `h4`: Heading level 4 `h5`: Heading level 5 `h6`: Heading level 6
`ignore` | Selector identifying the fields to ignore. | Add `"ignore": "selector"` to the `data-wb-frmvld` attribute or `window[ "wb-frmvld" ]` where `selector` is a valid jQuery selector. Use the following JavaScript code instead to configure all instances of the plugin: `window[ "wb-frmvld" ] = {"ignore": ".ignore"};`. | `:hidden` (default): All hidden fields `.ignore`: All fields with the `ignore` class Empty string ("") None of the fields

### Specialized validation

Add specialized validation to an input field by applying the following options.

Option | Validation type
--- | ---
`data-rule-alphanumeric="true"` | Alphanumeric
`data-rule-cifES="true"` | CIF code (Spain)
`data-rule-creditcard="true"` | Credit card number
`type="date"` | Date
`type="date" data-rule-dateISO="true"` | Date (ISO)
`type="date" data-rule-dateITA="true"` | Date (Italy)
`type="number"` | Digits only
`type="email"` | Email
`data-rule-equalTo="#x"` | Equal to field with id = "x"
`data-rule-lettersonly="true"` | Letters only
`data-rule-letterswithbasicpunc="true"` | Letters and basic punctuation only (allowed punctuation: [.])
`data-rule-maxlength="x"` | Maximum length of x
`max="x"` | Maximum number x
`data-rule-maxWords="x"` | Maximum of x words
`data-rule-minlength="x"` | Minimum length of x
`data-rule-strippedminlength="x"` | Minimum length of x (when HTML tags are removed)
`min="x"` | Minimum number x
`data-rule-minWords="x"` | Minimum of x words
`data-rule-nieES="true"` | NIE code (Spain)
`data-rule-nifES="true"` | NIF code (Spain)
`data-rule-nowhitespace="true"` | No white space
`data-rule-postalCodeCA="true"` | Postal code (Canada)
`data-rule-rangelength="[x,y]"` | Range (number)
`data-rule-rangelength="[x,y]"` | Range length x to y
`data-rule-rangeWords="[x,y]"` | Range of x to y words
`type="tel" data-rule-phoneUK="true"` | Telephone number (UK)
`type="tel" data-rule-mobileUK="true"` | Mobile number (UK)
`type="tel" data-rule-phoneUS="true"` | Telephone number (US)
`type="time"` | Time
`type="url"` | URL (IPv4)
`type="url" data-rule-ipv6="true"` | URL (IPv6)
`type="url" data-rule-url2="true"` | URL (TLD optional)
`data-rule-vinUS="true"` | Vehice Identification Number (VIN, US)
`data-rule-require_from_group='[1,".group"]'` | Validates the minimum number of fields within an group (each input requires the validation rule). The minium and group is defined by the options passed (number being the minium and a common class for each input).

See jQuery Validation Plugin - Documentation for more details.

### Merge Server-Client errors functionality

If you want to concatenate the server errors with the client errors, add the following attributes to each ASP validator:

`Display="Dynamic" EnableClientScript="false" CssClass="label label-danger wb-server-error"`

Asp Validator examples:

    <asp:CustomValidator ID="TypeOfPrestationCv" ErrorMessage = "Your server error message" ControlToValidate="TypeOfPrestation" OnServerValidate="TypeOfPrestationCvServer"
    Display="Dynamic" EnableClientScript="false" Cssclass="label label-danger wb-server-error" runat="server"></asp:CustomValidator>

    <asp:RequiredFieldValidator ID="TypeOfPrestationRfv" ErrorMessage = "Your server error message" ControlToValidate="TypeOfPrestation"
    Display="Dynamic" EnableClientScript="false" CssClass="label label-danger wb-server-error" runat="server"></asp:RequiredFieldValidator>

ASP.Net Web Form Demo1 - Source Code on GitHub

- Demo1.aspx
- Demo1.aspx.cs
- wbDisplayErrors.ascx (When Javascript is disabled)
- wbDisplayErrors.ascx.cs
- wbCheckBoxList.ascx
- wbCheckBoxList.ascx.cs
- wbRadioButtonList.ascx
- wbRadioButtonList.ascx.cs
- Resources.resx
- Resources.fr.resx
- Common.js

## Events

Document the public events that can be used by implementers or developers.

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-frmvld` | Triggered manually (e.g., `$( ".wb-frmvld" ).trigger( "wb-init.wb-frmvld" );`). | Used to manually initialize the form validation. Note: The Form validation plugin will be initialized automatically unless the form elements are added after the page has already loaded.
`wb-ready.wb-frmvld` (v4.0.5+) | Triggered automatically after form validation initializes. | Used to identify the element where form validation has initialized (target of the event)
    $( document ).on( "wb-ready.wb-frmvld", ".wb-frmvld", function( event ) {
    });
    $( ".wb-frmvld" ).on( "wb-ready.wb-frmvld", function( event ) {
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

See jQuery Validation Plugin - Documentation for details about events specific to jQuery Validation.

## Source code

Form validation source code on GitHub

Date modified:
  2018-07-04