From 7aafc9b66985d0fc76246730c1d812e9641cb4ba Mon Sep 17 00:00:00 2001 From: scottjehl Date: Wed, 1 Dec 2010 09:38:16 -0500 Subject: [PATCH] documented auto-init (and prevention of auto-init) of form controls --- docs/forms/docs-forms.html | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/forms/docs-forms.html b/docs/forms/docs-forms.html index 40673931..6e20bca4 100755 --- a/docs/forms/docs-forms.html +++ b/docs/forms/docs-forms.html @@ -34,6 +34,28 @@

Markup Conventions

When constructing forms to be used in jQuery Mobile, most of the standard guidelines used to create forms that submit via normal HTTP post or get still apply. However, one thing to keep in mind is that the id attributes of form controls need to be not only unique on a given page, but also unique across the pages in a site. This is because jQuery Mobile's single-page navigation model allows many different "pages" to be present in the DOM at the same time, so you must be careful to use unique id attributes so there will be only one of each in the DOM (and of course, be sure to pair them properly with label elements via the for attribute).

+

Auto-initialization of form elements

+

By default, jQuery Mobile will automatically enhance certain native form controls into rich touch-friendly components. This is handled internally by finding form elements by tag name and running a plugin method on them, so for instance, a select element will be found and initialized with the "selectmenu" plugin, while an input element with a type="checkbox" will be enhanced with the "checkboxradio" plugin. Once initialized, you can address these enhanced components programmatically through their jQuery UI widget API methods (see documentation on available methods here: Form Plugin Methods).

+ +

Preventing auto-initialization of form elements

+

If you'd prefer that a particular form control be left untouched by jQuery Mobile, simply give that element the attribute data-role="none". For example:

+ 
				
+<label for="foo">
+<select name="foo" id="foo" data-role="none">
+	<option value="a" >A</option>
+	<option value="b" >B</option>
+	<option value="c" >C</option>
+</select>
+
+ + +

Or, if you'd like to prevent auto-initialization without adding attributes to your markup, you can customize the selector that is used for preventing auto-initialization by setting the page plugin's keepNative option (which defaults to "[data-role="none"]. Be sure to configure this option inside an event handler bound to the mobileinit event, so that it applies to the first page as well as subsequent pages that are loaded.

+ 

+$(document).bind('mobileinit',function(){
+	$.mobile.page.prototype.options.keepNative = "[data-role='none'], .foo, .bar";
+});	
+
+

Dynamic form layout

In jQuery Mobile, all form elements are designed to be a flexible width so they will comfortably fit the width of any mobile device. One optimization built into the framework is that we present labels and form elements differently based on screen width.