|
|
---layout : 'default'css : 'form'
element : 'form'elementType : 'behavior'
title : 'Form Validation'description : 'A form validation behavior checks data against a set of criteria before passing it along to the server'
type : 'UI Behavior'---
<script src="/build/uncompressed/definitions/behaviors/form.js"></script><script src="/javascript/validate-form.js"></script>
<%- @partial('header', { tabs: { usage: 'Usage', examples: 'Examples', settings: 'Settings'} }) %>
<div class="main container">
<div class="ui active tab" data-tab="usage">
<h2 class="ui dividing header">Usage</h2>
<div class="example"> <h4 class="ui header">Validation Definitions</h4> <p>Form validation requires passing in a validation object with the rules required to validate your form.</p> <div class="ui info message"> <i class="help icon"></i>A validation object includes a list of form elements, and rules to validate each against. Fields are matched by either the <code>id</code> tag, <code>name</code> tag, or the <code>data-validate</code> metadata matching the identifier provided in the settings object. </div> <div class="ignore code"> $('.ui.form') .form({ name: { identifier : 'name', rules: [ { type : 'empty', prompt : 'Please enter your name' } ] }, gender: { identifier : 'gender', rules: [ { type : 'empty', prompt : 'Please select a gender' } ] }, username: { identifier : 'username', rules: [ { type : 'empty', prompt : 'Please enter a username' } ] }, password: { identifier : 'password', rules: [ { type : 'empty', prompt : 'Please enter a password' }, { type : 'length[6]', prompt : 'Your password must be at least 6 characters' } ] } terms: { identifier : 'terms', rules: [ { type : 'checked', prompt : 'You must agree to the terms and conditions' } ] } }) ; </div> <div class="ui form segment"> <p>Tell Us About Yourself</p> <div class="two fields"> <div class="field"> <label>Name</label> <input placeholder="First Name" name="name" type="text"> </div> <div class="field"> <label>Gender</label> <div class="ui selection dropdown"> <input type="hidden" name="gender"> <div class="default text">Gender</div> <i class="dropdown icon"></i> <div class="menu"> <div class="item" data-value="male">Male</div> <div class="item" data-value="female">Female</div> </div> </div> </div> </div> <div class="field"> <label>Username</label> <input placeholder="Username" name="username" type="text"> </div> <div class="field"> <label>Password</label> <input type="password" name="password"> </div> <div class="inline field"> <div class="ui checkbox"> <input type="checkbox" name="terms" /> <label>I agree to the terms and conditions</label> </div> </div> <div class="ui blue submit button">Submit</div> </div> </div>
<div class="no example"> <h4 class="ui header"> Validation Rules </h4> <p>Validation rules are a set of conditions required to validate a field</p> <div class="ui info message">Validation rules are found in <code>$.fn.form.settings.rules</code>, to add new global validation rules, modify <code>$.fn.form.settings.rules</code> to include your function.</div> <div class="in red message">To pass parameters to a rule, use bracket notation in your settings object. For example <code>type: 'not[dog]'</code></div> <table class="ui teal celled sortable definition table"> <thead> <th class="four wide">Name</th> <th>Arguments</th> <th>Description</th> </thead> <tbody> <tr> <td>empty</td> <td>value</td> <td>Checks whether a field is empty</td> </tr> <tr> <td>email</td> <td>value</td> <td>Checks whether a field is a valid email address</td> </tr> <tr> <td>length</td> <td>value</td> <td>Checks whether a field is longer than a length</td> </tr> <tr> <td>not</td> <td>value, notValue</td> <td>Checks whether a field is not a value</td> </tr> <tr> <td>contains</td> <td>value, text</td> <td>Checks whether a field contains text</td> </tr> <tr> <td>is</td> <td>value, text</td> <td>Checks whether a field matches a value</td> </tr> <tr> <td>maxLength</td> <td>value</td> <td>Checks whether a field is less than a max length</td> </tr> <tr> <td>match</td> <td>value, fieldIdentifier</td> <td>Checks whether a field matches another field</td> </tr> <tr> <td>url</td> <td>value</td> <td>Checks whether a field is a url</td> </tr> <tr> <td>checked</td> <td>-</td> <td>Checks whether a checkbox field is checked</td> </tr> </tbody> </table> </div> </div> <div class="ui tab" data-tab="examples">
<h2 class="ui dividing header">Examples</h2> <div class="dropdown example"> <h4 class="ui header">Validating Dropdowns</h4> <p><a href="/modules/dropdown.html">Dropdowns</a> can also be validated like other form fields. Simply match the validation rule to the hidden input associated with the dropdown</p> <div class="ignored code"> $('.ui.dropdown') .dropdown() ; $('.ui.form') .form({ gender: { identifier : 'gender', rules: [ { type : 'empty', prompt : 'Please enter a gender' } ] }, name: { identifier : 'name', rules: [ { type : 'empty', prompt : 'Please enter your name' } ] }, }) ; </div> <div class="ui form"> <div class="two fields"> <div class="field"> <label>Name</label> <input type="text" name="name"> </div> <div class="field"> <label>Gender</label> <div class="ui fluid selection dropdown"> <input type="hidden" name="gender"> <div class="default text">Gender</div> <i class="dropdown icon"></i> <div class="menu"> <div class="item" data-value="1">Male</div> <div class="item" data-value="0">Female</div> </div> </div> </div> </div> <div class="ui blue submit button">Submit</div> </div> </div> <div class="example"> <h4 class="ui header">Displaying Error Messages</h4> <p>Forms that contain a <a href="/elements/message.html">ui message</a> error block will automatically be filled in with form validation information.</p> <div class="ui ignored info message">The template for error messages can be modified by adjusting settings.template.error</div>
<div class="ui form segment"> <p>Let's go ahead and get you signed up.</p> <div class="two fields"> <div class="field"> <label>First Name</label> <input placeholder="First Name" name="first-name" type="text"> </div> <div class="field"> <label>Last Name</label> <input placeholder="Last Name" name="last-name" type="text"> </div> </div> <div class="field"> <label>Username</label> <input placeholder="Username" name="username" type="text"> </div> <div class="field"> <label>Password</label> <input type="password" name="password"> </div> <div class="inline field"> <div class="ui checkbox"> <input type="checkbox" name="terms" /> <label>I agree to the Terms and Conditions</label> </div> </div> <div class="ui blue submit button">Submit</div> <div class="ui error message"></div> </div> </div>
<div class="inline example"> <h4 class="ui header">Validating on Blur and other Events</h4> <p>Validation messages can also appear inline. UI Forms automatically format <a href="/elements/label.html">labels</a> with the class name <code>prompt</code>. These validation prompts are also set to appear on input change instead of form submission.</p> <div class="ui ignored warning message">This example also uses a different validation event. Each element will be validated on input blur instead of the default form submit.</div> <div class="code" data-type="javascript"> $('.ui.dropdown') .form(validationRules, { inline : true, on : 'blur' }) ; </div> <div class="ui form segment"> <p>Let's go ahead and get you signed up.</p> <div class="two fields"> <div class="field"> <label>First Name</label> <input placeholder="First Name" name="first-name" type="text"> </div> <div class="field"> <label>Last Name</label> <input placeholder="Last Name" name="last-name" type="text"> </div> </div> <div class="field"> <label>Username</label> <input placeholder="Username" name="username" type="text"> </div> <div class="field"> <label>Password</label> <input type="password" name="password"> </div> <div class="inline field"> <div class="ui checkbox"> <input type="checkbox" name="terms" /> <label>I agree to the Terms and Conditions</label> </div> </div> <div class="ui blue submit button">Submit</div> </div> </div>
<div class="dog example"> <h4 class="ui header">Creating Custom Validation</h4> <p>You can use multiple arbitrary rules to validate a form</p> <div class="ignore code"> $('.ui.form') .form({ dog: { identifier: 'dog', rules: [ { type: 'empty', prompt: 'You must have a dog to add' }, { type: 'contains[fluffy]', prompt: 'I only want you to add fluffy dogs!' }, { type: 'not[mean]', prompt: 'Why would you add a mean dog to the list?' } ] } }) ; </div> <div class="ui form segment"> <p>Let's go ahead and get you signed up.</p> <div class="field"> <label>Dog</label> <input placeholder="Dog" name="dog" type="text"> </div> <div class="ui blue submit button">Add Dog <i class="add icon"></i></div> <div class="ui error message"></div> </div> </div>
</div>
<div class="ui tab" data-tab="settings"> <h2 class="ui dividing header">Behavior</h2>
All the following <a href="/module.html#/behavior">behaviors</a> can be called using the syntax
<div class="code" data-type="javascript"> $('.foo').form('behavior name', argumentOne, argumentTwo) </div>
<table class="ui definition celled table"> <tr> <td>submit</td> <td>Submits selected form</td> </tr> <tr> <td>validate form</td> <td>Validates form and calls onSuccess or onFailure</td> </tr> <tr> <td>get change event</td> <td>gets browser property change event</td> </tr> <tr> <td>get field(id)</td> <td>Returns element with matching name, id, or data-validate metadata to ID</td> </tr> <tr> <td>get validation(element)</td> <td>Returns validation rules for a given field</td> </tr> <tr> <td>has field(identifier)</td> <td>Returns whether a field exists</td> </tr> <tr> <td>add errors(errors)</td> <td>Adds errors to form, given an array errors</td> </tr> </table>
<h2 class="ui dividing header">Settings</h2>
<div class="no example"> <h4 class="ui header"> Form Settings </h4> <p>Form settings modify the form validation behavior</p>
<table class="ui celled sortable definition table"> <thead> <th>Setting</th> <th class="four wide">Default</th> <th>Description</th> </thead> <tbody> <tr> <td>keyboardShortcuts</td> <td>true</td> <td>Adds keyboard shortcuts for enter and escape keys to submit form and blur fields respectively</td> </tr> <tr> <td>on</td> <td>submit</td> <td>Event used to trigger validation. Can be either <b>submit</b>, <b>blur</b> or <b>change</b>.</td> </tr> <tr> <td>revalidate</td> <td>true</td> <td>If set to true will revalidate fields with errors on input change</td> </tr> <tr> <td>delay</td> <td>true</td> <td>Delay from last typed letter to validate a field when using <code>on: change</code> or when revalidating a field.</td> </tr> <tr> <td>inline</td> <td>false</td> <td>Adds inline error on field validation error</td> </tr> <tr> <td>transition</td> <td> scale </td> <td>Named transition to use when animating validation errors. Fade and slide down are available without including <a href="/modules/transition.html">ui transitions</a></td> </tr> <tr> <td>duration</td> <td>150</td> <td>Animation speed for inline prompt</td> </tr> </tbody> </table> </div> <div class="no example"> <h4 class="ui header"> Callbacks </h4> <p>Callbacks specify a function to occur after a specific behavior.</p>
<table class="ui celled sortable definition table"> <thead> <th class="four wide">Setting</th> <th>Context</th> <th>Description</th> </thead> <tbody> <tr> <td>onValid</td> <td>field</td> <td>Callback on each valid field</td> </tr> <tr> <td>onInvalid</td> <td>field</td> <td>Callback on each invalid field</td> </tr> <tr> <td>onSuccess</td> <td>form</td> <td>Callback if a form is all valid</td> </tr> <tr> <td>onFailure</td> <td>form</td> <td>Callback if any form field is invalid</td> </tr> </tbody> </table> </div> <div class="no example"> <h4 class="ui header"> Templates </h4> <p>Templates are used to construct elements</p> <div class="ui ignored info message">Templates are found in <code>settings.template</code>, to modify templates across all forms, modify <code>$.fn.form.settings.templates</code> to include your function. They must return html.</div> <table class="ui celled sortable definition table"> <thead> <th class="four wide">Template</th> <th>Arguments</th> <th>Description</th> </thead> <tbody> <tr> <td>error</td> <td>Errors (Array)</td> <td>Constructs the contents of an error message</td> </tr> <tr> <td>prompt</td> <td>Errors (Array)</td> <td>Constructs an element to prompt the user to an invalid field</td> </tr> </tbody> </table> </div>
<div class="no example"> <h4 class="ui header"> DOM Settings </h4> <p>DOM settings specify how this module should interface with the DOM</p> <table class="ui celled sortable definition table"> <thead> <th>Setting</th> <th class="six wide">Default</th> <th>Description</th> </thead> <tbody> <tr> <td>namespace</td> <td>form</td> <td>Event namespace. Makes sure module teardown does not effect other events attached to an element.</td> </tr> <tr> <td>selector</td> <td> <div class="code"> selector : { message : '.error.message', field : 'input, textarea, select', group : '.field', input : 'input', prompt : '.prompt', submit : '.submit' } </div> </td> <td>Selectors used to match functionality to DOM</td> </tr> <tr> <td>metadata</td> <td> <div class="code">
metadata : { validate: 'validate' }, </div> </td> <td> HTML5 metadata attributes </td> </tr> <tr> <td>className</td> <td> <div class="code"> className : { active : 'active', placeholder : 'default', disabled : 'disabled', visible : 'visible' } </div> </td> <td>Class names used to attach style to state</td> </tr> </tbody> </table> </div> <div class="no example"> <h4 class="ui header"> Debug Settings </h4> <p>Debug settings controls debug output to the console</p>
<table class="ui celled sortable definition table"> <thead> <th>Setting</th> <th class="four wide">Default</th> <th>Description</th> </thead> <tbody> <tr> <td>name</td> <td>Form</td> <td>Name used in debug logs</td> </tr> <tr> <td>debug</td> <td>True</td> <td>Provides standard debug output to console</td> </tr> <tr> <td>performance</td> <td>True</td> <td>Provides standard debug output to console</td> </tr> <tr> <td>verbose</td> <td>True</td> <td>Provides ancillary debug output to console</td> </tr> <tr> <td>errors</td> <td colspan="2"> <div class="code"> errors : { method : 'The method you called is not defined.' } </div> </td> </tr> </tbody> </table> </div> </div>
</div>
|
