PageRenderTime 172ms CodeModel.GetById 0ms RepoModel.GetById 0ms app.codeStats 0ms

/demos/mobile/docs/forms/docs-forms.html

https://github.com/MichaelVdheeren/Absolution
HTML | 267 lines | 200 code | 67 blank | 0 comment | 0 complexity | f12caba083da46e6465af4b95ab831ed MD5 | raw file
    

  1. <!DOCTYPE html>
    2. 

  2. <html>
    3. 

  3. 	<head>
    4. 

  4. 	<meta charset="utf-8">
    5. 

  5. 	<meta name="viewport" content="width=device-width, initial-scale=1">
    6. 

  6. 	<title>jQuery Mobile Docs - Forms</title>
    7. 

  7. 	<link rel="stylesheet"  href="../../../../compiled/absolution.mobile.css" />
    8. 

  8. 	<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
    9. 

  9. 

  10. 	<script src="../../js/jquery.js"></script>
    11. 

  11. 	<script src="../../docs/_assets/js/jqm-docs.js"></script>
    12. 

  12. 	<script src="../../js/jquery.mobile-1.1.1.js"></script>
    13. 

  13. 

  14. </head>
    15. 

  15. <body>
    16. 

  16. 

  17. 	<div data-role="page" class="type-interior">
    18. 

  18. 

  19. 		<div data-role="header" data-theme="f">
    20. 

  20. 		<h1>Forms</h1>
    21. 

  21. 		<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
    22. 

  22. 		<a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
    23. 

  23. 	</div><!-- /header -->
    24. 

  24. 

  25. 	<div data-role="content">
    26. 

  26. 		<div class="content-primary">
    27. 

  27. 			<p>jQuery Mobile provides a complete set of finger-friendly form elements that are based on native HTML form elements.</p>
    28. 

  28. 

  29. 			<h2>Form structure</h2>
    30. 

  30. 

  31. 			<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>
    32. 

  32. 

  33. <code>
    34. 

  34. &lt;form action=&quot;form.php&quot; method=&quot;post&quot;&gt;
    35. 

  35. ...
    36. 

  36. &lt;/form&gt;
    37. 

  37. </code>
    38. 

  38. 

  39. 

  40. <h2>Markup conventions</h2>
    41. 

  41. <p>When constructing forms to be used in jQuery Mobile, most of the standard guidelines used to create forms that submit via ordinary HTTP POST or GET still apply. Additionally, the <code>id</code> 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. You must be careful to use unique <code>id</code> attributes so there will be only one of each in the DOM. Be sure to pair them properly with <code>label</code> elements via the <code>for</code> attribute.</p>
    42. 

    43. 

  43. 	<h2>Mini sized elements</h2>
    44. 

  44. 

  45. 	<p>For a more compact version of all form elements and buttons, add the <code>data-mini="true"</code> attribute to the element to create a <a href="forms-all-mini.html">mini version</a>. This is useful in toolbars and tight spaces but is still finger-friendly. It's possible to add this attribute to a fieldcontainer to set this on a number of elements at once.</p>
    46. 

    47. 

  47. <pre><code>
    48. 

  48. &lt;label for=&quot;basic&quot;&gt;Text Input:&lt;/label&gt;
    49. 

  49. &lt;input type=&quot;text&quot; name=&quot;name&quot; id=&quot;basic&quot; <strong>data-mini=&quot;true&quot;</strong> /&gt;
    50. 

  50. 	</code></pre>
    51. 

  51. 

  52. 	<p>This will produce an input that is not as tall as the standard version and has a smaller text size.</p>
    53. 

  53. 	 <label for="mini">Text Input:</label>
    54. 

  54. 	 <input type="text" name="name" id="mini" value="" data-mini="true" />
    55. 

  55. 

  56. 	<h2>Hiding labels accessibly</h2>
    57. 

  57. 	<p>For the sake of accessibility, jQuery Mobile requires that all form elements be paired with a meaningful <code>label</code>. To hide labels in a way that leaves them visible to assistive technologies—for example, when letting an element’s <code>placeholder</code> attribute serve as a label—apply the helper class <code>ui-hidden-accessible</code> to the label itself:</p>
    58. 

  58. <code>
    59. 

  59. <pre>
    60. 

  60. &lt;label for="username" <strong>class="ui-hidden-accessible"</strong>&gt;Username:&lt;/label&gt;
    61. 

  61. &lt;input type="text" name="username" id="username" value="" placeholder="Username"/&gt;
    62. 

  62. </pre>
    63. 

  63. </code>
    64. 

  64. 

  65. 	<p>To hide labels within a field container and adjust the layout accordingly, add the class <code>ui-hide-label</code> to the field container as in the following:</p>
    66. 

  66. 

  67. <code>
    68. 

  68. <pre>
    69. 

  69. &lt;div data-role="fieldcontain" <strong>class="ui-hide-label"</strong>&gt;
    70. 

  70. 	&lt;label for="username"&gt;Username:&lt;/label&gt;
    71. 

  71. 	&lt;input type="text" name="username" id="username" value="" placeholder="Username"/&gt;
    72. 

  72. &lt;/div&gt;
    73. 

  73. </pre>
    74. 

  74. </code>
    75. 

  75. 

  76. 	<p>Both of the above examples will render as:</p>
    77. 

  77. 	<div data-role="fieldcontain" class="ui-hide-label">
    78. 

  78. 		<label for="username">Username:</label>
    79. 

  79. 		<input type="text" name="username" id="username" value="" placeholder="Username" />
    80. 

  80. 	</div>
    81. 

  81. 

  82. 	<p>While the label will no longer be visible, it will be available to assisitive technologies such as screen readers.</p>
    83. 

  83. 

  84. 

  85. 	<h2>Disabling form elements</h2>
    86. 

  86. 	<p>All jQuery Mobile widgets can be disabled in the markup by adding the standard <code>disabled</code> attribute to the element, just like you would with native controls. Each form widget also has standard <code>disable</code> and <code>enable</code> methods that are documented with each form widget. Here are a few examples of disabled widgets: </p>
    87. 

  87. 

  88. 	<div data-role="fieldcontain">
    89. 

  89.      <label for="foo">Text Input:</label>
    90. 

  90.      <input type="text" name="name" id="foo" value="" disabled />
    91. 

  91. 	</div>
    92. 

  92. 

  93. 	<div data-role="fieldcontain">
    94. 

  94. 	<fieldset data-role="controlgroup">
    95. 

  95.     	<legend>Gender:</legend>
    96. 

  96.          	<input type="radio" name="gender" id="radio-female" value="f" disabled />
    97. 

  97.          	<label for="radio-female">Female</label>
    98. 

  98. 

  99.          	<input type="radio" name="gender" id="radio-male" value="m" disabled  />
    100. 

  100.          	<label for="radio-male">Male</label>
    101. 

  101.     </fieldset>
    102. 

  102.     </div>
    103. 

  103. 

  104. 	<div data-role="fieldcontain">
    105. 

  105. 	<label for="flip-s">Server status:</label>
    106. 

  106. 	<select name="flip-s" id="flip-s" data-role="slider" disabled >
    107. 

  107. 		<option value="off">Off</option>
    108. 

  108. 		<option value="on">On</option>
    109. 

  109. 	</select>
    110. 

  110.     </div>
    111. 

  111. 

  112.     <div data-role="fieldcontain">
    113. 

  113. 	<label for="slider">Max bandwidth:</label>
    114. 

  114. 	<input type="range" name="slider" id="slider" value="0" min="0" max="100" disabled />
    115. 

  115.     </div>
    116. 

  116. 

  117. 	<div data-role="fieldcontain">
    118. 

  118. 		<label for="select-choice-x" class="select">Shipping:</label>
    119. 

  119. 		<select name="select-shipper" id="select-choice-x" disabled>
    120. 

  120. 			<option></option>
    121. 

  121. 			<option value="standard">Standard</option>
    122. 

  122. 			<option value="rush">Rush</option>
    123. 

  123. 			<option value="express">Express</option>
    124. 

  124. 			<option value="overnight">Overnight</option>
    125. 

  125. 		</select>
    126. 

  126. 	</div>
    127. 

  127. 

  128. 	<p>Note that you can disable buttons created from <code>button</code> or <code>input</code>-based markup, but not links with a role of button. Links don't have a parallel disabled feature in HTML, but if you need to disable a link-based button (or any element), it's possible to apply the disabled class <code>ui-disabled</code> yourself with JavaScript to achieve the same effect. </p>
    129. 

  129. 

  130. 		<h2>Field containers</h2>
    131. 

  131. 		<p>To improve the styling of labels and form elements on wider screens, wrap a <code>div</code> or <code>fieldset </code>with the <code> data-role="fieldcontain"</code> attribute around each label/form element. This framework aligns the input and associated label side-by-side, and breaks to stacked block-level elements below ~480px. The framework will also add a thin bottom border to act as a field separator.</p>
    132. 

  132. 

  133. 		<h2>Forms in toolbars</h2>
    134. 

  134. 		<p>While all form elements are now tested to work correctly within <em>static</em> toolbars as of jQuery Mobile 1.1, we recommend extensive testing when using form elements within <em>fixed</em> toolbars or within any <code>position: fixed</code> elements. This can potentially trigger a number of unpredictable issues in various mobile browsers, Android 2.2/2.3 in particular (detailed in <a href="http://jqm.dev/docs/toolbars/bars-fixed.html">Known issues in Android 2.2/2.3</a>).</p>
    135. 

  135. 

  136. 		<p>For example:</p>
    137. 

  137. <pre><code>
    138. 

  138. &lt;div data-role=&quot;fieldcontain&quot;&gt;
    139. 

  139. 	&lt;label for="name"&gt;Text Input:&lt;/label&gt;
    140. 

  140. 	&lt;input type="text" name="name" id="name" value="" /&gt;
    141. 

  141. &lt;/div&gt;
    142. 

  142. </code></pre>
    143. 

  143. 

  144. 		<p>Will render as:</p>
    145. 

  145. 

  146. 		<div data-role="fieldcontain">
    147. 

  147.  			<label for="name">Text Input:</label>
    148. 

  148.  			<input type="text" name="name" id="name" value=""  />
    149. 

  149. 		</div>
    150. 

  150. 

  151. 		<p>For additional examples, see the <a href="forms-all.html">form elements gallery</a></p>
    152. 

  152. 

  153. 

  154. 	<h2>Auto-initialization of form elements</h2>
    155. 

  155. 	<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. 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 options, methods, and events listed on each form plugin's documentation page for details. </p>
    156. 

    157. 

  157. 	<h2>Initializing groups of dynamically-injected form elements</h2>
    158. 

  158. 	<p>If you should generate new markup client-side or load in content via AJAX and inject it into a page, you can trigger the <code>create</code> event to handle the auto-initialization for all the plugins contained within the new markup. This can be triggered on any element (even the page div itself), saving you the task of manually initializing each plugin (see below).</p>
    159. 

  159. 

  160. 	<p>For example, if a block of HTML markup (say a login form) was loaded in through Ajax, trigger the create event to automatically transform all the widgets it contains (inputs and buttons in this case) into the enhanced versions. The code for this scenario would be:</p>
    161. 

  161. 

  162. 	<code>
    163. 

  163. 	$( ...new markup that contains widgets... ).appendTo( ".ui-page" ).trigger( "create" );
    164. 

  164. 	</code>
    165. 

  165. 

  166. 	<h2>Refreshing form elements</h2>
    167. 

  167. 

  168.     <p>In jQuery Mobile, some enhanced form controls are simply styled (inputs), but others are custom controls (selects, sliders) built from, and kept in sync with, the native control. To programmatically update a form control with JavaScript, first manipulate the native control, then use the <code>refresh</code> method to tell the enhanced control to update itself to match the new state. Here are some examples of how to update common form controls, then call the <code>refresh</code> method:</p>
    169. 

  169. 	<h4>Checkboxes:</h4>
    170. 

  170. 

  171. <code>
    172. 

  172. $("input[type='checkbox']").prop("checked",true).checkboxradio("refresh");
    173. 

  173. </code>
    174. 

  174. 

  175. <h4>Radios:</h4>
    176. 

  176. <code>
    177. 

  177. $("input[type='radio']").prop("checked",true).checkboxradio("refresh");
    178. 

  178. </code>
    179. 

  179. 

  180. <h4>Selects:</h4>
    181. 

  181. <code><pre>
    182. 

  182. var myselect = $("#selectfoo");
    183. 

  183. myselect[0].selectedIndex = 3;
    184. 

  184. myselect.selectmenu("refresh");
    185. 

  185. </pre></code>
    186. 

  186. 

  187. <h4>Sliders:</h4>
    188. 

  188. <code>
    189. 

  189. $("input[type='range']").val(60).slider("refresh");
    190. 

  190. </code>
    191. 

  191. 

  192. <h4>Flip switches (they use slider):</h4>
    193. 

  193. 

  194. <code><pre>
    195. 

  195. var myswitch = $("#selectbar");
    196. 

  196. myswitch[0].selectedIndex = 1;
    197. 

  197. myswitch.slider("refresh");
    198. 

  198. </pre></code>
    199. 

  199. 

  200. 	<h2>Preventing auto-initialization of form elements</h2>
    201. 

  201. 	<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>
    202. 

  202. 	<pre><code>
    203. 

  203. &lt;label for=&quot;foo&quot;&gt;
    204. 

  204. &lt;select name=&quot;foo&quot; id=&quot;foo&quot; <strong>data-role=&quot;none&quot;</strong>&gt;
    205. 

  205. 	&lt;option value="a"&gt;A&lt;/option&gt;
    206. 

  206. 	&lt;option value="b"&gt;B&lt;/option&gt;
    207. 

  207. 	&lt;option value="c"&gt;C&lt;/option&gt;
    208. 

  208. &lt;/select&gt;
    209. 

  209. </code></pre>
    210. 

  210. 

  211. 

  212. 	<p>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>
    213. 

  213. 		<pre><code>
    214. 

  214. $(document).bind('mobileinit',function(){
    215. 

  215. 	<strong>$.mobile.page.prototype.options.keepNative = "select, input.foo, textarea.bar";</strong>
    216. 

  216. });
    217. 

  217. 		</code></pre>
    218. 

  218. 

  219.   	<p>Alternately you can use the <code>data-enhance="false"</code> data attribute on a parent element with <code>$.mobile.ignoreContentEnabled</code> set to true. Beware though, this will incur a performance penalty for each and every element in the page that would otherwise be enhanced as jQuery Mobile must traverse the set of parents to look for those elements.</p>
    220. 

  220. 

  221. <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 and appearance of the menu itself and benefit from the visual augmentation of the select button by jQuery Mobile, you can set <code>$.mobile.selectmenu.prototype.options.nativeMenu</code> to true in a <code>mobileinit</code> callback as a global setting or use <code>data-native-menu="true"</code> on a case by case basis.</p>
    222. 

  222. 

  223. 

  224. 	<h2>File Inputs</h2>
    225. 

  225. 	<p>Using a multipart form with a file input is not supported by ajax. In this case you should decorate the parent form with <code>data-ajax="false"</code> to ensure the form is submitted properly to the server.</p>
    226. 

  226. 

  227. 

  228. 	</div><!--/content-primary -->
    229. 

  229. 

  230. 	<div class="content-secondary">
    231. 

  231. 

  232. 		<div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
    233. 

  233. 

  234. 				<h3>More in this section</h3>
    235. 

  235. 

  236. 				<ul data-role="listview" data-theme="c" data-dividertheme="d">
    237. 

  237. 

  238. 					<li data-role="list-divider">Form elements</li>
    239. 

  239. 					<li data-theme="a"><a href="docs-forms.html">Form basics</a></li>
    240. 

  240. 					<li><a href="forms-all.html">Form element gallery</a></li>
    241. 

  241. 					<li><a href="forms-all-mini.html">Mini form element gallery</a></li>
    242. 

  242. 					<li><a href="textinputs/">Text inputs</a></li>
    243. 

  243. 					<li><a href="search/">Search inputs</a></li>
    244. 

  244. 					<li><a href="slider/">Slider</a></li>
    245. 

  245. 					<li><a href="switch/">Flip toggle switch</a></li>
    246. 

  246. 					<li><a href="radiobuttons/">Radio buttons</a></li>
    247. 

  247. 					<li><a href="checkboxes/">Checkboxes</a></li>
    248. 

  248. 					<li><a href="selects/">Select menus</a></li>
    249. 

  249. 					<li><a href="forms-themes.html">Theming forms</a></li>
    250. 

  250. 					<li><a href="forms-all-native.html">Native form elements</a></li>
    251. 

  251. 					<li><a href="forms-sample.html">Submitting forms</a></li>
    252. 

  252. 

  253. 

  254. 				</ul>
    255. 

  255. 		</div>
    256. 

  256. 	</div>
    257. 

  257. 

  258. </div><!-- /content -->
    259. 

  259. 

  260. <div data-role="footer" class="footer-docs" data-theme="c">
    261. 

  261. 		<p>&copy; 2012 jQuery Foundation and other contributors</p>
    262. 

  262. </div>
    263. 

  263. 

  264. </div><!-- /page -->
    265. 

  265. 

  266. </body>
    267. 

  267. </html>
    268. 

  268.