-
Notifications
You must be signed in to change notification settings - Fork 25
Roadmap: Framework v1.3: Forms
The Form API includes two components, the Forms UI and the Forms JS Library. Together, they encompass a full range of form functionality, the former providing basic style needs, while the latter helps leverage device-specific functionality such as HTML 5 input types while still allowing all code to be XHTML MP compatible.
The Forms UI defines styling for forms at the basic, standard and full levels, and is available on any page that includes the CSS Handler. Additional styling of option inputs (radio and checkbox) and selects is provided by the JS Handler, but these should function in a reasonable way without the JS Handler as well (and on basic devices where the JS Handler cannot manipulate the DOM and thus shouldn't load this functionality), though without a specialized mobile appearance. It provides content providers with the ability to semantically define both general forms with any type of inputs to special form types like login and search with optimized layouts and icons.
The Forms JS Library is a Javascript library that is optionally included through the JS Handler. One of the core features of this library includes the ability to transfigure standard input types to HTML 5 input types on capable devices through DOM manipulation. Other features include validation of common input types, modal popups, tooltips, and placeholder text.
Development of Form API can occur in multiple stages, so long as all portions of Forms UI are implemented before any components of Forms JS Library.
There are three overarching levels of Forms UI delivery formats:
- form
- .content> form
- .content> * form
Element styling in Forms UI is a disjoint task, though their definitions must support all three delivery formats:
- input
- textarea
- select
- a.form-button
There are then also specialized form formats including login, search and for dates, also included in Forms UI.
After these tasks are completed, then the following Forms JS Library functionality should be considered:
- HTML 5 Input Types
- Validation
- Modal Feedback
- Tooltips
- Placeholder Text
These latter bits of functionality for the Forms JS Library may end up rolling over into Framework v1.4. However, all the features of the Forms UI need to be covered in Framework v1.3.
There are three primary ways a form may be delivered:
-
form - A tier-1 entity comparable to #header, _.content, _.menu, _.buttonand #footer. In this case, form> fieldset should be comparable to .content> *, where each fieldset creates a new content box that inputs, text areas, selects, labels and text content go within. Similarly, _formshould support the same header and sub header definitions as _.contentas formh1 and formh4. This should also include a non-padded version defined as form.full.not-padded as form by default are padded and behaves identically to _.content.
-
.content> form - A tier-2 entity within _.content. In MWF 1.1, .content> * is defined as a content box. However, _formshould not creates a content box; rather, content boxes should be created for elements defined as .content> form> *. In this case, the form itself should be able to cover multiple content boxes transparently, but should not need to cover every content box, allowing for multiple forms within one _.content. This definition of .content> form> * as content boxes allows for .content> form> fieldset or the usual .content> form> div and .content> form> p that should be synonymous with the respective .content> div and .content> p
-
.content> * form - A tier-3+ entity within a content box from .content> *. In this case, it is merely important that the styling properties for form inputs, text areas, selects, labels and text content are still styled appropriately, but that this behaves as a form contained completely within a single content box defined as .content > div.
The prototypes for these are described in the following sections. In all cases, the styling properties for form inputs, text areas, selects, labels and text content should remain consistent.
ASIDE: The initial proposal by UC San Diego includes a "Naked Form" style. This is not defined in the specification for Forms API, but optionally could be implemented as form.form-naked as a tier-1 entity like form.full defined above.
<form class="padded" action="#" method="post">
<h1 class="first">Title</h1>
<h4>Subtitle</h4>
<p>A content box with paragraph content.</p>
<div>
<p>One of multiple paragraphs defined within one content box (div).</p>
<p>Another of multiple paragraphs defined within one content box (div).</p>
</div>
<fieldset>
<p>One of multiple paragraphs defined within one content box (fieldset).</p>
<p>Another of multiple paragraphs defined within one content box (fieldset).</p>
</fieldset>
<fieldset>
<label for="input-1">Label for Input 1</label>
<input type="text" id="input-1" name="input-1">
<label for="textarea-1">Label for Textarea 1</label>
<textarea id="textarea-1" name="textarea-1"></textarea>
<label for="radio-1">Label for Radio 1</label>
<input type="radio" id="radio-1" name="radio-1">
<label for="checkbox-1">Label for Checkbox 1</label>
<input type="radio" id="checkbox-1" name="checkbox-1">
<label for="select-1">Label for Select 1</label>
<select id="select-1" name="select-1">
<option value="value-1">Value 1</option>
<option value="value-2">Value 2</option>
<option value="value-3">Value 3</option>
</select>
</fieldset>
<h4>Subtitle</h4>
<fieldset class="last">
<p>Some text that comes before the submission.</p>
<input type="submit">
<input type="reset">
</fieldset>
</form><div class="content">
<h1>Title</h1>
<h4>Subtitle</h4>
<p>A content box with paragraph content.</p>
<div>
<p>One of multiple paragraphs defined within one content box (div).</p>
<p>Another of multiple paragraphs defined within one content box (div).</p>
</div>
<form action="#" method="post">
<h4 class="first">Subtitle</h4>
<p>A content box with paragraph content.</p>
<div>
<p>One of multiple paragraphs defined within one content box (div).</p>
<p>Another of multiple paragraphs defined within one content box (div).</p>
</div>
<fieldset>
<p>One of multiple paragraphs defined within one content box (fieldset).</p>
<p>Another of multiple paragraphs defined within one content box (fieldset).</p>
</fieldset>
<fieldset>
<label for="input-1">Label for Input 1</label>
<input type="text" id="input-1" name="input-1">
<label for="textarea-1">Label for Textarea 1</label>
<textarea id="textarea-1" name="textarea-1"></textarea>
</fieldset>
<div>
<label for="radio-1">Label for Radio 1</label>
<input type="radio" id="radio-1" name="radio-1">
<label for="checkbox-1">Label for Checkbox 1</label>
<input type="radio" id="checkbox-1" name="checkbox-1">
<label for="select-1">Label for Select 1</label>
<select id="select-1" name="select-1">
<option value="value-1">Value 1</option>
<option value="value-2">Value 2</option>
<option value="value-3">Value 3</option>
</select>
</div>
<h4>Subtitle</h4>
<fieldset class="last">
<p>Some text that comes before the submission.</p>
<input type="submit">
<input type="reset">
</fieldset>
</form>
<p>A content box with paragraph content.</p>
<div>
<p>One of multiple paragraphs defined within one content box (div).</p>
<p>Another of multiple paragraphs defined within one content box (div).</p>
</div>
</div><div class="content">
<h1>Title</h1>
<h4>Subtitle</h4>
<p>A content box with paragraph content.</p>
<div>
<p>One of multiple paragraphs defined within one content box (div).</p>
<p>Another of multiple paragraphs defined within one content box (div).</p>
</div>
<div>
<form action="#" method="post">
<p class="first">This and all the below form elements should be within one content box.</p>
<fieldset>
<label for="input-1">Label for Input 1</label>
<input type="text" id="input-1" name="input-1">
<label for="textarea-1">Label for Textarea 1</label>
<textarea id="textarea-1" name="textarea-1"></textarea>
<fieldset>
</fieldset>
<label for="radio-1">Label for Radio 1</label>
<input type="radio" id="radio-1" name="radio-1">
<label for="checkbox-1">Label for Checkbox 1</label>
<input type="radio" id="checkbox-1" name="checkbox-1">
<label for="select-1">Label for Select 1</label>
<select id="select-1" name="select-1">
<option value="value-1">Value 1</option>
<option value="value-2">Value 2</option>
<option value="value-3">Value 3</option>
</select>
</fieldset>
<p>Some text that comes before the submission.</p>
<input type="submit">
<input type="reset" class="last">
</form>
</div>
<p>A content box with paragraph content.</p>
<div>
<p>One of multiple paragraphs defined within one content box (div).</p>
<p>Another of multiple paragraphs defined within one content box (div).</p>
</div>
</div>The input element has four basic types:
- Textual: text, password
- Option: radio, checkbox
- Hidden: hidden
- Controls: submit, reset, button
The WCSS specification, a subset of CSS2, includes the type selector (CSS 2 Sec 5.4). As such, we can rely on the input[type] selector to define style differences between different input types.
The text and password types should meet the following criteria:
(1) Text alignment
The input on a text or password type should default to left aligned text (except as below).
(2) Full width
The input on a text or password type should be defined as full width.
(3) Text size
User agents often define their own size definition for text. Text size should thus be defined concretely to override this and use em measurements that conform to the rest of the page style.
(4) Labels
Labels for text and password inputs should appear above the item following the label conventions defined elsewhere in this document.
The radio and checkbox types can take the user agent style definition for basic, which should attempt to define some base properties to establish consistency where browsers allow these option inputs styled. However, it is recognized that some browsers do not allow these to be styled through CSS without Javascript manipulation, and Forms UI for MWF 1.3 does not need to account for this. Long term, however, the Forms API does intend to support this, though it shall be addressed in MWF 1.4 or beyond (see "Forms 1.4+ Improvements").
Labels for stand-alone checkbox and radio inputs should appear as a block-level element above the item following the label conventions defined elsewhere in this document.
There should also be the ability to cluster a set of radio buttons or checkboxes under a single label, and then each of them also gets their own label, still compliant with the left/right conventions above. The prototype for this is:
<label>Label for the Radio Set</label>
<div class="option right">
<label for="radio-opt-1">Label for First Radio</label>
<input type="radio" name="fieldname[]" id="radio-opt-1">
<br />
<label for="radio-opt-2">Label for Second Radio</label>
<input type="radio" name="fieldname[]" id="radio-opt-2">
</div>The option div tag can also have justify class instead of right which will align the label to the left of the screen and the radio to the right of the screen.
The hidden input type must not be displayed in any context.
The general case for controls is button, and as such, that shall be defined first in this document.
The button should support three different styles (coloring) for different types of buttons:
- input[type=button].primary
- input[type=button].secondary
- input[type=button].neutral
A set of a elements should also be defined with the same block rendering properties:
- a.form-button.primary
- a.form-button.secondary
- a.form-button.neutral
This set is actually the recommended approach for buttons since buttons otherwise require Javascript to direct the user properly. However, the button versions should also be defined and are what is referenced throughout this specification, though in the final documentation, the a.form-button is actually going to be the documented and referenced way to style buttons since their link property works when Javascript does not.
A use case for these three styles might be the case of a "submit" as primary, a "reset" as secondary, and a "info" as neutral. The recommended approach for these would be input[type=submit].primary, _input[type=reset].secondary, and _a.form-button.neutral. However, they apply in a generic setting as well.
The reason for these is to create user expectations based on three distinct style (such as blue, silver, and gray). As such, the input[type=submit] should default to the primary style, the input[type=reset] should default to the secondary style, and the a.form-button should default to the neutral style. However, in all cases, a definition of .primary, .secondary or .neutral on a input[type=submit], input[type=reset] or a.form-button should override the default.
By default, each button should be placed on its own line and have partial width.
Controls should support additional display options similar to .button:
- div.button input should create an appearance similar to the div.button general behavior where it appends one or two inputs into a full-width button. Support for three buttons within a div.button is not necessary as it is not supported by the usual div.button class at this time.
- input.button should create a single full-width button, rather than a partial width button.
Controls should not have associated labels.
The textarea element should behave in roughly the same way as the input textual types. However, as opposed to the input textual types, it should not allow for text alignment qualifiers, but rather always align text to the left. This leaves the following requirements for the textarea element:
(1) Full width
The textarea should be defined as a full width block element.
(2) Text size and font family
User agents often define their own size and font family definition for textarea. Text size should thus be defined concretely to override this and use em measurements that conform to the rest of the page style.
(3) Labels
Labels for textarea elements should appear above the item following the label conventions defined elsewhere in this document.
The select element can take the user agent style definition for basic.
For standard and full, they should be defined in a manner that conforms with input textual element styling in terms of font-size, alignment and full width. It is recognized that not all browsers support styling select elements, but that a base set should be defined nonetheless.
Further, for more robust styling where possible by the JS handler, DOM manipulation may be allowed, though this is left to implementation to determine if this is necessary (as opposed to input option types where this is utterly necessary for ideal styling of the element).
By default, labels should appear as full-width elements.
Each label should be defined above the element it relates to and should include a for attribute that references the id attribute of the associated user input option. Labels should be expected for textual and option inputs, textareas, and selects, but not for control or hidden inputs.
Further, label should default to left aligned text.
Text size should be defined explicitly as slightly smaller than the rest of the page.
In general, a required style should be expressed simply by appending the class .required to the label.
The mark should generally be inserted after the label, because we want these labels left-aligned.
When a validation error occurs, provide visual cues to tell the user what happened, how to fix it, and how to move on. The visual cues should include:
- Top-level message that indicates an error has occurred, and that it needs to be resolved before continuing.
- Visual indication to identify the field responsible for error by:
- Change the input border to red
- Change the label text to red
- Display inline error text (full width) below input field in red
- Display error icon (Red triangle/warning) to the left of the inline error text
An example of using validation error styles.
<div class="content">
<h1>Title</h1>
<div class="message error">
An error occurred while processing your request.
Please resolve it before continuing.
</div>
<form action="#" method="post">
<label for="input-1" class="required invalid">Label for Input 1</label>
<input type="text" id="input-1" name="input-1" class="invalid">
<p class="invalid">This field is required</p>
<label for="textarea-1" class="required invalid">Label for Textarea 1</label>
<textarea id="textarea-1" name="textarea-1" class="invalid">
<p class="invalid">This field is required</p>
<label for="select-1" class="required invalid">Label for Select 1</label>
<select id="select-1" name="select-1" class="invalid">
<option value="value-1">Value 1</option>
<option value="value-2">Value 2</option>
<option value="value-3">Value 3</option>
</select>
<p class="invalid">This field is required</p>
<input type="submit">
<input type="reset">
</form>
</div>Several specialized forms should be made available that have specific prototypes and can be leveraged for pre-defined styling. They should be compliant with all three form delivery formats, though they may be implemented slightly differently between the three.
The search form should be defined as form.form-search.
This form should include:
- a single input[type=text] element
- a single input[type=submit] element
This form should support three alignments:
- form.form-search.left that left orients their elements and text alignments
- form.form-search.center that centers their elements and text alignments
- form.form-search.right that right orients their elements and text alignments
The prototype for the form.padded delivery format is:
<form class="padded form-search" action="#" method="post">
<input type="text">
<input type="submit">
</form>In the form delivery format, it should also support form h1 and form.padded for this prototype:
<form class="form-full form-search form-padded" action="#" method="post">
<h1>Search Box Title</h1>
<input type="text">
<input type="submit">
</form>These prototypes should produce a single content box.
In the other two approaches, it should integrate with div.content-full as described in the form delivery formats section.
The login form should be defined as form.form-login.
This form should include:
- a single input[type=text] element for the username
- a single input[type=password] element for the password
- a single input[type=submit] element for login
Optionally, this form should also support:
- a label for both the input[type=text] and the input[type=password]
- a single a.form-button.register for a registration link that renders like input[type=button]
- a single a.form-button.forgot for a forgot password link that renders like input[type=button]
- a single h1 for the login box header
- one or more p for login box description
The prototype for the form.form-full delivery format is:
<form class="form-full form-search" action="#" method="post">
<input type="text">
<input type="submit">
</form>In the form.form-full delivery format, it should also support form.form-full h1 and form.form-full.form-padded for this prototype, as well as all the optionals as follows:
<form class="form-full form-search" action="#" method="post">
<h1>Login Box Title</h1>
<p>Some text</p>
<input type="text">
<input type="password">
<input type="submit">
<a href="#" class="form-button register">Register</a>
<a href="#" class="form-button forgot">Forgot Password</a>
<p>Some more text</p>
</form>These prototypes should produce a single content box.
In the other two approaches, it should integrate with div.content-full as described in the form delivery formats section.
As opposed to some of the others specialized forms described here, this is actually a specialized format form a form "element" rather than for the form as a whole. There are three types of date selection, each that require a different set of internal elements (note that they should all be defined within the three form formats only so that these classes can be used outside without conflict):
- form div.date: select.day plus select.month plus select.year
- form div.month: select.month plus select.year
- form div.week: select.week plus select.year
Each one of these should include a single label that is before any of the select elements within the DOM and references the first select element of the set. In all cases, the select elements should produce the same sort of values as their HTML 5 counterparts, though client-side processing will have to handle the differences.
The prototype for the form div.date-field is:
<div class="date-field">
<label for="day-1">date</label>
<select type="text" class="day" id="day-1">…</select>
<select type="text" class="month">...</select>
<select type="text" class="year">...</select>
</div>The prototype for the form div.month-field is:
<div class="month-field">
<label for="month-1">month</label>
<select type="text" class="month" id="month-1">...</select>
<select type="text" class="year">...</select>
</div>The prototype for the form div.week-field is:
<div class="week-field">
<label for="week-1">week</label>
<select type="text" class="week" id="week-1">...</select>
<select type="text" class="year">...</select>
</div>Note that, if date, month or week is defined, then the Form JS Library will transfigure this entry into a single input[type=date], input[type=month] or input[type=week] entry, so the content provider will need to consider this on a form submission.
When this transfiguration occurs, the element takes a name that is a concatenated version of the names of the select fields that formerly represented it. When the value of these HTML5 fields are changed, the value are also changed in the original fields.
HTML 5 input field support centers around the class .input-field, along with additional classes that define the type of input field that is considered. These exist as it is not beneficial to always fall back to input[type=text] if a new type is not available. Doing so will produce results in an unexpected state, whereas they may be better controlled through select or special form formats in many cases.
HTML 5 input field support comes in two phases:
- Input Type Transformations
- onBlur synchronization
In all browsers with Javascript event support, onSubmit, if a form includes any .[input]-field elements, those elements should be transformed into the data format that the HTML 5 input type produces. This means that, with the exception of basic and minimally-capable standard devices, all responses using the .[input]-field class produce results that are in the HTML 5 style, even if the HTML 5 support is not actually there.
Input type transformations, meanwhile, occur where a browser supports the HTML 5 input type in question. Since some browsers support some types but not other types, it should not be assumed that all will be transformed on a given device. However, given the onSubmit transformations, the data format can be assumed, except for basic devices. Currently, the following input types are transformed to if the device supports it:
- number
- search
- color
- tel
- url
- date
- datetime
- datetime-local
- time
- month
- week
This functionality makes the following transformations in data format and in input type:
- input[type=text].search-field to input[type=search]
- form.form-search input[type=text] to input[type=search]
- select.number-field. to input[type=number]
- select.range-field to input[type=range]
- input[type=text].color-field to input[type=color]
- input[type=text].tel-field to input[type=tel]
- input[type=text].url-field to input[type=url]
- input[type=text].email-field to input[type=email]
- div.date-field to input[type=date]
- div.month-field to input[type=month]
- div.week-field to input[type=week]
These transformations are divided into three sets, input[type=text], select and div. The input[type=text] is meant for those elements that can otherwise be entered as text entries and submit as such, while the select is meant for those where otherwise the select box should contain a comparable set of options. In many of the select transformations, the values within the select field should be used to set minimum and maximum values on the HTML 5 input types. The div transformations are similar, except entail more than one underlying select field, and should be referred to in the Forms UI > Special Forms > Date Selection section.
In all cases, the transformation should remove the class definition that caused the transformation. This allows for CSS definitions that provide specialized styling for the input[type=text], select and div elements with these classes that will disappear when the input is transformed to one of the HTML 5 types.
The HTML 5 input types warrant styling considerations, targetable as input[type=…].
However, more scoping is necessary to determine exactly how each should be styled.
The MWF capability library will be used to detect HTML 5 Type support.
Elements should be modified on onDOMContentLoaded, as the JS Handler should make this functionality available in the HEAD rather than waiting until onReady. As with other functionality in MWF that operates at onDOMContentLoaded, however, a qualifier should exist that loads it at onReady if the onDOMContentLoaded event does not fire.
Further, for type data format transformations, onBlur listener events will need to be attached to form transformed elements and the value synchronized with the form elements with .[input]-field.
Eventually, this library should also transform the input[type=text] and select elements into elements with specialized appearance based on their type in browsers that do not support the HTML 5 type that they would otherwise be transformed to. An example of this are the sliders, color pickers, date pickers and others that are common in other Javascript UI libraries.
As such, the transformation function that transforms these elements into their HTML 5 counterparts should be designed in such a way that, if they do not support the HTML 5 input type, instead they can make a different sort of transformation where possible. However, actually implementing these transformations is outside the scope of Forms 1.2.
To use Forms JS, include the following JavaScript. Only the Full classification devices are supported.
if (mwf.classification.isFull()) {
mwf.forms.init();
}Client-side validation library can provide a better user experience. The downside is the bandwidth requirement to download the client-side validation library. The number of HTTP request can be reduced unless the actual validation logic calls a server side logic. Our goal should be a light weight validation library that takes advantage of existing HTML markups and performs a set of often used validation logic.
Currently, we're using jQuery Validation Plugin 1.9.0 from http://bassistance.de/jquery-plugins/jquery-plugin-validation/.
The earlier the better, but not obtrusive. We could check on each keyup (too often) or on each form submit (too late). A good balance is to trigger the validation on the onblur event. There will also be cases when a field cannot be validated until a form is submitted, such as required fields. So we should trigger the validation on the onSubmit event. Finally, client-side validation is a means to enhance user experience, one must still perform server-side validation.
Using existing HTML markups (as suggested in HTML 5 Input Type section), we can determine attributes about a field (input, textarea or select):
- required
- number
- date
- url
If there is any validation error, the validation library will change the appropriate field's CSS class to notify the end user. On for submit, the validation library will stop the form submit and display the validation error.
Note that date client-side validation is a mere format matching. 8888-8888-8888 is just as valid as 2011-12-31.
Since mobile screen real-estate is limited, we only want to show tooltips when the user has requested so.
The framework will provide a tooltip icon that when pressed, a tooltip will appear. The tooltip will be in a form of a bubble or modal dialog box, but will never leave the current form page. All the data the user has entered will be intact when the users closes the bubble or the modal dialog box.
We're using jQuery tooltip from jQuery Tools v1.2.6 at http://flowplayer.org/tools/. Since tooltip does not require HTML5 or CSS3, this functionality is available at the standard classification level. Put the tool tip next to the label:
<label for="input-11" class="required">Tooltip</label><span class="tiptext">Tip text goes here</span>
<input type="text" id="input-11" name="input-11" />The javascript to initialize the tooltip functionality.
mwf.tooltip();In basic device, the tooltip will always be shown. In standard and full devices, the tooltip will be shown once the tip icon is clicked or hovered.
On browsers that supports Placeholder text, the javascript will take a div element that contains placeholder class name and the id "placeholder-[element id name]" and will put the placeholder text in the matching element id.
<label>Search</label>
<input type="text" />
<span class="placeholder">Enter search value</span>Some features have been forestalled for MWF 1.3 or beyond. However, in an effort to provide a long-term outlook on these features, they are listed below.
For standard and full, they should be defined with images that create a more "mobile" look. This requires DOM manipulation through Javascript and should be included as part of the JS Handler default Javascript for standard and full devices.
(1) Checkbox
The checkbox input type should support the following appearances for standard and full:
- input[type=checkbox].check :: A checkmark that is a standard "check"
- input[type=checkbox].cross :: A checkmark that is an X
- input[type=checkbox].box :: A box that is either crossed or checked.
- input[type=checkbox].circle :: A circle that is either crossed or checked.
The checkbox should default to the behavior defined as input[type=checkbox].box.checked.
(2) Radio
The radio input type should support the following appearances for standard and full:
- input[type=radio].circle :: A circle that is either up (unselected) or depressed (selected).
- input[type=radio].box :: A box that is either up (unselected) or depressed (selected).
- input[type=radio].yesno :: A box that has a "Yes" and "No" like on the iPhone for two options.
- input[type=radio].yesno.button-full :: The .yesno box, but the full width across the screen.
The radio should default to the behavior defined as input[type=radio].circle.