You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>jQuery Mobile provides a complete set of finger-friendly form elements that are based on native HTML form elements.</p>
23
-
23
+
24
24
<h2>Form structure</h2>
25
-
25
+
26
26
<p>All forms should be wrapped in a <code>form</code> tag that has an <code>action</code> and <code>method</code> that will handle the form data processing on the server.</p>
<p>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 <code>select</code> element will be found and initialized with the "selectmenu" plugin, while an <code>input</code> element with a <code>type="checkbox"</code> 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: <ahref="plugin-eventsmethods.html">Form Plugin Methods</a>). </p>
40
-
40
+
41
41
<h2>Preventing auto-initialization of form elements</h2>
42
42
<p>If you'd prefer that a particular form control be left untouched by jQuery Mobile, simply give that element the attribute <code>data-role="none"</code>. For example:</p>
<p>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 <code>keepNative</code> option (which defaults to <code>"[data-role="none"]</code>. Be sure to configure this option inside an event handler bound to the <code>mobileinit</code> event, so that it applies to the first page as well as subsequent pages that are loaded.</p>
<p>One special case is that of selects. The above sample will prevent any and all augmentation from taking place on select elements in the page if <code>select</code> is included. If you wish to retain the native performance, look/feel of the menu itself and benefit from the visual augmentation of the select button by jQuery Mobile you can set $.mobile.nativeSelectMenu to true in a <code>mobileinit</code> callback as a global setting or use <code>data-native="true"</code> on a case by case basis.</p>
61
+
60
62
<h2>Dynamic form layout</h2>
61
63
62
64
<p>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. </p>
63
-
<p>If a page is fairly narrow (~480px), the labels are styled as block-level elements so they will stack on top of the form element to save horizontal space.</p>
65
+
<p>If a page is fairly narrow (~480px), the labels are styled as block-level elements so they will stack on top of the form element to save horizontal space.</p>
64
66
<p>On wider screens, the labels and form elements are styled to be on the same line in a 2-column layout to take advantage of the screen real estate.</p>
65
67
66
68
<h2>Field containers</h2>
67
-
69
+
68
70
<p>To improve the styling to labels and form elements on wider screens, we recommend wrapping a <code>div</code> or <code>fieldset </code>with the <code>data-role="fieldcontain"</code> attribute around each label/form element. The framework will add a thin vertical bottom border on this container to act as a field separator and visually align the label and form elements for quick scanning.</p>
<p>The select menus are driven off native <code>select</code> elements, but the native selects are hidden from view and replaced with more style-friendly markup. The replacement buttons and menus are ARIA-enabled and are keyboard accessible on the desktop as well. </p>
27
27
<p>When clicked, if the menu has room it will appear as an overlay listbox, but if there are too many options to fit in the window without scrolling, the page content is wrapped in a div and hidden, and the menu is appended as a whole new page. This lets us take advantage of native scrolling while the menu is in use. </p>
28
-
28
+
29
29
<p>To add a select widget to your page, start with a standard <code>select</code> element populated with a set of <code>option</code> elements. Set the <code>for</code> attribute of the <code>label</code> to match the ID of the <code>select</code> so they are semantically associated. Wrap them in a <code>div</code> with the <code>data-role="fieldcontain"</code> attribute to help visually group it in a longer form. </p>
30
-
30
+
31
31
<p>The framework will find all <code>select</code> elements and automatically enhance them into the custom select menus.</p>
<p> If there is a small number of options that will fit on the device's screen, it will appear as a small overlay with a pop transition.</p>
46
46
47
47
<divdata-role="fieldcontain">
@@ -117,7 +117,15 @@ <h2>Select menus</h2>
117
117
118
118
<h2>Option to use native menus</h2>
119
119
<p>The custom select menus add the ability to theme the select and provide visual consistency across platforms In addition, it fixes over some missing functionality on certain platforms: <code>optgroup</code> support on Android, multi-select capability on WebOS, and adds an elegant way to handle placeholder values (explained below).</p>
120
-
<p>However, there is overhead involved in parsing the native select to build a custom menu and if the number of selects or options within are fairly large, this can impact the performance of the page. By adding the <code>data-native="true"</code> attribute to the <code>select</code>, the framework will use the browesr's native select menu when the select button is clicked. Because this option doesn't use any of the custom menu parsing and menu generation logic, it is significantly faster than the custom menu version.</p>
120
+
<p>However, there is overhead involved in parsing the native select to build a custom menu and if the number of selects or options within are fairly large, this can impact the performance of the page. By adding the <code>data-native="true"</code> attribute to the <code>select</code>, the framework will use the browser's native select menu when the select button is clicked. Because this option doesn't use any of the custom menu parsing and menu generation logic, it is significantly faster than the custom menu version.</p>
121
+
122
+
<p>You can also set the global configuration <code>$.mobile.nativeSelectMenus</code> to true in a callback bound to the <code>mobileinit</code> event to achieve the same effect. The following must be included in the page after jQuery is loaded but before jQuery Mobile.</p>
@@ -174,27 +182,25 @@ <h2>Option to use native menus</h2>
174
182
<optionvalue="WY">Wyoming</option>
175
183
</select>
176
184
</div>
177
-
178
-
179
-
185
+
180
186
<h2>Placeholder options</h2>
181
187
<p>It's common for developers to include a "null" option in their select element to force a user to choose an option. If a placeholder option is present in your markup, jQuery Mobile will hide them in the overlay menu, showing only valid choices to the user, and display the placeholder text inside the menu as a header. A placeholder option is added when the framework finds:</p>
182
188
<ul>
183
189
<li>An option with no value attribute (or an empty value attribute)</li>
184
190
<li>An option with no text node</li>
185
191
<li>An option with a <code>data-placeholder="true"</code> attribute. (This allows you to use an option that has a value and a textnode as a placeholder option).</li>
186
192
</ul>
187
-
193
+
188
194
<p>You can disable this feature through the selectmenu plugin's <code>hidePlaceholderMenuItems</code> option, like this:</p>
<p>jQuery Mobile will automatically disable and style option tags with the <code>disabled</code> attribute. In the demo below, the second option "Rush: 3 days" has been set to disabled.</p>
235
241
@@ -242,7 +248,7 @@ <h2>Disabled options</h2>
242
248
<optionvalue="overnight">Overnight</option>
243
249
</select>
244
250
</div>
245
-
251
+
246
252
<h2>Optgroup support</h2>
247
253
<p>If a select menu contains <code>optgroup</code> elements, jQuery Mobile will create a divider & group items based on the <code>label</code> attribute's text:</p>
248
254
@@ -262,11 +268,11 @@ <h2>Optgroup support</h2>
262
268
</optgroup>
263
269
</select>
264
270
</div>
265
-
266
-
271
+
272
+
267
273
<h2>Multiple selects</h2>
268
274
<p>If the <code>multiple</code> attribute is present in your markup, jQuery Mobile will enhance the element with a few extra considerations:</p>
269
-
275
+
270
276
<ul>
271
277
<li>A header element will be created inside the menu and display the placeholder text and a close button.</li>
272
278
<li>Clicking on an item inside the overlay menu will not close the widget.</li>
@@ -276,7 +282,7 @@ <h2>Multiple selects</h2>
276
282
<li>If no items are selected, the button's text will default to the placeholder text.</li>
277
283
<li>If no placeholder element exists, the default button text will be blank and the header will appear with just a close button. Because this isn't a friendly user experience, we recommended that you always specify a placeholder element when using multiple select boxes.</li>
<p>When a select is large enough to where the menu will open in a new page, the placeholder text is displayed in the button when no items are selected, and the <code>label</code> text is displayed in the menu's header. This differs from smaller overlay menus where the placeholder text is displayed in both the button and the header, and from full-page single selects where the placeholder text is not used at all.</p>
<p>You can specify any jQuery Mobile button data- attribute on a select element too. In this example, we're setting the theme, icon and inline properties though data- attributes.</p>
355
-
360
+
<p>You can specify any jQuery Mobile button data- attribute on a select element too. In this example, we're setting the theme, icon and inline properties though data- attributes.</p>
0 commit comments