SemanSemantic-UItic-UI/server/documents/modules/form.html.eco

---
layout      : 'default'
css         : 'form'

element     : 'form'
elementType : 'behavior'

title       : 'Form Validation'
description : 'A form validation behavior checks user input data against a set of criteria before passing along the data 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="peek">
    <div class="ui vertical pointing secondary menu">
      <a class="active item">Usage</a>
      <a class="item">Behavior</a>
      <a class="item">Settings</a>
    </div>
  </div>
  <div class="ui active tab" data-tab="usage">

    <h2 class="ui dividing header">Usage</h2>

    <div class="example">
      <h3 class="ui header">Validation Definitions</h3>
      <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>

    <h3 class="ui header">
      Types of Validation Rules
      <div class="sub header">Validation rules are a set of conditions required to validate a field</div>
    </h3>
    <div class="ui info message">Validation rules are found in <code>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 class="ui tab" data-tab="examples">
    <div class="dropdown example">
      <h3 class="ui header">Validating Dropdowns</h3>
      <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">
      <h3 class="ui header">Displaying Error Messages</h3>
      <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">
      <h3 class="ui header">Validating on Blur and other Events</h3>
      <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">
      <h3 class="ui header">Creating Custom Validation</h3>
      <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 <code>$('.foo').form('behavior name', argumentOne, argumentTwo)</code>

    <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>

    <h3 class="ui header">
      Form Settings
      <div class="sub header">Form settings modify the form validation behavior</div>
    </h3>

    <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 class="ui horizontal divider"><i class="icon setting"></i></div>

    <h3 class="ui header">
      Callbacks
      <div class="sub header">Callbacks specify a function to occur after a specific behavior.</div>
    </h3>

    <table class="ui celled 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 class="ui horizontal divider"><i class="icon setting"></i></div>

    <h3 class="ui header">
      Templates
      <div class="sub header">Templates are used to construct elements</div>
    </h3>
    <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 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 class="ui horizontal divider"><i class="icon setting"></i></div>

    <h3 class="ui header">
      DOM Settings
      <div class="sub header">DOM settings specify how this module should interface with the DOM</div>
    </h3>
    <table class="ui celled 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 class="ui horizontal divider"><i class="icon setting"></i></div>

    <h3 class="ui header">
      Debug Settings
      <div class="sub header">Debug settings controls debug output to the console</div>
    </h3>

    <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>