This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<p>The framework will find all <code>input</code> elements with a <code>type="range"</code> and automatically enhance them into a slider with an accompanying input without any need to apply a <code>data-role</code> attribute. To prevent the automatic enhancement of this input into a slider, add <code>data-role="none"</code> attribute to the input.</p>
<p>In this example, the acceptable range is 0-100.</p>
<p>To force the slider to snap to a specific increment, add the <code>step</code> attribute to the input. By default, the step is 1, but in this example, the step is 50 and the maximum value is 500.</p>
<p>In this example, the acceptable range is 0-100.</p>
<p>This will produce an input that snaps to increments of 50. If a value is added to the input that isn't valid with the step increment, the value will be reset on blur to the closest step.
<p>To have a highlight fill on the track up to the slider handle position, add the <code>data-highlight="true"</code> attribute to the input. The fill uses active state swatch. </p>
<p>For a more compact version that is useful in toolbars and tight spaces, add the <code>data-mini="true"</code> attribute to the element to create a mini version. </p>
<p>Optionally wrap the slider markup in a container with class <code>ui-field-contain</code> to help visually group it in a longer form. In this example, the step attribute is omitted to allow any whole number value to be selected.</p>
<p><strong>Note: The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</strong></p>
<p>This plugin will auto initialize on any page that contains a text input with the <code>type="range"</code> attribute. However, if needed you can directly call the slider plugin on any selector, just like any jQuery plugin:</p>
<pre><code>
<pre><code><![CDATA[
$( "input" ).slider();
</code></pre>
]]></code></pre>
<h3>Theming the slider</h3>
<p>To set the theme swatch for the slider, add a <code>data-theme</code> attribute to the <code>input</code> which will apply the theme to both the input, handle and track. The track swatch can be set separately by adding the <code>data-track-theme</code> attribute to apply the down state version of the selected button swatch.</p>
<p>To create a flip toggle, start with a <code>select</code> with two options. The first option will be styled as the "off" state switch and the second will be styled as the "on" state so write your options accordingly.</p>
<p>Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>input</code> so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.</p>
<p>This will produce a basic flip toggle switch input. The default styles set the width of the switch to 100% of the parent container and stack the label on a separate line.
<p>The control is proportionally scaled, so to use longer labels one can just add a line of CSS setting the switch to the desired width. For example, given the following markup:</p>
<p>For a more compact version that is useful in toolbars and tight spaces, add the <code>data-mini="true"</code> attribute to the element to create a mini version. </p>
<p>Optionally wrap the switch markup in a container with class <code>ui-field-contain</code> to help visually group it in a longer form. In this example, the step attribute is omitted to allow any whole number value to be selected.</p>
<p><strong>Note: The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</strong></p>
<p>Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the <code>data-theme</code> attribute on the <code>select</code> and specify a swatch letter.</p>
<p>It is also possible to theme the track of the flip switch by adding the <code>data-track-theme</code> attribute and specifying the chosen swatch letter on the <code>select</code>.</p>
<p>Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:</p>
<p>Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the <code>data-theme</code> attribute on the select and specify a swatch letter.</p>
<p>This results in a switch with the swatch "a" colors for the handle. Note that the lefthand "on" state gets the active state color.</p>
<p>It is also possible to theme the track of the flip switch by adding the data-track-theme attribute and specifying the chosen swatch letter on the select.</p>
<p>Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:</p>
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<p>The column chooser mode requires a <code>table</code> element with two attributes: <code>data-role="table"</code> and <code>data-mode="columntoggle"</code>. An <code>ID</code> attribute is also required on the table to associate it with the column chooser popup menu.</p>
<p>The table works by hiding and showing columns based on two inputs: available screen width or by the user checking and unchecking which columns to display in a column picker popup. Add <code>data-priority</code> attributes to each of the table headers of columns you want to responsively display and assign a priority (1 = highest, 6 = lowest). Any table header given a priority will be available in the column picker menu. </p>
<p>To make a column <em>persistent</em> so it's not available for hiding, omit the <code>data-priority</code> attribute. This will make the column visible at all widths and won't be available in the column chooser menu.</p>
<pre><code><th>I'm critical and can't be removed</th>
<th data-priority="1">I'm very important</th>
<th data-priority="5">I'm less important</th>
</code></pre>
<pre><code><![CDATA[
<th>I'm critical and can't be removed</th>
<th data-priority="1">I'm very important</th>
<th data-priority="3">I'm somewhat</th>
<th data-priority="5">I'm less important</th>
]]></code></pre>
<p>Behind the scenes, the plugin will apply classes to each cell that map to the priority set in the data attribute on the header. For example, if a table heading has a <code>data-priority="3"</code> attribute, every cell in that column will assigned a <code>ui-table-priority-3</code> class once enhanced. These classes are then used in media queries to hide and show columns based on screen width (see below).</p>
<p>You may use any priority naming convention and assign as many (or few) levels of priority for the columns. The plugin simply generates class names based on the values in the <code>data-priority</code> attribute so even though we default to using a numeric system of 1-6, any naming convention is possible. </p>
@@ -64,7 +68,7 @@
<p>In the example styles below for a <code>my-custom-class</code> class on the table, the priority 1 columns are shown first, at widths above <code>20em</code> (320px), then priority 2 kicks in above <code>30em</code> (480px) and so on up to wide desktop widths with priority 6. Feel free to change these breakpoints in your stylesheet and choose how many priority levels you'd like to use.</p>
<pre><code>
<pre><code><![CDATA[
/* Show priority 1 at 320px (20em x 16px) */
@media screen and (min-width: 20em) {
.my-custom-class th.ui-table-priority-1,
@@ -79,10 +83,10 @@
display: table-cell;
}
}
...more breakpoints...
</code></pre>
/* ...more breakpoints... */
]]></code></pre>
<p>Due to CSS specificity, you will also need to include the class definitions for the hidden and visible states <em>after</em> the custom breakpoints in your custom stylesheet so be sure to include these as well:</p>
<pre><code>
<pre><code><![CDATA[
/* Manually hidden */
.my-custom-class th.ui-table-cell-hidden,
.my-custom-class td.ui-table-cell-hidden {
@@ -94,15 +98,17 @@
.my-custom-class td.ui-table-cell-visible {
display: table-cell;
}
</code></pre>
]]></code></pre>
<h3>Applying a preset breakpoint</h3>
<p>Even though we strongly encourage you to write custom breakpoints yourself, the framework includes a set of pre-configured breakpoints for each of the six priority levels that you can use if they happen work well for your content. </p>
<p>These breakpoints can applied by adding a <code>class="ui-responsive"</code> to the table element. Here is an example of a table with this class added:</p>
<p>The six preset breakpoints classes included in the column toggle stylesheet use regular increments of 10em (160 pixels). Here is a summary of the breakpoints assigned to each priority in the preset styles: </p>
@@ -144,44 +150,111 @@
<p>The popup widget must contain a single controlgroup widget which in turn contains all the checkboxes representing the columns of the table.</p>
<p>In the example below the parameter <code>data-column-btn-theme="b"</code> is added to the table explicitly to indicate that the theme applied to the "Columns..." button is not the default (<code>null</code>).</p>
<td><a href="http://en.wikipedia.org/wiki/Gone_with_the_Wind_(film)" data-rel="external">Gone with the Wind</a></td>
<td>1939</td>
<td>96%</td>
<td>87</td>
</tr>
<tr>
<th>5</th>
<td><a href="http://en.wikipedia.org/wiki/Lawrence_of_Arabia_(film)" data-rel="external">Lawrence of Arabia</a></td>
<td>1962</td>
<td>94%</td>
<td>87</td>
</tr>
<tr>
<th>6</th>
<td><a href="http://en.wikipedia.org/wiki/Dr._Strangelove" data-rel="external">Dr. Strangelove Or How I Learned to Stop Worrying and Love the Bomb</a></td>
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<p>The reflow responsive table mode is the simplest in terms of markup requirements because it only requires a table with a <code>data-role="table"</code> on the table element. There is no need to set the <code>data-mode</code> attribute since <code>reflow</code> is the default.</p>
<p>The plugin works by parsing the values (or <code>abbr title</code>) of the first row of header (<code>th</code>) elements found in the table. For example, in the table above, the third table header is parsed to grab the contents ("Year"):</p>
<pre><code><th>Year</th></code></pre>
<pre><code><![CDATA[
<th>Year</th>
]]></code></pre>
<p>The script then appends an element with the table header text <em>before</em> the contents of every cell in that column. For example, for every table cell in the year column:</p>
<pre><code><td>1941</td></code></pre>
<pre><code><![CDATA[
<td>1941</td>
]]></code></pre>
<p>An element is added before the text of each cell with a <code>class</code> of <code>ui-table-cell-label</code>:</p>
<p>With our mobile-first approach, the base styles for a reflow table stacks each row and presents each cell in the label/data style format. This is done by hiding the table header rows, making each table cell <code>display:block</code> so they are stacked. The the label element injected into each cell is styled as <code>display:inline-block</code> with a <code>min-width:30%</code> rule to place the labels on the same line as the content at a consistent width to form a two column presentation.</p>
@@ -37,7 +45,7 @@
<p>This is done by wrapping a few simple CSS rules in and a media query that only applies the rules above a certain width breakpoint. The styles make the table header rows visible, display the cells in a tabular format, and hide the generated label elements within each. Here is an example media query that swaps the presentation at 40em (640 pixels): </p>
<pre><code>@media ( min-width: 40em ) {
<pre><code><![CDATA[@media ( min-width: 40em ) {
/* Show the table header rows and set all cells to display: table-cell */
.my-custom-breakpoint td,
.my-custom-breakpoint th,
@@ -54,7 +62,7 @@
display: none;
}
}
</code></pre>
]]></code></pre>
<p>It's best to use a <code>class</code> on the table to apply the breakpoint. Add these rules to your custom stylesheet that is included in the <code>head</code> of the page. We recommend creating a set of custom breakpoint classes that can be used to apply standard table breakpoints in your project.</p>
@@ -70,7 +78,9 @@
<h3>Applying a preset breakpoint</h3>
<p>Even though we strongly encourage you to write custom breakpoints yourself, the framework includes a single pre-configured breakpoint that targets the stacked style to smaller phones and swaps to a tabular prsentation on larger phones, tablet and desktop devices. To use this preset breakpoint, add the <code>ui-responsive</code> class to the table to convert from the stacked presentation to a tabular presentation at 560px (35em). If this breakpoint doesn't work for your content, we encourage you to write a custom breakpoint as descibed above.</p>
<desc>This is used to define the selectors (element types, data roles, etc.) that will automatically be initialized as tables. To change which elements are initialized, bind this option to the mobileinit event:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<p>Both table modes start with standard HTML table markup but there are some specific guidelines you must follow for the responsive table to work correctly: </p>
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<p>To collect standard alphanumeric text, use an <code>input</code> with a <code>type="text"</code> attribute. Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>input</code> so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.</p>
<p>This will produce a basic text input. The default styles set the width of the input to 100% of the parent container and stack the label on a separate line.
<p>For a more compact version that is useful in toolbars and tight spaces, add the <code>data-mini="true"</code> attribute to the element to create a mini version.</p>
<p>The <code>clearButton</code> extension provides the <code>clearBtn</code> option.</p>
<p>To add a clear button to any input (like the search input), add the <code>data-clear-btn="true"</code> attribute. The text for this clear button can be customized via the <code>data-clear-btn-text="clear input"</code> attribute. Search buttons have the clear button by default and cannot be controlled by this option. Note that this is available for all the input types below except for those coded via <code>textarea</code> elements.</p>
<p>Optionally wrap the text input in a container with class <code>ui-field-contain</code> to help visually group it in a longer form.</p>
<p><strong>Note: The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</strong></p>
<p>Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>textarea</code> so they are semantically associated, and wrap them in a <code>div</code> with class <code>ui-field-contain</code> to group them.</p>
<p><strong>Note: The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</strong></p>
I'm a basic textarea. If this is pre-populated with content, the height will be automatically adjusted to fit without needing to scroll. That is a pretty handy usability feature.
</textarea>
</code></pre>
<pre><code><![CDATA[
<label for="textarea-a">Textarea:</label>
<textarea name="textarea" id="textarea-a">
I'm a basic textarea. If this is pre-populated with content, the height will be automatically adjusted to fit without needing to scroll. That is a pretty handy usability feature.
</textarea>
]]></code></pre>
<p>This will produce a basic textarea with the width set to 100% of the parent container and the label stacked on a separate line. The textarea will grow to fit new lines as you type:
<p>This plugin will auto initialize on any page that contains a textarea or any of the text input types listed above without any need for a <code>data-role</code> attribute in the markup. However, if needed, you can directly call the <code>textinput</code> plugin on any selector, just like any jQuery plugin:</p>
<pre><code>
<pre><code><![CDATA[
$( "input" ).textinput();
</code></pre>
]]></code></pre>
<h3>Degraded input types</h3>
@@ -110,21 +110,21 @@ $( "input" ).textinput();
<p>Search inputs are a new HTML type styled with pill-shaped corners and an "x" icon to clear the field once you start typing. Start with an input with a type="search" attribute in your markup.</p>
<p>Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>input</code> so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.</p>
<p>This will produce a basic search input. The default styles set the width of the input to 100% of the parent container and stack the label on a separate line.
<p>For a more compact version that is useful in toolbars and tight spaces, add the <code>data-mini="true"</code> attribute to the element to create a mini version.</p>
<p>Optionally wrap the search input in a container with tlass <code>ui-field-contain</code> to help visually group it in a longer form.</p>
<p><strong>Note: The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</strong></p>
<p>This plugin will auto-initialize on any page that contains a text input with the <code>type="search"</code> attribute without any need for a <code>data-role</code> attribute in the markup. However, if needed, you can directly call the <code>textinput</code> plugin on a selector, just like any jQuery plugin:</p>
<p>The <placeholdername="name"/> widget wraps <code>input</code>-based widgets in <code>div</code> used for creating the style. <code>textarea</code> elements are not wrapped in such a <code>div</code>.</p>
<p>In the example below, we add the attribute <code>data-corners="false"</code> to the input, because the class <code>ui-corner-all</code> is absent from the wrapper, indicating that the value of the "corners" option should be false.</p>
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<p>The header is a <placeholdername="name"/> at the top of the page that usually contains the page title text and optional buttons positioned to the left and/or right of the title for navigation or actions. Headers can optionally be positioned as fixed so they remain at the top of the screen at all times instead of scrolling with the page.</p>
<p>The title text is normally an H1 heading element but it's possible to use any heading level (H1-H6) to allow for semantic flexibility. For example, a page containing multiple mobile "pages" may use a H1 element on the home "page" and a H2 element on the secondary pages. All heading levels are styled identically by default to maintain visual consistency.</p>
<p><strong>The behavior whereby the first two buttons automatically get the <code>ui-btn-left</code> and <code>ui-btn-right</code> classes is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must add those classes in your markup if you wish to position the buttons left and/or right.</strong></p>
<p>The <placeholdername="name"/> plugin looks for immediate children of the header container, and automatically sets the first link in the left button slot and the second link in the right. In this example, the 'Cancel' button will appear in the left slot and 'Save' will appear in the right slot based on their sequence in the source order. </p>
<p>Buttons automatically adopt the swatch color of the bar they sit in, so a link in a header bar with the "a" color will also be styled as "a" colored buttons. It's simple to make a button visually stand out. Here, we add the <code>data-theme</code> attribute and set the color swatch for the button to "b" to make the "Save" button stand out.</p>
<p>The button position can also be controlled by adding classes to the button anchors, rather than relying on source order. This is especially useful if you only want a button in the right slot. To specify the button position, add the class of <code>ui-btn-left</code> or <code>ui-btn-right</code> to the anchor.</p>
<h3>Adding buttons to <placeholdername="name"/> widgets without heading</h3>
<p>The heading in the header bar has some margin that will give the bar its height. If you choose not to use a heading, you will need to add an element with <code>class="ui-title"</code> so that the bar can get the height and display correctly.</p>
@@ -99,11 +99,11 @@ If you're doing this programmatically, set this option inside the mobileinit eve
<p>If you need to create a header that doesn't follow the default configuration, simply wrap your custom styled markup in any container, such as <code>div</code>. The plugin won't apply the automatic button logic to the wrapped content inside the header container so you can write custom styles for laying out the content in your header.</p>
<p>It's also possible to create custom bars without using the header data-role at all. For example, start with any container and add the <code>ui-bar</code> class to apply standard bar padding and add the <code>ui-bar-b</code> class to assign the bar swatch styles from your theme. (The "b" can be any swatch letter.)</p>
<pre><code>
<div class="ui-bar ui-bar-b">
<h3>I'm just a div with bar classes and a mini inline <a href="#" data-role="button" data-mini="true">Button</a></h3>
</div>
</code></pre>
<pre><code><![CDATA[
<div class="ui-bar ui-bar-b">
<h3>I'm just a div with bar classes and a mini inline <a href="#" data-role="button" data-mini="true">Button</a></h3>
@@ -118,11 +118,11 @@ If you're doing this programmatically, set this option inside the mobileinit eve
<h3>Footer bar structure</h3>
<p>The <code>footer</code> bar has the same basic structure as the header except it uses the <code>data-role</code> attribute value of <code>footer</code>.</p>
<p>The footer <placeholdername="name"/> inherits its theme swatch from the <ahref="/page/">page</a> by default but you can easily set the theme swatch color by adding the <code>data-theme</code> attribute to the header. For example, <code>data-theme="b"</code>. When you use external headers you must set a theme, because there is no parent page from which it can inherit a theme.</p>
@@ -136,13 +136,13 @@ If you're doing this programmatically, set this option inside the mobileinit eve
<p>Any link or valid button markup with a <code>data-role="button"</code> attribute added to the footer will automatically be turned into a button. To save space, buttons in <placeholdername="name"/> widgets are automatically set to inline styling so the button is only as wide as the text and icons it contains.</p>
<p>By default, <placeholdername="name"/> widgets don't have any padding to accommodate nav bars and other widgets. To include padding on the bar, add a <code>class="ui-bar"</code> to the footer.</p>
@@ -151,7 +151,9 @@ If you're doing this programmatically, set this option inside the mobileinit eve
<p>To group buttons together into a button set, wrap the links in a wrapper with <code>data-role="controlgroup"</code> and <code>data-type="horizontal"</code> attributes.</p>
@@ -171,18 +173,18 @@ If you're doing this programmatically, set this option inside the mobileinit eve
<p>To enable this behavior on a header or footer, add the <code>data-position="fixed"</code> attribute to a jQuery Mobile <placeholdername="name"/> element.</p>