Hopiu/jquery-mobile
1
0
Fork 0
mirror of https://github.com/Hopiu/jquery-mobile.git synced 2026-05-16 10:33:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Created a new API docs format for people to help us populate. Started with just the select menu API docs to server as a template for others. Each plugin is now in a folder with a local nav between index (summary), options, methods, and events.

Browse source
This commit is contained in:
toddparker 2011-07-28 12:00:36 -04:00
parent 2c4615176d
commit 5c603198e7
19 changed files with 918 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
docs/_assets/css/jqm-docs.css
View file

@ -13,7 +13,7 @@ body { background: #dddddd; }
.ui-mobile #jqm-version { text-indent: -99999px; background: url(../images/version.png) top right no-repeat; width: 119px; height: 122px; overflow: hidden; position: absolute; z-index: 50; top: 0; right: 0; }
.ui-mobile .jqm-themeswitcher { margin: 10px 25px 10px 10px; }
h2 { margin-top:1.5em; }
h2 { margin:1.2em 0 .4em 0; }
p code { font-size:1.2em; font-weight:bold; }
dt { font-weight: bold; margin: 2em 0 .5em; }
@ -74,6 +74,49 @@ p.intro strong {
margin: 0;
}
/* new API additions */
dt {
margin: 35px 0 15px 0;
background-color:#ddd;
font-weight:normal;
}
dt code {
display:inline-block;
font-weight:bold;
color:#56A00E;
padding:3px 7px;
margin-right:10px;
background-color:#fff;
}
dd {
margin-bottom:10px;
}
dd .default { font-weight:bold; }
dd pre {
margin:0 0 0 0;
}
dd code { font-weight: normal; }
dd pre code {
margin:0;
border:none;
font-weight:normal;
font-size:100%;
background-color:transparent;
}
dd h4 { margin:15px 0 0 0; }
.localnav {
margin:0 0 20px 0;
overflow:hidden;
}
.localnav li {
float:left;
}
.localnav .ui-btn-inner {
padding: .6em 10px;
font-size:80%;
}
/* F bar theme - just for the docs overview headers */

2
docs/forms/docs-forms.html
View file

@ -134,7 +134,7 @@ myswitch .slider("refresh");
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-all-native.html
View file

@ -224,7 +224,7 @@
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li data-theme="a"><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-all.html
View file

@ -222,7 +222,7 @@
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-checkboxes.html
View file

@ -130,7 +130,7 @@ $("input[type='checkbox']").attr("checked",true).checkboxradio("refresh");
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li data-theme="a"><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-radiobuttons.html
View file

@ -134,7 +134,7 @@ $("input[type='radio']").attr("checked",true).checkboxradio("refresh");
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li data-theme="a"><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-sample.html
View file

@ -68,7 +68,7 @@
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li data-theme="a"><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-search.html
View file

@ -72,7 +72,7 @@
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-slider.html
View file

@ -82,7 +82,7 @@ $("input[type=range]").val(60).slider("refresh");
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-switch.html
View file

@ -79,7 +79,7 @@ myswitch .slider("refresh");
<li data-theme="a"><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-text.html
View file

@ -127,7 +127,7 @@
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/forms-themes.html
View file

@ -383,7 +383,7 @@
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li data-theme="a"><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/index.html
View file

@ -33,7 +33,7 @@
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

2
docs/forms/plugin-eventsmethods.html
View file

@ -196,7 +196,7 @@ $('input').button('disable');
<li><a href="forms-switch.html">Flip toggle switch</a></li>
<li><a href="forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="forms-checkboxes.html">Checkboxes</a></li>
<li><a href="forms-selects.html">Select menus</a></li>
<li><a href="selects/index.html">Select menus</a></li>
<li><a href="forms-themes.html">Theming forms</a></li>
<li><a href="forms-all-native.html">Native form elements</a></li>
<li><a href="forms-sample.html">Submitting forms</a></li>

101
docs/forms/selects/events.html Normal file
View file

@ -0,0 +1,101 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>jQuery Mobile Docs - Select events</title>
<link rel="stylesheet" href="../../themes/default/" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="./../../js/jquery.js"></script>
<script src="./../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
<script src="../../_assets/js/jqm-docs.js"></script>
<script src="../../../js/"></script>
</head>
<body>
<div data-role="page" class="type-interior">
<div data-role="header" data-theme="f">
<h1>Select Menus</h1>
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
</div><!-- /header -->
<div data-role="content">
<div class="content-primary">
<form action="#" method="get">
<h2>Select menus</h2>
<ul data-role="controlgroup" data-type="horizontal" class="localnav">
<li><a href="index.html" data-role="button" data-transition="fade">Basics</a></li>
<li><a href="options.html" data-role="button" data-transition="fade">Options</a></li>
<li><a href="methods.html" data-role="button" data-transition="fade">Methods</a></li>
<li><a href="events.html" data-role="button" data-transition="fade" class="ui-btn-active">Events</a></li>
</ul>
<p>Since the native select menu is used as a proxy for the custom select, you can watch for events on the original, native select instead of needing to go through the select menu plugin. Bind to the change event by type: change, blur, focus, keypress, click, etc.</p>
<pre><code>
$( ".selector" ).bind( "change", function(event, ui) {
...
});
</code></pre>
<p>The select menu plugin has the following custom events:</p>
<dl>
<dt><code>create</code> triggered when a select menu is created</dt>
<dd>
<p>This event is used to find out when a custom select was created. It is not used to create a custom select. The select create event can be used like this: </p>
<pre><code>
$( ".selector" ).selectmenu({
create: function(event, ui) { ... }
});
</code></pre>
</dd>
</dl>
</form>
</div><!--/content-primary -->
<div class="content-secondary">
<div data-role="collapsible" data-collapsed="true" data-theme="b">
<h3>More in this section</h3>
<ul data-role="listview" data-theme="c" data-dividertheme="d">
<li data-role="list-divider">Form elements</li>
<li><a href="../docs-forms.html">Form basics</a></li>
<li><a href="../forms-all.html">Form element gallery</a></li>
<li><a href="../forms-text.html">Text inputs</a></li>
<li><a href="../forms-search.html">Search inputs</a></li>
<li><a href="../forms-slider.html">Slider</a></li>
<li><a href="../forms-switch.html">Flip toggle switch</a></li>
<li><a href="../forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="../forms-checkboxes.html">Checkboxes</a></li>
<li data-theme="a"><a href="index.html">Select menus</a></li>
<li><a href="../forms-themes.html">Theming forms</a></li>
<li><a href="../forms-all-native.html">Native form elements</a></li>
<li><a href="../forms-sample.html">Submitting forms</a></li>
<li><a href="../plugin-eventsmethods.html">Plugin methods</a></li>
</ul>
</div>
</div>
</div><!-- /content -->
<div data-role="footer" class="footer-docs" data-theme="c">
<p>&copy; 2011 The jQuery Project</p>
</div>
</div><!-- /page -->
</body>
</html>

11
docs/forms/forms-selects.html → docs/forms/selects/forms-selects.html
View file

@ -10,6 +10,10 @@
<script src="../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
<script src="../_assets/js/jqm-docs.js"></script>
<script src="../../js/"></script>
<style type="text/css">
</style>
</head>
<body>
@ -26,6 +30,13 @@
<form action="#" method="get">
<h2>Select menus</h2>
<div data-role="controlgroup" data-type="horizontal" class="localnav">
<a href="index.html" data-role="button" class="ui-btn-active">Basics</a>
<a href="index.html" data-role="button">Options</a>
<a href="index.html" data-role="button">Methods</a>
<a href="index.html" data-role="button">Events</a>
</div>
<p>The select menus are driven off native <code>select</code> elements, but the native selects are hidden from view and replaced with a custom-styled select button that matches the look and feel of the jQuery Mobile framework. The replacement selects are ARIA-enabled and are keyboard accessible on the desktop as well.</p>

487
docs/forms/selects/index.html Normal file
View file

@ -0,0 +1,487 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>jQuery Mobile Docs - Select</title>
<link rel="stylesheet" href="../../themes/default/" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="../../../js/jquery.js"></script>
<script src="../../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
<script src="../../_assets/js/jqm-docs.js"></script>
<script src="../../../js/"></script>
</head>
<body>
<div data-role="page" class="type-interior">
<div data-role="header" data-theme="f">
<h1>Select Menus</h1>
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
</div><!-- /header -->
<div data-role="content">
<div class="content-primary">
<form action="#" method="get">
<h2>Select menus</h2>
<ul data-role="controlgroup" data-type="horizontal" class="localnav">
<li><a href="index.html" data-role="button" data-transition="fade" class="ui-btn-active">Basics</a></li>
<li><a href="options.html" data-role="button" data-transition="fade">Options</a></li>
<li><a href="methods.html" data-role="button" data-transition="fade">Methods</a></li>
<li><a href="events.html" data-role="button" data-transition="fade">Events</a></li>
</ul>
<p>The select menus are driven off native <code>select</code> elements, but the native selects are hidden from view and replaced with a custom-styled select button that matches the look and feel of the jQuery Mobile framework. The replacement selects are ARIA-enabled and are keyboard accessible on the desktop as well.</p>
<p>When the select button is clicked, the native select menu picker for the OS will open. When a value is selected in the menu, the custom select button is updated to match the new selection. </p>
<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>
<p>The framework will find all <code>select</code> elements and automatically enhance them into the custom select menus. Here is a typical select menu grouped in a fieldc container to style the label and select together:</p>
<pre><code>
&lt;div data-role=&quot;fieldcontain&quot;&gt;
&lt;label for=&quot;select-choice-1&quot; class=&quot;select&quot;&gt;Choose shipping method:&lt;/label&gt;
&lt;select name=&quot;select-choice-1&quot; id=&quot;select-choice-1&quot;&gt;
&lt;option value=&quot;standard&quot;&gt;Standard: 7 day&lt;/option&gt;
&lt;option value=&quot;rush&quot;&gt;Rush: 3 days&lt;/option&gt;
&lt;option value=&quot;express&quot;&gt;Express: next day&lt;/option&gt;
&lt;option value=&quot;overnight&quot;&gt;Overnight&lt;/option&gt;
&lt;/select&gt;
&lt;/div&gt;
</code></pre>
<p>This produces this select:</p>
<div data-role="fieldcontain">
<label for="select-choice-1" class="select">Choose shipping method:</label>
<select name="select-choice-1" id="select-choice-1">
<option value="standard">Standard: 7 day</option>
<option value="rush">Rush: 3 days</option>
<option value="express">Express: next day</option>
<option value="overnight">Overnight</option>
</select>
</div>
<p>Here is an example of a select with a long list of options:</p>
<div data-role="fieldcontain">
<label for="select-choice-3" class="select">Your state:</label>
<select name="select-choice-3" id="select-choice-3">
<option value="AL">Alabama</option>
<option value="AK">Alaska</option>
<option value="AZ">Arizona</option>
<option value="AR">Arkansas</option>
<option value="CA">California</option>
<option value="CO">Colorado</option>
<option value="CT">Connecticut</option>
<option value="DE">Delaware</option>
<option value="FL">Florida</option>
<option value="GA">Georgia</option>
<option value="HI">Hawaii</option>
<option value="ID">Idaho</option>
<option value="IL">Illinois</option>
<option value="IN">Indiana</option>
<option value="IA">Iowa</option>
<option value="KS">Kansas</option>
<option value="KY">Kentucky</option>
<option value="LA">Louisiana</option>
<option value="ME">Maine</option>
<option value="MD">Maryland</option>
<option value="MA">Massachusetts</option>
<option value="MI">Michigan</option>
<option value="MN">Minnesota</option>
<option value="MS">Mississippi</option>
<option value="MO">Missouri</option>
<option value="MT">Montana</option>
<option value="NE">Nebraska</option>
<option value="NV">Nevada</option>
<option value="NH">New Hampshire</option>
<option value="NJ">New Jersey</option>
<option value="NM">New Mexico</option>
<option value="NY">New York</option>
<option value="NC">North Carolina</option>
<option value="ND">North Dakota</option>
<option value="OH">Ohio</option>
<option value="OK">Oklahoma</option>
<option value="OR">Oregon</option>
<option value="PA">Pennsylvania</option>
<option value="RI">Rhode Island</option>
<option value="SC">South Carolina</option>
<option value="SD">South Dakota</option>
<option value="TN">Tennessee</option>
<option value="TX">Texas</option>
<option value="UT">Utah</option>
<option value="VT">Vermont</option>
<option value="VA">Virginia</option>
<option value="WA">Washington</option>
<option value="WV">West Virginia</option>
<option value="WI">Wisconsin</option>
<option value="WY">Wyoming</option>
</select>
</div>
<p>This example organizes the options with optgroup elements and has a disabled option.</p>
<div data-role="fieldcontain">
<label for="select-choice-nc" class="select">Preferred delivery:</label>
<select name="select-choice-8" id="select-choice-nc">
<optgroup label="FedEx">
<option value="firstOvernight">First Overnight</option>
<option value="expressSaver">Express Saver</option>
<option value="ground">Ground</option>
</optgroup>
<optgroup label="UPS">
<option value="firstOvernight">First Overnight</option>
<option value="expressSaver">Express Saver</option>
<option value="ground">Ground</option>
</optgroup>
<optgroup label="US Mail">
<option value="standard">Standard: 7 day</option>
<option value="rush">Rush: 3 days</option>
<option value="express" disabled="disabled">Express: next day (disabled)</option>
<option value="overnight">Overnight</option>
</optgroup>
</select>
</div>
<p>Note that on some mobile platforms, the native select menus don't support multiple selection via the <code>multiple="multiple"</code> attribute. If this feature is required, we recommend using custom menus.
<h2>Programmatically calling the select menu plugin</h2>
<p>The select menu plugin will auto initialize on any page that contains a select menu, no need for a <code>data-role</code> attribute in the markup. However, you can directly call the select menu plugin on any selector, just like any normal jQuery plugin:</p>
<pre><code>
$('select').selectmenu();
</code></pre>
<h2>Option to use custom menus</h2>
<p>You can optionally use custom-styled select menus instead of the native versions. This adds the ability to theme the menu to better match the look and feel of your site and provides visual consistency across platforms. In addition, it supports multiple selection, restores missing functionality on certain platforms such as <code>optgroup</code> support on Android, and adds an elegant way to handle placeholder values (explained below). Lastly, the custom menus will look better on desktop browsers because native menus on the desktop tend to be fairly small compared their mobile counterparts and this can look a bit odd if desktop is a priority for your project.</p>
<p>Keep in mind that there is overhead involved in parsing the native select to build a custom menu. If there are a lot of selects on a page, or a select has a long list of options, this can impact the performance of the page so we recommend using custom menus sparingly. </p>
<p>To use custom menus on a specific <code>select</code>, just add the <code>data-native-menu="false"</code> attribute. Alternately, this can also programmatically set the select menu's <code>nativeMenu</code> configuration option to <code>false</code> in a callback bound to the <code>mobileinit</code> event to achieve the same effect. This will globally make all selects use the custom menu by default. The following must be included in the page after jQuery is loaded but before jQuery Mobile is loaded.</p>
<code>
<pre>
$(document).bind('mobileinit',function(){
$.mobile.selectmenu.prototype.options.nativeMenu = false;
});
</pre>
</code>
<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>
<div data-role="fieldcontain">
<label for="select-choice-custom" class="select">Choose shipping method:</label>
<select name="select-choice-1" id="select-choice-custom" data-native-menu="false">
<option value="standard">Standard: 7 day</option>
<option value="rush">Rush: 3 days</option>
<option value="express">Express: next day</option>
<option value="overnight">Overnight</option>
</select>
</div>
<p>If there is a select menu with too many options to show on the device's screen, the framework will automatically create a new &quot;page&quot; populated with a standard list view that contains all the options. This allows us to use the native scrolling included on the device for moving through a long list. The text inside the <code>label</code> is used as the title for this page.</p>
<div data-role="fieldcontain">
<label for="select-choice-3" class="select">Your state:</label>
<select name="select-choice-3" id="select-choice-3" data-native-menu="false">
<option value="AL">Alabama</option>
<option value="AK">Alaska</option>
<option value="AZ">Arizona</option>
<option value="AR">Arkansas</option>
<option value="CA">California</option>
<option value="CO">Colorado</option>
<option value="CT">Connecticut</option>
<option value="DE">Delaware</option>
<option value="FL">Florida</option>
<option value="GA">Georgia</option>
<option value="HI">Hawaii</option>
<option value="ID">Idaho</option>
<option value="IL">Illinois</option>
<option value="IN">Indiana</option>
<option value="IA">Iowa</option>
<option value="KS">Kansas</option>
<option value="KY">Kentucky</option>
<option value="LA">Louisiana</option>
<option value="ME">Maine</option>
<option value="MD">Maryland</option>
<option value="MA">Massachusetts</option>
<option value="MI">Michigan</option>
<option value="MN">Minnesota</option>
<option value="MS">Mississippi</option>
<option value="MO">Missouri</option>
<option value="MT">Montana</option>
<option value="NE">Nebraska</option>
<option value="NV">Nevada</option>
<option value="NH">New Hampshire</option>
<option value="NJ">New Jersey</option>
<option value="NM">New Mexico</option>
<option value="NY">New York</option>
<option value="NC">North Carolina</option>
<option value="ND">North Dakota</option>
<option value="OH">Ohio</option>
<option value="OK">Oklahoma</option>
<option value="OR">Oregon</option>
<option value="PA">Pennsylvania</option>
<option value="RI">Rhode Island</option>
<option value="SC">South Carolina</option>
<option value="SD">South Dakota</option>
<option value="TN">Tennessee</option>
<option value="TX">Texas</option>
<option value="UT">Utah</option>
<option value="VT">Vermont</option>
<option value="VA">Virginia</option>
<option value="WA">Washington</option>
<option value="WV">West Virginia</option>
<option value="WI">Wisconsin</option>
<option value="WY">Wyoming</option>
</select>
</div>
<h2>Placeholder options</h2>
<p>It's common for developers to include a &quot;null&quot; 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>
<ul>
<li>An option with no value attribute (or an empty value attribute)</li>
<li>An option with no text node</li>
<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>
</ul>
<p>You can disable this feature through the selectmenu plugin's <code>hidePlaceholderMenuItems</code> option, like this:</p>
<pre>
<code>
$.mobile.selectmenu.prototype.options.hidePlaceholderMenuItems = false;
</code>
</pre>
<p>Here's a demo of various placeholder options:</p>
<div data-role="fieldcontain">
<label for="select-choice-4" class="select">Choose shipping method:</label>
<select name="select-choice-4" id="select-choice-4" data-native-menu="false">
<option></option>
<option value="standard">Standard: 7 day</option>
<option value="rush">Rush: 3 days</option>
<option value="express">Express: next day</option>
<option value="overnight">Overnight</option>
</select>
</div>
<div data-role="fieldcontain">
<label for="select-choice-5" class="select">Choose shipping method:</label>
<select name="select-choice-5" id="select-choice-5" data-native-menu="false">
<option>Choose one...</option>
<option value="standard">Standard: 7 day</option>
<option value="rush">Rush: 3 days</option>
<option value="express">Express: next day</option>
<option value="overnight">Overnight</option>
</select>
</div>
<div data-role="fieldcontain">
<label for="select-choice-6" class="select">Choose shipping method:</label>
<select name="select-choice-6" id="select-choice-6" data-native-menu="false">
<option value="choose-one" data-placeholder="true">Choose one...</option>
<option value="standard">Standard: 7 day</option>
<option value="rush">Rush: 3 days</option>
<option value="express">Express: next day</option>
<option value="overnight">Overnight</option>
</select>
</div>
<h2>Disabled options</h2>
<p>jQuery Mobile will automatically disable and style option tags with the <code>disabled</code> attribute. In the demo below, the second option &quot;Rush: 3 days&quot; has been set to disabled.</p>
<div data-role="fieldcontain">
<label for="select-choice-7" class="select">Choose shipping method:</label>
<select name="select-choice-7" id="select-choice-7" data-native-menu="false">
<option value="standard">Standard: 7 day</option>
<option value="rush" disabled="disabled">Rush: 3 days</option>
<option value="express">Express: next day</option>
<option value="overnight">Overnight</option>
</select>
</div>
<h2>Optgroup support</h2>
<p>If a select menu contains <code>optgroup</code> elements, jQuery Mobile will create a divider &amp; group items based on the <code>label</code> attribute's text:</p>
<div data-role="fieldcontain">
<label for="select-choice-8" class="select">Choose shipping method:</label>
<select name="select-choice-8" id="select-choice-8" data-native-menu="false">
<optgroup label="USPS">
<option value="standard">Standard: 7 day</option>
<option value="rush">Rush: 3 days</option>
<option value="express">Express: next day</option>
<option value="overnight">Overnight</option>
</optgroup>
<optgroup label="FedEx">
<option value="firstOvernight">First Overnight</option>
<option value="expressSaver">Express Saver</option>
<option value="ground">Ground</option>
</optgroup>
</select>
</div>
<h2>Multiple selects</h2>
<p>If the <code>multiple</code> attribute is present in your markup, jQuery Mobile will enhance the element with a few extra considerations:</p>
<ul>
<li>A header element will be created inside the menu and display the placeholder text and a close button.</li>
<li>Clicking on an item inside the overlay menu will not close the widget.</li>
<li>A ghosted, unchecked icon will appear adjacent to each unselected item. When the item is selected the icon will change to a checkbox. Neither icon will appear inside a single select box.</li>
<li>Once 2+ items are selected, a counter element with the total number of selected items will appear inside the button.</li>
<li>The text of each selected item will appear inside the button as a list. If the button is not wide enough to display the entire list, it is truncated with an ellipses.</li>
<li>If no items are selected, the button's text will default to the placeholder text.</li>
<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>
</ul>
<div data-role="fieldcontain">
<label for="select-choice-9" class="select">Choose shipping method(s):</label>
<select name="select-choice-9" id="select-choice-9" multiple="multiple" data-native-menu="false">
<option>Choose options</option>
<option value="standard">Standard: 7 day</option>
<option value="rush">Rush: 3 days</option>
<option value="express">Express: next day</option>
<option value="overnight">Overnight</option>
</select>
</div>
<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>
<div data-role="fieldcontain">
<label for="select-choice-10" class="select">Choose state(s):</label>
<select name="select-choice-10" id="select-choice-10" multiple="multiple" data-native-menu="false">
<option>Choose options</option>
<option value="AL">Alabama</option>
<option value="AK">Alaska</option>
<option value="AZ">Arizona</option>
<option value="AR">Arkansas</option>
<option value="CA">California</option>
<option value="CO">Colorado</option>
<option value="CT">Connecticut</option>
<option value="DE">Delaware</option>
<option value="FL">Florida</option>
<option value="GA">Georgia</option>
<option value="HI">Hawaii</option>
<option value="ID">Idaho</option>
<option value="IL">Illinois</option>
<option value="IN">Indiana</option>
<option value="IA">Iowa</option>
<option value="KS">Kansas</option>
<option value="KY">Kentucky</option>
<option value="LA">Louisiana</option>
<option value="ME">Maine</option>
<option value="MD">Maryland</option>
<option value="MA">Massachusetts</option>
<option value="MI">Michigan</option>
<option value="MN">Minnesota</option>
<option value="MS">Mississippi</option>
<option value="MO">Missouri</option>
<option value="MT">Montana</option>
<option value="NE">Nebraska</option>
<option value="NV">Nevada</option>
<option value="NH">New Hampshire</option>
<option value="NJ">New Jersey</option>
<option value="NM">New Mexico</option>
<option value="NY">New York</option>
<option value="NC">North Carolina</option>
<option value="ND">North Dakota</option>
<option value="OH">Ohio</option>
<option value="OK">Oklahoma</option>
<option value="OR">Oregon</option>
<option value="PA">Pennsylvania</option>
<option value="RI">Rhode Island</option>
<option value="SC">South Carolina</option>
<option value="SD">South Dakota</option>
<option value="TN">Tennessee</option>
<option value="TX">Texas</option>
<option value="UT">Utah</option>
<option value="VT">Vermont</option>
<option value="VA">Virginia</option>
<option value="WA">Washington</option>
<option value="WV">West Virginia</option>
<option value="WI">Wisconsin</option>
<option value="WY">Wyoming</option>
</select>
</div>
<h2>Styling with data attributes</h2>
<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>
<div data-role="fieldcontain">
<label for="select-choice-11" class="select">Actions</label>
<select name="select-choice-11" id="select-choice-11" data-theme="a" data-icon="gear" data-inline="true" data-native-menu="false">
<option value="edit">Edit user</option>
<option value="delete">Delete user</option>
</select>
</div>
<h2>Refreshing a select</h2>
<p>If you manipulate a select via JavaScript, you must call the refresh method on it to update the visual styling. Here is an example:</p>
<code><pre>
var myselect = $("select#foo");
myselect[0].selectedIndex = 3;
myselect.selectmenu("refresh");
</pre></code>
</form>
</div><!--/content-primary -->
<div class="content-secondary">
<div data-role="collapsible" data-collapsed="true" data-theme="b">
<h3>More in this section</h3>
<ul data-role="listview" data-theme="c" data-dividertheme="d">
<li data-role="list-divider">Form elements</li>
<li><a href="../docs-forms.html">Form basics</a></li>
<li><a href="../forms-all.html">Form element gallery</a></li>
<li><a href="../forms-text.html">Text inputs</a></li>
<li><a href="../forms-search.html">Search inputs</a></li>
<li><a href="../forms-slider.html">Slider</a></li>
<li><a href="../forms-switch.html">Flip toggle switch</a></li>
<li><a href="../forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="../forms-checkboxes.html">Checkboxes</a></li>
<li data-theme="a"><a href="index.html">Select menus</a></li>
<li><a href="../forms-themes.html">Theming forms</a></li>
<li><a href="../forms-all-native.html">Native form elements</a></li>
<li><a href="../forms-sample.html">Submitting forms</a></li>
<li><a href="../plugin-eventsmethods.html">Plugin methods</a></li>
</ul>
</div>
</div>
</div><!-- /content -->
<div data-role="footer" class="footer-docs" data-theme="c">
<p>&copy; 2011 The jQuery Project</p>
</div>
</div><!-- /page -->
</body>
</html>

123
docs/forms/selects/methods.html Normal file
View file

@ -0,0 +1,123 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>jQuery Mobile Docs - Select methods</title>
<link rel="stylesheet" href="../../themes/default/" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="./../../js/jquery.js"></script>
<script src="./../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
<script src="../../_assets/js/jqm-docs.js"></script>
<script src="../../../js/"></script>
</head>
<body>
<div data-role="page" class="type-interior">
<div data-role="header" data-theme="f">
<h1>Select Menus</h1>
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
</div><!-- /header -->
<div data-role="content">
<div class="content-primary">
<form action="#" method="get">
<h2>Select menus</h2>
<ul data-role="controlgroup" data-type="horizontal" class="localnav">
<li><a href="index.html" data-role="button" data-transition="fade">Basics</a></li>
<li><a href="options.html" data-role="button" data-transition="fade">Options</a></li>
<li><a href="methods.html" data-role="button" data-transition="fade" class="ui-btn-active">Methods</a></li>
<li><a href="events.html" data-role="button" data-transition="fade">Events</a></li>
</ul>
<p>The select menu plugin has the following methods:</p>
<dl>
<dt><code>close</code> close an open select menu</dt>
<dd>
<pre><code>
$('select').selectmenu('close');
</code></pre>
</dd>
<dt><code>enable</code> enable a disabled select</dt>
<dd>
<pre><code>
$('select').selectmenu('enable');
</code></pre>
</dd>
<dt><code>disable</code> disable a select.</dt>
<dd>
<pre><code>
$('select').selectmenu('disable');
</code></pre>
</dd>
<dt><code>open</code> open a closed select menu</dt>
<dd>
<pre><code>
$('select').selectmenu('open');
</code></pre>
</dd>
<dt><code>refresh</code> update the custom select</dt>
<dd>
This is used to update the custom select to reflect the native select element's value.If the number of options in the select are different than the number of items in the custom menu, it'll rebuild the custom menu. Also, if you pass a true argument you can force the rebuild to happen.
<pre><code>
//refresh value
$('select').selectmenu('refresh');
//refresh and force rebuild
$('select').selectmenu('refresh', true);
</code></pre>
</dd>
</dl>
</form>
</div><!--/content-primary -->
<div class="content-secondary">
<div data-role="collapsible" data-collapsed="true" data-theme="b">
<h3>More in this section</h3>
<ul data-role="listview" data-theme="c" data-dividertheme="d">
<li data-role="list-divider">Form elements</li>
<li><a href="../docs-forms.html">Form basics</a></li>
<li><a href="../forms-all.html">Form element gallery</a></li>
<li><a href="../forms-text.html">Text inputs</a></li>
<li><a href="../forms-search.html">Search inputs</a></li>
<li><a href="../forms-slider.html">Slider</a></li>
<li><a href="../forms-switch.html">Flip toggle switch</a></li>
<li><a href="../forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="../forms-checkboxes.html">Checkboxes</a></li>
<li data-theme="a"><a href="index.html">Select menus</a></li>
<li><a href="../forms-themes.html">Theming forms</a></li>
<li><a href="../forms-all-native.html">Native form elements</a></li>
<li><a href="../forms-sample.html">Submitting forms</a></li>
<li><a href="../plugin-eventsmethods.html">Plugin methods</a></li>
</ul>
</div>
</div>
</div><!-- /content -->
<div data-role="footer" class="footer-docs" data-theme="c">
<p>&copy; 2011 The jQuery Project</p>
</div>
</div><!-- /page -->
</body>
</html>

139
docs/forms/selects/options.html Normal file
View file

@ -0,0 +1,139 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>jQuery Mobile Docs - Select options</title>
<link rel="stylesheet" href="../../themes/default/" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="./../../js/jquery.js"></script>
<script src="./../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
<script src="../../_assets/js/jqm-docs.js"></script>
<script src="../../../js/"></script>
</head>
<body>
<div data-role="page" class="type-interior">
<div data-role="header" data-theme="f">
<h1>Select Menus</h1>
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
</div><!-- /header -->
<div data-role="content">
<div class="content-primary">
<form action="#" method="get">
<h2>Select menus</h2>
<ul data-role="controlgroup" data-type="horizontal" class="localnav">
<li><a href="index.html" data-role="button" data-transition="fade">Basics</a></li>
<li><a href="options.html" data-role="button" data-transition="fade" class="ui-btn-active">Options</a></li>
<li><a href="methods.html" data-role="button" data-transition="fade">Methods</a></li>
<li><a href="events.html" data-role="button" data-transition="fade">Events</a></li>
</ul>
<p>The select menu plugin has the following options:</p>
<dl>
<dt><code>corners</code> <em>boolean</em></dt>
<dd>
<p class="default">default: "true"</p>
<p>Applies the rounded corner class to add the theme button border-radius to the select button if set to true. This option is also exposed as a data attribute: <code>data-corners=&quot;false&quot;</code></p>
<pre><code>$('select').selectmenu(<strong>{ corners: "false" }</strong>);</code></pre>
</dd>
<dt><code>icon</code> <em>string</em></dt>
<dd>
<p class="default">default: "arrow-down"</p>
<p>Sets the icon for the select element from the <a href="../../buttons/buttons-icons.html">icon set</a>. This option is also exposed as a data attribute: <code>data-icon=&quot;star&quot;</code></p>
<pre><code>$('select').selectmenu(<strong>{ icon: "star" }</strong>);</code></pre>
</dd>
<dt><code>iconpos</code> <em>string</em></dt>
<dd>
<p class="default">default: "right"</p>
<p>Position of the icon in the select button. Possible values: left, right, none, notext. The notext value will display the select as an icon-only button with no text feedback. This option is also exposed as a data attribute: <code>data-iconpos=&quot;left&quot;</code></p>
<pre><code>$('select').selectmenu(<strong>{ iconpos: "left" }</strong>);</code></pre>
</dd>
<dt><code>iconshadow</code> <em>boolean</em></dt>
<dd>
<p class="default">default: "true"</p>
<p>Applies the icon drop shadow class to add the theme shadow style to the select button if set to true. This option is also exposed as a data attribute: <code>data-iconshadow=&quot;false&quot;</code></p>
<pre><code>$('select').selectmenu(<strong>{ iconshadow: "false" }</strong>);</code></pre>
</dd>
<dt><code>inline</code> <em>boolean</em></dt>
<dd>
<p class="default">default: "null" (false)</p>
<p>If set to true, this will make the select button act like an inline button so the width is determined by the feedback text inside. By default, this is null (false) so the select button is full width, regardless of the feedback content. Possible values: true, false. This option is also exposed as a data attribute: <code>data-inline=&quot;true&quot;</code></p>
<pre><code>$('select').selectmenu(<strong>{ inline: "true" }</strong>);</code></pre>
</dd>
<dt><code>nativeMenu</code> <em>boolean</em></dt>
<dd>
<p class="default">default: "true"</p>
<p>When set to true, clicking the custom-styled select menu will open the native select menu which is best for performance. If set to false, the custom select menu style will be used instead of the native menu. This option is also exposed as a data attribute: <code>data-native-menu=&quot;false&quot;</code></p>
<pre><code>$('select').selectmenu(<strong>{ nativeMenu: "false" }</strong>);</code></pre>
</dd>
<dt><code>shadow</code> <em>boolean</em></dt>
<dd>
<p class="default">default: "true"</p>
<p>Applies the drop shadow class to add the theme shadow style to the select button if set to true. This option is also exposed as a data attribute: <code>data-shadow=&quot;false&quot;</code></p>
<pre><code>$('select').selectmenu(<strong>{ shadow: "false" }</strong>);</code></pre>
</dd>
<dt><code>theme</code> <em>string</em></dt>
<dd>
<p class="default">default: null, inherited from parent</p>
<p>Sets the theme swatch color scheme for the select element. This is a single letter from a-z that maps to the swatches included in your theme. By default, a select will inherit the same swatch color as it's parent container if not explicitly set. This option is also exposed as a data attribute: <code>data-theme=&quot;a&quot;</code></p>
<pre><code>$('select').selectmenu(<strong>{ theme: "a" }</strong>);</code></pre>
</dd>
</dl>
</form>
</div><!--/content-primary -->
<div class="content-secondary">
<div data-role="collapsible" data-collapsed="true" data-theme="b">
<h3>More in this section</h3>
<ul data-role="listview" data-theme="c" data-dividertheme="d">
<li data-role="list-divider">Form elements</li>
<li><a href="../docs-forms.html">Form basics</a></li>
<li><a href="../forms-all.html">Form element gallery</a></li>
<li><a href="../forms-text.html">Text inputs</a></li>
<li><a href="../forms-search.html">Search inputs</a></li>
<li><a href="../forms-slider.html">Slider</a></li>
<li><a href="../forms-switch.html">Flip toggle switch</a></li>
<li><a href="../forms-radiobuttons.html">Radio buttons</a></li>
<li><a href="../forms-checkboxes.html">Checkboxes</a></li>
<li data-theme="a"><a href="index.html">Select menus</a></li>
<li><a href="../forms-themes.html">Theming forms</a></li>
<li><a href="../forms-all-native.html">Native form elements</a></li>
<li><a href="../forms-sample.html">Submitting forms</a></li>
<li><a href="../plugin-eventsmethods.html">Plugin methods</a></li>
</ul>
</div>
</div>
</div><!-- /content -->
<div data-role="footer" class="footer-docs" data-theme="c">
<p>&copy; 2011 The jQuery Project</p>
</div>
</div><!-- /page -->
</body>
</html>