Here, we have some text so that we can have
some vertical space in order to demonstrate
- the silentScroll() method.
Back to Top
Buttons are coded with standard HTML anchor and input elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device. Use anchor links (a elements) to mark up navigation buttons, and input or button elements for form submission.
In the main content block of a page, you can style any anchor link as a button by adding the data-role="button" attribute. The framework will enhance the link with markup and classes to style the link as a button. For example, this markup:
Buttons are coded with standard HTML input elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device.
-<a href="index.html" data-role="button">Link button</a>
-Produces this link-based button: -
- -Note: Links styled like buttons have all the same visual options as true form-based buttons below, but there are a few important differences. Link-based buttons aren't part of the button plugin and only just use the underlying buttonMarkup plugin to generate the button styles so the form button methods (enable, disable, refresh) aren't supported. If you need to disable a link-based button (or any element), it's possible to apply the disabled class ui-disabled yourself with JavaScript to achieve the same effect.
-<a href="index.html" data-role="button" class="ui-disabled">Link button</a>
-Produces this disabled link-based button: - -
- -For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the button to create a mini version.
-<a href="index.html" data-role="button" data-mini="true">Link button</a>
-This will produce a button that is not as tall as the standard version and has a smaller text size. - -
-For ease of styling, the framework automatically converts any button or input element with a type of submit, reset, or button into a custom styled button - there is no need to add the data-role="button" attribute. However, if needed, you can directly call the button plugin on any selector, just like any jQuery plugin:
-$( "[type="submit"]" ).button();
-Button based button:
- -
-<button>Button element</button>
-For ease of styling, the framework automatically converts any input element with a type of submit, reset, or button into a custom styled button - there is no need to add the data-role="button" attribute. However, if needed, you can directly call the
Input type="button" based button:
-
-<input type="button" value="Button" />
-Input type="button" based
Input type="submit" based button:
-
-<input type="submit" value="Submit Button" />
-Input type="reset" based button:
-
-<input type="reset" value="Reset Button" />
-The jQuery Mobile framework includes a selected set of icons most often needed for mobile apps. To minimize download size, jQuery Mobile includes a single white icon sprite, and automatically adds a semi-transparent black circle behind the icon to ensure that it has good contrast on any background color.
- - -An icon can be added to a button by adding a data-icon attribute on the anchor specifying the icon to display. For example, the following markup:
-<a href="index.html" data-role="button" data-icon="delete">Delete</a>
-The following data-icon attributes can be referenced to create the icons shown below:
-
By default, all icons in buttons are placed to the left of the button text. -
- -This default may be overridden using the data-iconpos attribute to set the icon to the right, above (top) or below (bottom) the text. For example, the markup:
-<a href="index.html" data-role="button" data-icon="delete" data-iconpos="right">Delete</a>
-You can also create an icon-only button, by setting the data-iconpos attribute to notext. The button plugin will hide the text on-screen, but add it as a title attribute on the link to provide context for screen readers and devices that support tooltips. For example, replacing data-iconpos="right" on the previous example with data-iconpos="notext":
Input type="submit" based
-<a href="index.html" data-role="button" data-icon="delete" data-iconpos="notext">Delete</a>
-Creates this icon-only button: -
- -The mini and inline attributes can be added to produce more compact buttons: -
- -To use custom icons, specify a data-icon value that has a unique name like myapp-email and the button plugin will generate a class by prefixing ui-icon- to the data-icon value and apply it to the button: ui-icon-myapp-email.
You can then write a CSS rule in your stylesheet that targets the ui-icon-myapp-email class to specify the icon background source. To maintain visual consistency with the rest of the icons, create a white icon 18x18 pixels saved as a PNG-8 with alpha transparency.
In this example, we're just pointing to a standalone icon image, but you could just as easily use an icon sprite and specify the positioning instead, just like the icon sprite we use in the framework.
- -.ui-icon-myapp-email {
- background-image: url( "app-icon-email.png" );
-}This will create the standard resolution icon, but many devices now have very high resolution displays, like the retina display on the iPhone 4. To add a HD icon, create an icon that is 36x36 pixels (exactly double the 18 pixel size), and add second a rule that uses the -webkit-min-device-pixel-ratio: 2 media query to target a rule only to high resolution displays. Specify the background image for the HD icon file and set the background size to 18x18 pixels which will fit the 36 pixel icon into the same 18 pixel space. The media query block can wrap multiple icon rules:
-@media only screen and (-webkit-min-device-pixel-ratio: 2) {
- .ui-icon-myapp-email {
- background-image: url( "app-icon-email-highres.png" );
- background-size: 18px 18px;
- }
- ...more HD icon rules go here...
-}
-The semi-transparent black circle behind the white icon ensures good contrast on any background color so it works well with the jQuery Mobile theming system. Here are examples of the same icons sitting on top of a range of different color swatches with themed buttons.
- --
- -By default, all buttons in the body content are styled as block-level elements so they fill the width of the screen: -
- - -If you have multiple buttons that should sit side-by-side on the same line, add the data-inline="true" attribute to each button. This will style the buttons to be the width of their content and float the buttons so they sit on the same line.
-<a href="index.html" data-role="button" data-inline="true">Cancel</a>
-<a href="index.html" data-role="button" data-inline="true" data-theme="b">Save</a>
-Input type="reset" based
If you want buttons to sit side-by-side but stretch to fill the width of the screen, you can use the content column grids to put normal full-width buttons into 2- or 3-columns.
+ -Occasionally, you may want to visually group a set of buttons to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the data-role="controlgroup" attribute - the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together.
-<div data-role="controlgroup">
- <a href="index.html" data-role="button">Yes</a>
- <a href="index.html" data-role="button">No</a>
- <a href="index.html" data-role="button">Maybe</a>
-</div>
-The div around the input.
In the example below, pre-rendered markup for a data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the wrapper element indicates that the "corners" widget option is to be false.
By default, grouped buttons are presented as a vertical list: -
- -By adding the data-type="horizontal" attribute to the controlgroup container, you can swap to a horizontal-style group that floats the buttons side-by-side and sets the width to only be large enough to fit the content. (Be aware that these will wrap to multiple lines if the number of buttons or the overall text length is too wide for the screen.)
-
- -Because the label element will be associated with each individual input or button and will be hidden for styling purposes, we recommend wrapping the buttons in a fieldset element that has a legend which acts as the combined label for the group. Using the label as a wrapper around an input prevents the framework from hiding it, so you have to use the for attribute to associate the label with the input.
jQuery Mobile has a rich theming system that gives you full control of how buttons are styled. When a link is added to a container, it is automatically assigned a theme swatch letter that matches its parent bar or content box to visually integrate the button into the parent container, like a chameleon. So a button placed inside a content container with a theme of "a" (black in the default theme) will be automatically assigned the button theme of "a" (charcoal in the default theme). Here are examples of the button theme pairings in the default theme. All buttons have the same HTML markup: -
+Buttons can be manually assigned any of the button color swatches from the theme to add visual contrast with the container they sit inside by adding the data-theme attribute on the button markup and specifying a swatch letter.
-<a href="index.html" data-role="button" data-theme="a">Swatch a</a>
-Here are 5 buttons with icons that have a different swatch letter assigned via the data-theme attribute.
-
-$( "[type='submit']" ).button( "enable" );
-
-$( "[type='submit']" ).button( "disable" );
-If you manipulate a form button via JavaScript, you must call the refresh method on it to update the visual styling.
-
+ update the form If you manipulate a form
+
+]]> button or a elements by simply adding classes.
+
+ ui-btn-icon-left is added to make sure the icon (ui-icon-arrow-r) will be displayed.
+You can use .buttonMarkup() to style any element as a button that is attractive and useable on a mobile device. It is a convenience function that allows you to manipulate the classes related to button styling. For each element in the set of matched elements this function converts the options parameter to a list of classes to be applied to the element, while respecting the element's existing classes that are not related to button styling. You may also set the parameter overwriteClasses to true for performance reasons. When overwriteClasses is set to true the function discards existing classes and applies the classes corresponding to the options provided.
The framework will automatically apply button styling to anchors that have the attribute data-role="button" as well as button elements, anchors contained directly in bars and controlgroup widgets. You can specify button styling options via data attributes that you add to the anchor or button element. The data attribute corresponding to each .buttonMarkup() option is documented in the options of .buttonMarkup(). The example below shows the markup needed for an anchor-based button.
Produces this anchor-based button: +
+ +Button based button:
+ +.buttonMarkup() also automatically enhances button elements such as the one below:
You can style an anchor as disabled by adding the class ui-state-disabled.
Note: It is not inherently possible to "disable" anchors. The class ui-state-disabled merely adds styling to make the anchor look disabled. It does not provide the same level of functionality as the disabled attribute of a form button. It may still be possible to follow the anchor using navigation methods that do not involve the pointing device.
Produces an anchor-based button styled as disabled: + +
+ +In the case of button elements, you should apply the ui-state-disabled class when you set the button element's disabled attribute:
By default, all buttons in the body content are styled as block-level elements so they fill the width of the screen: +
+ +If you have multiple buttons that should sit side-by-side on the same line, add the data-inline="true" attribute to each button. This will style the buttons to be the width of their content and float the buttons so they sit on the same line.
If you want buttons to sit side-by-side but stretch to fill the width of the screen, you can use the content column grids to put normal full-width buttons into 2- or 3-columns.
+ +For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the button to create a mini version.
This will produce a button that is not as tall as the standard version and has a smaller text size. + +
+ +The jQuery Mobile framework includes a selected set of icons most often needed for mobile apps. To minimize download size, jQuery Mobile includes a single white icon sprite, and automatically adds a semi-transparent black circle behind the icon to ensure that it has good contrast on any background color.
+ +An icon can be added to a button by adding a data-icon attribute on the anchor specifying the icon to display. For example:
The following data-icon attributes can be referenced to create the icons shown below:
+
By default, all icons in buttons are placed to the left of the button text. +
+ +This default may be overridden using the data-iconpos attribute to set the icon to the right, above (top) or below (bottom) the text. For example:
You can also create an icon-only button, by setting the data-iconpos attribute to notext. The button plugin will hide the text on-screen, but add it as a title attribute on the link to provide context for screen readers and devices that support tooltips. For example, replacing data-iconpos="right" on the previous example with data-iconpos="notext":
Creates this icon-only button: +
+ +The mini and inline attributes can be added to produce more compact buttons: +
+ +To use custom icons, specify a data-icon value that has a unique name like myapp-email and the button plugin will generate a class by prefixing ui-icon- to the data-icon value and apply it to the button: ui-icon-myapp-email.
You can then write a CSS rule in your stylesheet that targets the ui-icon-myapp-email:after class to specify the icon background source. The framework contains an inline (data URI) SVG test and adds class ui-nosvg to the html element if this is not supported. If you are using SVG icons you can use this class to provide a fallback to external PNG icons.
The semi-transparent black circle behind the white icon ensures good contrast on any background color so it works well with the jQuery Mobile theming system. Here are examples of the same icons sitting on top of a range of different color swatches with themed buttons.
+ ++
+ +Occasionally, you may want to visually group a set of buttons to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the data-role="controlgroup" attribute - the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together.
By default, grouped buttons are presented as a vertical list: +
+ +By adding the data-type="horizontal" attribute to the controlgroup container, you can swap to a horizontal-style group that floats the buttons side-by-side and sets the width to only be large enough to fit the content. (Be aware that these will wrap to multiple lines if the number of buttons or the overall text length is too wide for the screen.)
+
+ +Because the label element will be associated with each individual input or button and will be hidden for styling purposes, we recommend wrapping the buttons in a fieldset element that has a legend which acts as the combined label for the group. Using the label as a wrapper around an input prevents the framework from hiding it, so you have to use the for attribute to associate the label with the input.
jQuery Mobile has a rich theming system that gives you full control of how buttons are styled. When a link is added to a container, it is automatically assigned a theme swatch letter that matches its parent bar or content box to visually integrate the button into the parent container, like a chameleon. So a button placed inside a content container with a theme of "a" will be automatically assigned the button theme of "a". Here are examples of the button theme pairings in the default theme. All buttons have the same HTML markup: +
+ +Buttons can be manually assigned any of the button color swatches from the theme to add visual contrast with the container they sit inside by adding the data-theme attribute on the button markup and specifying a swatch letter.
Here are 2 buttons with icons that have a different swatch letter assigned via the data-theme attribute.
+
ui-corner-all when true and removes it when false. This gives the button-styled element rounded corners.
+ This option is also exposed as a data-attribute: data-corners="false"
iconpos option.
+ For example, if the value is "arrow-r" and the value of the iconpos option is "left", then .buttonMarkup() will add the classes ui-icon-arrow-r and ui-btn-icon-left to each of the set of matched elements.
This option is also exposed as a data-attribute: data-icon="arrow-r"
For example, if the value is "right" and the button-styled element has an icon, then the class ui-btn-icon-right will be added to each of the set of matched elements.
This option is also exposed as a data-attribute: data-iconpos="right"
Adds the class ui-shadow-icon to each of the set of matched elements when set to true and the button-styled element has an icon.
This option is also exposed as a data-attribute: data-iconshadow="true"
ui-btn-inline to each of the set of matched elements when set to true.
+ This option is also exposed as a data-attribute: data-inline="true"
ui-mini to each of the set of matched elements when set to true.
+ This option is also exposed as a data-attribute: data-mini="true"
ui-shadow to each of the set of matched elements when set to true.
+ This option is also exposed as a data-attribute: data-shadow="false"
null.
+ This option adds a class constructed by appending the string "ui-btn-" to the value to each of the set of matched elements. If set to null, no class is added, and the swatch is inherited from the element's parent.
For example, a value of "b" will cause the class ui-btn-b to be added to each of the set of matched elements.
This option is also exposed as a data-attribute: data-theme="b"
true, .buttonMarkup() discards all classes on each of the set of matched elements and adds classes based on the values passed into the options argument. You can use this feature to increase performance in situations where the element you wish to enhance does not have any classes other than the button styling classes added by .buttonMarkup().
+ Conversely, when set to false, .buttonMarkup() first parses the existing classes found on each of the set of matched elements and computes a set of existing options based on the presence or absence of classes related to button styling already present. It separately records any classes unrelated to button styling. It then merges the options specified in the options parameter with the computed options such that the options passed in take precedence, and calculates a list of classes that must be present for those options to be expressed in the element's styling. It then re-applies the classes unrelated to button styling as well as the classes that reflect the new set of options. This means that calling .buttonMarkup() on the same element multiple times will have the expected effect:
+// Initially corners are turned off
+$( "#myAnchor" ).buttonMarkup({ corners: false });
+
+// Later on we turn off shadow - the lack of corners is retained
+$( "#myAnchor" ).buttonMarkup({ shadow: false });
+
+// Later still we turn corners back on - the lack of shadow is retained
+$( "#myAnchor" ).buttonMarkup({ corners: true });
+Checkboxes are used to provide a list of options where more than one can be selected. Traditional desktop checkboxes are not optimized for touch input so in jQuery Mobile, we style the label for the checkboxes so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.
Checkboxes are used to provide a list of options where more than one can be selected. Traditional desktop checkboxes are not optimized for touch input so in jQuery Mobile, we style the label for the checkboxes so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.
The checkbox controls below use standard input/label markup, but are styled to be more touch-friendly. The styled control you see is actually the label element, which sits over the real input, so if images fail to load, you'll still have a functional control. In most browsers, clicking the label automatically triggers a click on the input, but we've had to trigger the update manually for a few mobile browsers that don't do this natively. On the desktop, these controls are keyboard and screen-reader accessible.
-To create a single checkbox, add an input with a type="checkbox" attribute and a corresponding label. If the input isn’t wrapped in its corresponding label, be sure to set the for attribute of the label to match the id of the input so they are semantically associated.
To create a single checkbox, add an input with a type="checkbox" attribute and a corresponding label. If the input isn't wrapped in its corresponding label, be sure to set the for attribute of the label to match the id of the input so they are semantically associated.
-<label><input type="checkbox" name="checkbox-0" /> I agree </label>
+
The above snippets will produce two basic checkboxes. The default styles will set the width of the element to 100% of the parent container.
Mini version
- For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
+ For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-
-<input type="checkbox" name="checkbox-mini" id="checkbox-mini-1" class="custom" data-mini="true" />
-<label for="checkbox-mini-1">I agree</label>
-
+
This will produce a checkbox that is not as tall as the standard version and has a smaller text size.
Field containers & Legends
+ Optionally wrap the checkboxes in a container with class ui-field-contain to help visually group it in a longer form.
+
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
+
+
Because checkboxes use the label element for the text displayed next to the checkbox form element, we recommend wrapping the checkbox in a fieldset element that has a legend which acts as the title for the question. Add the data-role="controlgroup" attribute to the fieldset so it can be styled in a parallel way as text inputs, selects or other form elements.
-
-<div data-role="fieldcontain">
- <fieldset data-role="controlgroup">
- <legend>Agree to the terms:</legend>
- <input type="checkbox" name="checkbox-2" id="checkbox-2" class="custom" />
- <label for="checkbox-2">I agree</label>
- </fieldset>
-</div>
-
+
Vertically grouped checkboxes
- Checkboxes can also be used for grouped button sets where more than one button can be selected at once, such as the bold, italic and underline button group seen in word processors. To make a horizontal button set, add the data-type="horizontal" to the fieldset.
+
Checkboxes can also be used for grouped button sets where more than one button can be selected at once, such as the bold, italic and underline button group seen in word processors. To make a horizontal button set, add the data-type="horizontal" to the fieldset.
-
-<fieldset data-role="controlgroup" data-type="horizontal" >
-
+
The framework will float the labels so they sit side-by-side on a line, hide the checkbox icons and only round the left and right edges of the group.
Radio buttons
- Radio buttons are used to provide a list of options where only a single item can be selected. Traditional desktop radio buttons are not optimized for touch input so jQuery Mobile styles the label for the radio buttons so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.
+ Radio buttons are used to provide a list of options where only a single item can be selected. Traditional desktop radio buttons are not optimized for touch input so jQuery Mobile styles the label for the radio buttons so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.
The radio button controls below use standard input/label markup, but are styled to be more touch-friendly. The styled control you see is actually the label element, which sits over the real input, so if images fail to load, you'll still have a functional control. In most browsers, clicking the label automatically triggers a click on the input, but we've had to trigger the update manually for a few mobile browsers that don't do this natively. On the desktop, these controls are keyboard and screen-reader accessible.
Vertically grouped radio buttons
-
+
To create a set of radio buttons, add an input with a type="radio" attribute and a corresponding label. Set the for attribute of the label to match the id of the input so they are semantically associated.
The label element is displayed next to the radio form element. Wrap the radio buttons in a fieldset element that has a legend which acts as the title for the question.
To visually integrate multiple radio buttons into a vertically grouped button set, the framework will automatically remove all margins between buttons and round only the top and bottom corners of the set if there is a data-role="controlgroup" attribute on the container.
-
-<fieldset data-role="controlgroup">
- <legend>Choose a pet:</legend>
- <input type="radio" name="radio-choice" id="radio-choice-1" value="choice-1" checked="checked" />
- <label for="radio-choice-1">Cat</label>
+
This will produce a vertically grouped radio button set. The default styles set the width of the button group to 100% of the parent container and stacks the label on a separate line.
@@ -90,44 +95,47 @@
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-
-<fieldset data-role="controlgroup" data-mini="true">
- <input type="radio" name="radio-mini" id="radio-mini-1" value="choice-1" checked="checked" />
- <label for="radio-mini-1">Credit</label>
+
This will produce a radio button that is not as tall as the standard version and has a smaller text size.
Field containers
- Optionally wrap the radiobuttons in a container with the data-role="fieldcontain" attribute to help visually group it in a longer form.
+ Optionally wrap the radio buttons in a container with class ui-field-contain to help visually group it in a longer form.
+
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
+
-
-<div data-role="fieldcontain">
- <fieldset data-role="controlgroup">
- <legend>Choose a pet:</legend>
- <input type="radio" name="radio-choice-2" id="radio-choice-21" value="choice-1" checked="checked" />
- <label for="radio-choice-1">Cat</label>
+
@@ -135,53 +143,58 @@
Radio buttons can also be used for grouped button sets where only a single button can be selected at once, such as a view switcher control. To make a horizontal radio button set, add the data-type="horizontal" to the fieldset.
-
-<fieldset data-role="controlgroup" data-type="horizontal" >
-
+
The labels float so they sit side-by-side on a line. The radio button icons are hidden and only the left and right edges of the group are rounded.
-
+
+ The checkboxradio widget wraps the input element in a div and prepends the label element to the div.
+ In the example below, pre-rendered markup for a checkbox is provided. The attribute data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the label element indicates that the value of the "corners" widget option is to be false.
+
+
+
+
+
If you manipulate a checkboxradio via JavaScript, you must call the refresh method on it to update the visual styling.
jQuery Mobile uses the following style classes:
+ui-corner-all |
+ Adds rounded corners to the element. | +
ui-shadow |
+ Adds an item shadow around the element. | +
ui-overlay-shadow |
+ Adds an overlay shadow around the element. The intended effect is for the element to appear to float above other elements. | +
ui-mini |
+ Reduces the font size and scales down paddings proportionally to produce a miniature version of the element for use in toolbars and tight spaces. | +
These classes can be applied any of the framework's widgets.
+ui-collapsible-inset |
+ The collapsible widget has horizontal margins, borders, and rounded corners when this class is applied. | +
ui-listview-inset |
+ The listview widget has horizontal margins, borders, and rounded corners when this class is applied. | +
In addition to the style classes, you can add the following classes to a (anchor) and button elements to render them touch-friendly:
| Basic options | |
|---|---|
ui-btn |
+ You must add this class to indicate that the element is to be styled as a button. This is a prerequisite for adding any other button-related classes. | +
ui-btn-inline |
+ Displays the button inline. This means that it will only consume as much space as is needed for the label. This allows you to place buttons side by side, flowing with the text. | +
ui-shadow-icon |
+ Draws a shadow around the icon. Note: This class is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. | +
| Icon positioning | |
ui-btn-icon-top |
+ The icon appears above the text | +
ui-btn-icon-right |
+ The icon appears to the right of the text | +
ui-btn-icon-bottom |
+ The icon appears below the text | +
ui-btn-icon-left |
+ The icon appears to the left of the text | +
ui-btn-icon-notext |
+ The button text is suppressed, and only the icon is shown. The result is a circular button the size of the icon. | +
| Theme | |
ui-btn-[a-z] |
+ Sets the color scheme (swatch) for the button. Use a single letter from a-z that maps to the swatches included in your theme. For example: ui-btn-b |
+
Icons are used by a variety of widgets. The table below lists all the available icon classes. The widgets which support an icon usually have an option named "icon". The value for that option is the name of the icon, which is appended to the prefix ui-icon- to create the icon class name. In the class list below, the icon names are emphasized as part of the icon class name.
ui-icon-alert |
+ An exclamation mark inside a triangle. | +
ui-icon-arrow-l |
+ An arrow pointing left (←). | +
ui-icon-arrow-r |
+ An arrow pointing right (→). | +
ui-icon-arrow-u |
+ An arrow pointing up (↑). | +
ui-icon-arrow-d |
+ An arrow pointing down (↓). | +
ui-icon-back |
+ A curved arrow arcing counterclockwise upwards. | +
ui-icon-bars |
+ Three horizontal bars one above the other. | +
ui-icon-carat-b |
+ A carat pointing down (v). | +
ui-icon-carat-l |
+ A carat pointing left (>). | +
ui-icon-carat-r |
+ A carat pointing right (<). | +
ui-icon-carat-t |
+ A carat pointing up (^). | +
ui-icon-check |
+ A checkmark (✓). | +
ui-icon-delete |
+ A diagonal cross similar to (✕). | +
ui-icon-edit |
+ A pencil - similar to (✎) but pointing to the lower left. | +
ui-icon-forward |
+ A curved arrow arcing clockwise upwards. | +
ui-icon-gear |
+ A gear (⚙). | +
ui-icon-grid |
+ A 3✕3 grid. | +
ui-icon-home |
+ A house similar to (⌂). | +
ui-icon-minus |
+ A "minus" sign (-). | +
ui-icon-plus |
+ A "plus" sign (+). | +
ui-icon-refresh |
+ A circular arrow similar to (⟳). | +
ui-icon-search |
+ A magnifying glass. | +
ui-icon-star |
+ A star similar to (✭). | +
The class prefixes in the table below are used for applying a swatch to various parts of the user interface. The actual class name is constructed by appending the swatch letter (a-z) to the prefix. For example, the class ui-body-a is the swatch applied to the page.
ui-bar-[a-z] |
+ Sets the color scheme (swatch) for a bar. This includes headers and footers, or bars you include in the page. | +
ui-body-[a-z] |
+ Sets the color scheme (swatch) for a content block. This includes page content panes (deprecated as of 1.4.0), listview items, popups, collapsibles, the loader widget, sliders, and panels. | +
ui-btn-[a-z] |
+ Sets the color scheme (swatch) for a button. | +
ui-group-theme-[a-z] |
+ Sets the color scheme (swatch) for controlgroups, listviews, and collapsible sets (accordions). | +
ui-overlay-[a-z] |
+ Sets the color scheme (swatch) for backgrounds such as those of popup widgets, and page containers. | +
ui-page-theme-[a-z] |
+ Sets the color scheme (swatch) for pages. | +
ui-panel-page-container-[a-z] |
+ Panels temporarily set the theme on the page container using this class. | +
Collapsible sets start with the exact same markup as individual collapsibles.
- By adding a parent wrapper with a data-role="collapsible-set" attribute around a number of collapsibles, the framework will style these to looks like a visually grouped widget and make it behave like an accordion so only one section can be open at a time.
By default, all the sections will be collapsed. To set a section to be open when the page loads, add the data-collapsed="false" attribute to the heading of the section you want expanded.
-<div data-role="collapsible-set">
-
- <div data-role="collapsible" data-collapsed="false">
- <h3>Section 1</h3>
- <p>I'm the collapsible set content for section 1.</p>
- </div>
-
- <div data-role="collapsible">
- <h3>Section 2</h3>
- <p>I'm the collapsible set content for section 2.</p>
- </div>
-
-</div>
-Here is an example of a collapsible set with 5 sections. -
- -For full width collapsibles without corner styling add the data-inset="false" attribute to the set.
-
For a more compact version that is useful in tight spaces, add the data-mini="true" attribute to the set to create a mini version.
-
Collapsible headings’ default icons can be overridden by using the data-collapsed-icon and data-expanded-icon attributes, either at the collapsible-set level or on an individual collapsible basis.
-
Collapsible headings’ default icon positioning can be overridden by using the data-iconpos attribute, either at the collapsible-set level or on an individual collapsible basis.
-
The standard data-theme attribute can be used to set the color of each collapsible in a set. To provide a clearer visual grouping of the content with the headers, add the data-content-theme attribute with a swatch letter. This adds a themed background color and border to the content block. For consistent theming, add these attributes to the parent collapsible set.
-
-
<div data-role="collapsible-set" data-theme="c" data-content-theme="d">
-To have individual sections in a group styled differently, add data-theme and data-content-theme attributes to specific collapsibles.
-
To expand or collapse items in a set, call the respective methods on individual collapsibles. The selector for the collapse method can include multiple items in a set: -
-
-$( "#myCollapsibleSet" ).children().trigger( "collapse" );
-If you manipulate a collapsible set via JavaScript (e.g. add new collapsible containers), you must call the refresh method on it to update the visual styling.
- -To create a collapsible block of content, create a container and add the data-role="collapsible" attribute. Using data-content-theme attribute allows you to set a theme for the content of the collapsible.
+To create a collapsible block of content, create a container and add the data-role="collapsible" attribute. Using the data-content-theme attribute allows you to set a theme for the content of the collapsible.
Directly inside this container, add any header (H1-H6) or legend element. The framework will style the header to look like a clickable button and add a "+" icon to the left to indicate it's expandable.
After the header, add any HTML markup you want to be collapsible. The framework will wrap this markup in a container that will be hidden/shown when the heading is clicked.
By default, the content will be collapsed.
-
-<div data-role="collapsible">
- <h3>I'm a header</h3>
- <p>I'm the collapsible content. By default I'm closed, but you can click the header to open me.</p>
-</div>
- This code will create a collapsible widget like this:
- -To expand the content when the page loads, add the data-collapsed="false" attribute to the wrapper.
-<div data-role="collapsible" data-collapsed="false">
-When you add the data-collapsed="false" attribute to the wrapper the collapsible will initially be expanded.
This code will create a collapsible widget like this:
- +By default collapsibles have an inset appearance. To make them full width without corner styling add the data-inset="false" attribute to the element.
-<div data-role="collapsible" data-inset="false">
-This code will create a non-inset collapsible:
- +For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-<div data-role="collapsible" data-mini="true">
-This code will create a mini collapsible widget:
- +Collapsible headings’ default icons can be overridden by using the data-collapsed-icon and data-expanded-icon attributes. In the below case, data-collapsed-icon="arrow-r" and data-expanded-icon="arrow-d".
+
The default icon of collapsible headings can be overridden by using the data-collapsed-icon and data-expanded-icon attributes. The example below uses data-collapsed-icon="arrow-r" and data-expanded-icon="arrow-d".
Collapsible headings’ default icon positioning can be overridden by using the data-iconpos attribute. In the below case, data-iconpos="right".
+
The default icon positioning of collapsible headings can be overridden by using the data-iconpos attribute. The example below uses data-iconpos="right".
Collapsible content is minimally styled - we add only a bit of margin between the bar and content, and the header adopts the default theme styles of the container it sits within.
- -To provide a stronger visual connection between the collapsible header and content, add the data-content-theme attribute to the wrapper and specify a theme swatch letter. This will apply the swatch's border and flat background color (not the gradient) to the content block and changes the corner rounding to square off the bottom of the header and round the bottom of the content block instead to visually group these elements.
-<div data-role="collapsible" data-content-theme="c">
- <h3>Header</h3>
- <p>I'm the collapsible content with a themed content block set to "c".</p>
-</div>
-Collapsible content is minimally styled - we add only a bit of margin between the bar and content, and the header adopts the default theme styles of the container within which it sits.
+ +To provide a stronger visual connection between the collapsible header and content, add the data-content-theme attribute to the wrapper and specify a theme swatch letter. This applies the border and background color of the swatch to the content block and changes the corner rounding to square off the bottom of the header and round the bottom of the content block instead to visually group these elements.
To set the theme on a collapsible header button, add the data-theme attribute to the wrapper and specify a swatch letter. Note that you can mix and match swatch letters between the header and content with these theme attributes.
<div data-role="collapsible" data-theme="a" data-content-theme="a">
- <h3>Header swatch A</h3>
- <p>I'm the collapsible content with a themed content block set to "a".</p>
-</div>
-Collapsibles can be nested inside each other if needed. In this example, we're setting the content theme to provide clearer visual connection between the levels.
- +It's possible to combine multiple collapsibles into a grouped set that acts like an accordion widget.
+It's possible to combine multiple collapsibles into a grouped set that acts like an accordion widget.
+ +The div that will serve as the container for the collapsible content.
In the example below, pre-rendered markup for a data-collapsed-icon="arrow-r" is explicitly specified, since the use of theui-icon-arrow-r class on the anchor element indicates that the value of the "collapsedIcon" widget option is to be "arrow-r".
Here is an example of a collapsible set with 5 sections. +
+ +For full width collapsibles without corner styling add the data-inset="false" attribute to the set.
+
For a more compact version that is useful in tight spaces, add the data-mini="true" attribute to the set to create a mini version.
+
The icon displayed when a collapsible is shown or hidden can be overridden by using the data-collapsed-icon and data-expanded-icon attributes. Both the collapsibleset widget and the collapsible widget accepts these attributes. When you set one or both of these attributes on the collapsibleset widget all collapsible widgets that are part of the collapsibleset display the icon specified by the chosen value. You can override the icon displayed by individual collapsible widgets by setting one or both of these attributes on the collapsible widget itself.
+
The default icon positioning for collapsible headings can be overridden by using the data-iconpos attribute. You can set the attribute either on the collapsibleset to affect all collapsibles in the set, or on an individual collapsible widget to affect only the one widget.
+
The standard data-theme attribute can be used to set the color of each collapsible in a set. To provide a clearer visual grouping of the content with the headers, add the data-content-theme attribute with a swatch letter. This adds a themed background color and border to the content block. For consistent theming, add these attributes to the parent collapsible set.
+
+
To have individual sections in a group styled differently, add data-theme and data-content-theme attributes to specific collapsibles.
+
The
In the example below, pre-rendered markup for a data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the container element indicates that the "corners" widget option is to be false. One of the child collapsibles is provided as-is, while the other is pre-rendered.
If you manipulate a collapsible set via JavaScript (e.g. by adding new collapsibles, removing old ones, or showing/hiding existing ones), you must call the refresh method on it to update the visual styling. This method will instantiate collapsibles on child elements which are marked data-role="collapsible", so there is no need to manually call .collapsible().
Occasionally, you may want to visually group a set of buttons to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the data-role="controlgroup" attribute — the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together.
Occasionally, you may want to visually group a set of buttons to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the data-role="controlgroup" attribute — the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together.
-<div data-role="controlgroup">
- <a href="#" data-role="button">Yes</a>
- <a href="#" data-role="button">No</a>
- <a href="#" data-role="button">Maybe</a>
-</div>
-This will result in the following button group:
@@ -21,10 +21,10 @@Horizontal grouped buttons:
- +If you use a controlgroup for input, button or select buttons we recommend wrapping them in a fieldset element that has a legend which acts as the combined label for the group. The label elements of each individual button in the group will be hidden for styling purposes, and are only accessible by screen readers. Using the label as a wrapper around the form element prevents the framework from hiding it, so you have to use the for attribute to associate the label with the input.
-$( ".selector" ).controlgroup( "container" );
+$( ".selector" ).dialog option provided by the page.dialog extension of the page widget allows you to style a page as a dialog, however, the special navigational handling will be removed. You may also consider implementing dialogs using popup widgets.Any page can be presented as a modal dialog by adding the data-rel="dialog" attribute to the page anchor link. When the "dialog" attribute is applied, the framework adds styles to add rounded corners, margins around the page and a dark background to make the "dialog" appear to be suspended above the page.
-<a href="foo.html" data-rel="dialog">Open dialog</a>
-You can open a dialog programmatically by calling the $.mobile.changePage method:
-
+
Transitions
By default, the dialog will open with a 'pop' transition. Like all pages, you can specify any page transition you want on the dialog by adding the data-transition attribute to the link. To make it feel more dialog-like, we recommend specifying a transition of "pop", "slidedown" or "flip".
Possible values include: fade, pop, flip, turn, flow, slidefade, slide, slideup, slidedown, none.
-
-<a href="foo.html" data-rel="dialog" data-transition="pop">Open dialog</a>
-
+
Closing dialogs
When any link is clicked within a dialog, the framework will automatically close the dialog and transition to the requested page, just as if the dialog were a normal page. Nevertheless, dialogs can also be chained, as explained below under "Chaining Dialogs". Similarly, a link that opens a popup will also leave the dialog in place.
-
+
If the dialog has a header the framework will add a close button at the left side of the header. You can change the position by adding data-close-btn="right" to the dialog container. If you don't want a close button in the header or add a custom close button, you can use data-close-btn="none".
-
+
-
+
To create a "cancel" button in a dialog, just link to the page that triggered the dialog to open and add the data-rel="back" attribute to your link. This pattern of linking to the previous page is also usable in non-JS devices as well.
For JavaScript-generated links, you can simply set the href attribute to "#" and use the data-rel="back" attribute. You can also call the dialog's close() method to programmatically close dialogs, for example: $( ".ui-dialog" ).dialog( "close" ).
@@ -59,9 +61,9 @@ $.mobile.changePage( "#myDialog", { role: "dialog" } );
Dialogs can be styled with different theme swatches, just like any page by adding data-theme attributes to the header, content, or footer containers.
-
+
By default dialogs have rounded corners. The option corners can be set to false by adding data-corners="false" to the dialog container:
-
+
Dialogs appear to be floating above an overlay layer. This overlay adopts the swatch 'a' content color by default, but the data-overlay-theme attribute can be added to the page wrapper to set the overlay to any swatch letter.
@@ -76,7 +78,7 @@ $.mobile.changePage( "#myDialog", { role: "dialog" } );
For the sake of readability, dialogs have a default width of 92.5% and a max-width of 500 pixels. There is also a 10% top margin to give dialogs larger top margin on larger screens, but collapse to a small margin on smartphones. The dialog's inner container is shifted towards the top with 15px to hide the corner styling if a dialog is used as a control sheet (see above). To override these styles, add the following CSS override rule to your stylesheet and tweak as needed:
-
+
This method is responsible for performing all jQuery Mobile enhancement. Given a set of DOM elements it will enhance their children with all the widgets available.
+The enhancement is based on each widget's initSelector property. This selector will be used to identify the elements upon which the widget will be instantiated.
You can shield elements and their children from enhancement by adding the attribute data-enhance="false" to an element. This will cause it, and all its children to be ignored by .enhanceWithin(). Unfortunately, checking elements to see whether they are children of an element that has been marked with data-enhance="false" is performance-intensive. Thus, the presence of data-enhance="false" will only be considered if the global flag $.mobile.ignoreContentEnabled is set to true.
Caveat: filterable widgets before checkboxradio widgets are enhanced can cause the checkboxradio widgets to be displayed incorrectly. If this affects you, then you must ensure that the widgets which need to be enhanced early are instantiated before the rest of the widgets. One possibility for accomplishing this is to instantiate your widgets during the page widget's pagebeforecreate event.
div with class ui-field-contain.
+ Adds class ui-field-contain to div wrappers of individual form elements which have a label. The div and the class ensure that the form is rendered responsively. At a sufficient width the label for each form element will be placed to the left of the form element, whereas on narrow displays, the label will appear above the form element.
The ui-screen-hidden to those children for which a filter callback function provided via the widget's filterCallback option returns true.
The filterable widget is a generalization of the listview widget's filter extension that was available in jQuery Mobile 1.3. It retains API compatibility with the listview filter. Its behavior is also made backwards compatible by the following deprecated features:
data-input attribute, it will generate a text input and place it before the element.filterPlaceholder option which sets the placeholder attribute on the generated text input.filterTheme option which sets the theme option on the generated text input.hidedividers option, which causes the new listview hidedividers extension to automatically hide dividers for categories wherein all items are hidden.To render the children of an element filterable, perform the following steps: +
change signal and has a value that can be accessed via the jQuery .val() plugin. This is usually a text input. The change signal by reading the value of the input after a short delay and iterating over all the children to determine whether they should be shown or hidden according to the filter callback provided.data-filter="true" to the element whose children will be filtered.data-input to the element whose children will be filtered. The value of the attribute is a string containing a jQuery selector that will return the element to be used as the source for the refresh method on the
+ Child elements may have the data-filtertext attribute set. In that case, the default filter callback will hide a given child element only if the value of the data-filtertext attribute does not contain the string provided by the user. If the data-filtertext attribute is absent, the child will be hidden if its text content does not contain the string provided by the user.
+
The normal initial state of a
You can turn on "reveal" mode by adding the attribute data-filter-reveal="true" to the element whose children will be filtered.
The example below illustrates the behavior of a
The filterCallback option allows you to set a custom callback. In the example below items are filtered by their ordinal, which can be specified using page printing conventions such as "1,2" or "4-9", or both ("1,2,4-9,12").
= searchValue[ idx ][ 0 ] &&
+ index <= searchValue[ idx ][ 1 ] ) ) {
+ return false;
+ }
+ }
+ }
+
+ return !!searchValue;
+};
+]]>The data-enhanced="true", you instruct the ui-screen-hidden to any children which must initially be hidden due to the initial value of the search input.
Note: If the element whose children are to be filtered is enhanced by another widget as well, such as for example a listview or a controlgroup then you are required to provide pre-rendered markup for the other widget as well, because the attribute data-enhanced="true" will influence the initialization behavior of the other widget as well.
In the example below, pre-rendered markup for a data-filter-reveal="true" is explicitly specified, since the presence of the ui-screen-hidden class on all the children indicates that they are initially hidden. The controlgroup widget containing the children is also pre-rendered, because the data-enhanced="true" attribute applies to the controlgroup widget as much as it does to the
If you manipulate a refresh() method on it to update the visual styling.
In browsers that support CSS position: fixed (most desktop browsers, iOS5+, Android 2.2+, BlackBerry 6, and others), toolbars that use the "fixedtoolbar" plugin will be fixed to the top or bottom of the viewport, while the page content scrolls freely in between. In browsers that don't support fixed positioning, the toolbars will remain positioned in flow, at the top or bottom of the page.
To enable this behavior on a header or footer, add the data-position="fixed" attribute to a jQuery Mobile header or footer element.
Fixed header markup example:
-
-<div data-role="header" data-position="fixed">
- <h1>Fixed Header</h1>
-</div>
- Fixed footer markup example:
-
-<div data-role="footer" data-position="fixed">
- <h1>Fixed Footer</h1>
-</div>
- Fullscreen fixed toolbars sit on top of the content at all times when they are visible, and unlike regular fixed toolbars, fullscreen toolbars do not fall back to static positioning when toggled. Instead they disappear from the screen entirely. Fullscreen toolbars are ideal for more immersive interfaces, like a photo viewer that is meant to fill the entire screen with the photo itself and no distractions.
- -To enable this option on a fixed header or footer, add the data-fullscreen attribute to the element.
-<div data-role="header" data-position="fixed" data-fullscreen="true">
- <h1>Fixed Header!</h1>
-</div>
- While all form elements are now tested to work correctly within static toolbars as of jQuery Mobile 1.1, we recommend extensive testing when using form elements within fixed toolbars or within any position: fixed elements. This can potentially trigger a number of unpredictable issues in various mobile browsers, Android 2.2/2.3 in particular (detailed in Known issues in Android 2.2/2.3, below).
Prior to version 1.1, jQuery Mobile used dynamically re-positioned toolbars for the fixed header effect because very few mobile browsers supported the position:fixed CSS property, and simulating fixed support through the use of "fake" JavaScript overflow-scrolling behavior would have reduced our browser support reach, in addition to feeling unnatural on certain platforms. This behavior was not ideal, and jQuery Mobile 1.1 took a new approach to fixed toolbars that allows much broader support. The framework now offers true fixed toolbars on many popular platforms, while gracefully degrading non-supporting platforms to static positioning.
The fixed toolbar plugin degrades gracefully in platforms that do not support CSS position:fixed properly, such as iOS4.3. If you still need to support fixed toolbars on that platform (with the show/hide behavior) included in previous releases, Filament Group has developed a polyfill that you can use.
Just include the CSS and JS files after your references to jQuery Mobile and Fixed toolbars will work similarly to jQuery Mobile 1.0 in iOS4.3, with the inclusion of the new API for the 1.1 fixedtoolbar plugin.
- -If you have any improvements to suggest, fork the gist on github and let us know!
- -An obscure issue exists in iOS5 and some Android platforms where form controls placed inside fixed-positioned containers can lose their hit area when the window is programatically scrolled (using window.scrollTo for example). This is not an issue specific to jQuery Mobile, but because of it, we recommend not programatically scrolling a document when using form controls inside jQuery Mobile fixed toolbars. This ticket from the Device Bugs project tracker explains this problem in more detail.
Android 2.2/2.3's implementation of position: fixed; can, in conjunction with seemingly unrelated styles and markup patterns, cause a number of strange issues, particularly in the case of position: absolute elements inside of position: fixed elements. While we've done our best to work around a number of these unique bugs within the scope of the library, custom styles may cause a number of issues.
position: fixed element appears anywhere on a page, most 2D CSS transforms will fail. Oddly, only translate transforms seem unaffected by this. Even more oddly, this issue is solved by setting a CSS opacity of .9 or below on the parent of the fixed element.position: fixed and overflow properties are best avoided, as both have been known to cause unpredictable issues in older versions of Android OS.position: fixed element, will fail to respond to user input when using anything other than the default keyboard. This includes Swype, XT9 or, it seems, any input method apart from the standard non-predictive keyboard.While we will continue to try to find ways to mitigate these bugs as best we can, we currently advise against implementing fixed toolbars containing complicated user styles and form elements without extensive testing in all versions of Android's native browser.
- - -Prior to jQuery Mobile 1.1, true fixed toolbar support was contingent on native browser support for the CSS property overflow-scrolling: touch, which is currently only supported in iOS5. As of version 1.1, jQuery Mobile no longer uses this CSS property at all. We've removed all internal usage of this property in the framework, but we've left it defined globally on the $.mobile object to reduce the risk that its removal will cause trouble with existing applications. This property is flagged for removal, so please update your code to no longer use it. The support test for this property, however, remains defined under $.support and we have no plans to remove that test at this time.
As of jQuery Mobile 1.4.0 the functionality of the fixedtoolbar widget has been moved to the toolbar widget.
+$.mobile.fixedToolbars.show(true);There is also an updatelayout event that can be used to trigger the toolbars to re-position. Developers who are building dynamic applications that inject content into the current page can also manually trigger this updatelayout event to ensure components on the page update in response to the new content that was just added. This event is used internally in the collapsible and listview filter plugins and is powerful because it's not toolbar-specific -- any widget can be built to listen for the updatelayout event to update the widget in response.
The flip switch is an alternative look to the checkbox or the two-option select menu. It can be toggled by a click or a swipe.
+To create a flip switch add the attribute data-role="flipswitch" to a checkbox input or to a select which has two option values.
Use the following markup to create a flipswitch based on a checkbox input:
+
onText and offText options.
+ You can also create a flipswitch based on a select element:
+
select element's option elements. The first option is used for the inactive, "off" state, and the second option is used for the active, "on" state.
+
+ You can customize the labels displayed by the option elements if the widget is based on a select.
The location of the text inside the two labels is specified manually in the
Depending on your choice of labels, you may also have to provide custom CSS to override the default width for the flipswitch:
+The div around the input. In addition to the original element, the wrapper also contains two span elements where the two labels are stored. The first span is styled as a button with the text for the active state appearing outside the button's bounding box to the left. To make the tabindex="1" attribute to the first span.
In the example below, pre-rendered markup for a data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the wrapper element indicates that the "corners" widget option is to be false.
If you manipulate a
The footer bar has the same basic structure as the header except it uses the data-role attribute value of footer.
-<div data-role="footer">
- <h4>Footer content</h4>
-</div>
-The footer toolbar will be themed with the "a" swatch by default (black in the default theme) but you can easily set the theme swatch color.
-
The page footer is very similar to the header in terms of options and configuration. The primary difference is that the footer is designed to be less structured than the header to allow more flexibility, so the framework doesn't automatically reserve slots for buttons to the left or right as it does in headers.
-Since footers do not have the same prescriptive markup conventions as headers, we recommend using layout grids or writing custom styles to achieve the design you want.
- -Any link or valid button markup added to the footer will automatically be turned into a button. To save space, buttons in toolbars are automatically set to inline styling so the button is only as wide as the text and icons it contains.
-By default, toolbars don't have any padding to accommodate nav bars and other widgets. To include padding on the bar, add a class="ui-bar" to the footer.
-<div data-role="footer" class="ui-bar">
- <a href="index.html" data-role="button" data-icon="plus">Add</a>
- <a href="index.html" data-role="button" data-icon="arrow-u">Up</a>
- <a href="index.html" data-role="button" data-icon="arrow-d">Down</a>
-</div>
-This creates this toolbar with buttons sitting in a row -
- -Note that .ui-bar should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap the toolbar's contents in an element and apply the padding to that element.
To group buttons together into a button set, wrap the links in a wrapper with data-role="controlgroup" and data-type="horizontal" attributes.
<div data-role="controlgroup" data-type="horizontal">
-
- This creates a grouped set of buttons: -
- -Form elements and other content can also be added to toolbars. Here is an example of a select menu inside a footer bar. We recommend using mini-sized form elements in toolbars by adding the data-mini="true" attribute:
-
In situations where the footer is a global navigation element, you may want it to appear fixed so it doesn't scroll out of view. It's also possible to make a fixed toolbar persistent so it appears to not move between page transitions. This can be accomplished by using the persistent footer feature included in jQuery Mobile.
-To make a footer persistent between transitions, add the data-id attribute to the footer of all relevant pages and use the same id value for each. For example, by adding data-id="myfooter" to the current page and the target page, the framework will keep the footer anchors in the same spot during the page animation. This effect will only work correctly if the header and footer toolbars are set to data-position="fixed" so they are in view during the transition.
As of jQuery Mobile 1.4.0 the functionality of the footer widget has been moved to the toolbar widget.
+To build a two-column (50/50%) layout, start with a container with a class of ui-grid-a, and add two child containers inside it classed with ui-block-a for the first column and ui-block-b for the second:
-<div class="ui-grid-a">
- <div class="ui-block-a"><strong>I'm Block A</strong> and text inside will wrap</div>
- <div class="ui-block-b"><strong>I'm Block B</strong> and text inside will wrap</div>
-</div><!-- /grid-a -->
-The above markup produces the following content layout:
As you see above, by default grid blocks have no visual styling; they simply present content side-by-side.
Grid classes can be applied to any container. In this next example, we add ui-grid-a to a fieldset, and apply the ui-block classes to the container of each of the two buttons inside to stretch them each to 50% of the screen width:
-<fieldset class="ui-grid-a">
- <div class="ui-block-a"><button type="submit" data-theme="c">Cancel</button></div>
- <div class="ui-block-b"><button type="submit" data-theme="b">Submit</button></div>
-</fieldset>
-Please note that the framework adds left and right margin to buttons in a grid. For a single button you can use a container with class ui-grid-solo and wrap the button in a div with class ui-block-a like the example below. This way the button will get the same margin.
-<div class="ui-grid-a">
- <div class="ui-block-a"><button type="button" data-theme="c">Previous</button></div>
- <div class="ui-block-b"><button type="button" data-theme="c">Next</button></div>
-</div>
-<div class="ui-grid-solo">
- <div class="ui-block-a"><button type="v" data-theme="b">More</button></div>
-</div>
-Theme classes (not data-theme attributes) from the theming system can be added to an element, including grids. On the blocks below, we're adding two classes: ui-bar to add the default bar padding and ui-bar-e to apply the background gradient and font styling for the "e" toolbar theme swatch. For illustration purposes, an inline style="height:120px" attribute is also added to each grid to set each to a standard height.
Theme classes (not data-theme attributes) from the theming system can be added to an element, including grids. On the blocks below, we're adding two classes: ui-bar to add the default bar padding and ui-bar-e to apply the background gradient and font styling for the "e" toolbar theme swatch. For illustration purposes, an inline style="height:120px" attribute is also added to each grid to set each to a standard height.
The other grid layout configuration uses class=ui-grid-b on the parent, and 3 child container elements, each with its respective ui-block-a/b/c class, to create a three-column layout (33/33/33%). Note: These blocks are also styled with theme classes so the grid layout is clearly visible.
-<div class="ui-grid-b">
- <div class="ui-block-a">Block A</div>
- <div class="ui-block-b">Block B</div>
- <div class="ui-block-c">Block C</div>
-</div><!-- /grid-b -->
-This will produce a 33/33/33% grid for our content.
- +And an example of a 3 column grid with buttons inside:
- +A four-column, 25/25/25/25% grid is created by specifying class=ui-grid-c on the parent and adding a fourth block. Note: These blocks are also styled with theme classes so the grid layout is clearly visible.
A five-column, 20/20/20/20/20% grid is created by specifying class=ui-grid-d on the parent and adding a fifth block. Note: These blocks are also styled with theme classes so the grid layout is clearly visible.
Grids are designed to wrap to multiple rows of items. For example, if you specify a 3-column grid (ui-grid-b) on a container that has nine child blocks, it will wrap to 3 rows of 3 items each. There is a CSS rule to clear the floats and start a new line when the class=ui-block-a is seen so make sure to assign block classes in a repeating sequence (a, b, c, a, b, c, etc.) that maps to the grid type:
Grids are helpful for creating layouts within a toolbar. Here's a footer with a 4 column grid.
- +iFrame source: example1.html
diff --git a/entries/header.xml b/entries/header.xml
index 4241e9c3..cca3a337 100644
--- a/entries/header.xml
+++ b/entries/header.xml
@@ -2,118 +2,10 @@
The Header bar serves as the page title, is usually the first element inside each mobile page, and typically contains a page title and up to two buttons. The 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. The In the standard header configuration, there are slots for buttons on either side of the text heading. Each button is typically an The header 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. 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 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 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 jQuery Mobile has a feature to automatically create and append "back" buttons to any header, though it is disabled by default. This is primarily useful in chromeless installed applications, such as those running in a native app webview. The framework automatically generates a "back" button on a header when the page plugin's If you use the attribute If you just want a reverse transition without actually going back in history, you should use the If you'd like to configure the back button text, you can either use the If you'd like to configure the back button role-theme, you can use: 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 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 Note that By writing some simple styles, it's easy to build message bars like this: As of jQuery Mobile 1.4.0 the functionality of the header widget has been moved to the toolbar widget. Note: Some native input types have undesirable native behavior. Note: Note: This method is no longer useful, since theme inheritance is implemented entirely in CSS as of jQuery Mobile 1.4.0. Possible values: swatch letter (a-z). Note: Header structure
- header is a toolbar 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.
-
-
-<div data-role="header">
- <h1> Page Title </h1>
-</div>
-Default header features
-
- header toolbar is themed with the "a" swatch by default (black in the default theme) but you can easily set the theme swatch color.
- Adding buttons
-
- anchor element, but can be a button element as well. To save space, buttons in toolbars are set to inline styling so the button is only as wide as the text and icons it contains. Default button positioning
-
-
-
-
-
-<div data-role="header">
- <a href="index.html" data-icon="delete">Cancel</a>
- <h1>Edit Contact</h1>
- <a href="index.html" data-icon="check">Save</a>
-</div>
-Making buttons visually stand out
-
- data-theme attribute and set the color swatch for the button to "b" to make the "Save" button pop.
-
-
-
-
-<div data-role="header">
- <a href="index.html" data-icon="delete">Cancel</a>
- <h1>Edit Contact</h1>
- <a href="index.html" data-icon="check" data-theme="b">Save</a>
-</div>
-Controlling button position with classes
- ui-btn-left or ui-btn-right to the anchor.
-
-
-
-
-<div data-role="header">
- <h1>Page Title</h1>
- <a href="index.html" data-icon="gear" class="ui-btn-right">Options</a>
-</div>
-Adding buttons to toolbars without heading
- class="ui-title" so that the bar can get the height and display correctly.
-
-
-
-
-<div data-role="header">
- <a href="index.html" data-icon="gear" class="ui-btn-right">Options</a>
- <span class="ui-title" />
-</div>
-Adding Back buttons
-
- addBackBtn option is true. This can also be set via markup if the page div has a data-add-back-btn="true" attribute. data-rel="back" on an anchor, any clicks on that anchor will mimic the back button, going back one history entry and ignoring the anchor's default href. This is particularly useful when linking back to a named page, such as a link that says "home", or when generating "back" buttons with JavaScript, such as a button to close a dialog. When using this feature in your source markup, be sure to provide a meaningful href that actually points to the URL of the referring page. This will allow the feature to work for users in C-Grade browsers.data-direction="reverse" attribute.Customizing the back button text
- data-back-btn-text="previous" attribute on your page element, or set it programmatically via the page plugin's options: $.mobile.page.prototype.options.backBtnText = "previous";Default back button style
- $.mobile.page.prototype.options.backBtnTheme = "a";
-If you're doing this programmatically, set this option inside the mobileinit event handler.Custom header configurations
- div. 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.ui-bar class to apply standard bar padding and add the ui-bar-b class to assign the bar swatch styles from your theme. (The "b" can be any swatch letter.)
-
-
-
-
-<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>
-.ui-bar should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap the toolbar's contents in an element and apply the padding to that element instead.pagecontainer widget instead.
+
Utility method for determining the directory portion of an URL. If the URL has no trailing slash, the last component of the URL is considered to be a file. This function returns the directory portion of a given URL.
The browser's location.href may contain the username/password information. getLocation() always returns location.href stripped of the username/password information if present, ensuring that your code is not vulnerable to XSS attacks.
Utility method for determining if a URL is absolute. This function returns a boolean true if the URL is absolute, false if not.
Utility method for determining if a URL is relative variant. This function returns a boolean true if the URL is relative, false if it is absolute.
This function returns a string that is an absolute version of the relative URL passed in.
This method gets the current location via getLocation() and returns the result of parsing this value via parseUrl().
Here, we have some text so that we can have
some vertical space in order to demonstrate
- the silentScroll() method.
A listview is coded as a simple unordered list containing linked list items with a data-role="listview" attribute. jQuery Mobile will apply all the necessary styles to transform the list into a mobile-friendly listview with right arrow indicator that fills the full width of the browser window. When you tap on the list item, the framework will trigger a click on the first link inside the list item, issue an Ajax request for the URL in the link, create the new page in the DOM, then kick off a page transition. View the data- attribute reference to see all the possible attributes you can add to listviews.
A listview is coded as a simple unordered list containing linked list items with a data-role="listview" attribute. jQuery Mobile will apply all the necessary styles to transform the list into a mobile-friendly listview with right arrow indicator that fills the full width of the browser window. When you tap on the list item, the framework will trigger a click on the first link inside the list item, issue an Ajax request for the URL in the link, create the new page in the DOM, then kick off a page transition. View the data- attribute reference to see all the possible attributes you can add to listviews.
Here is the HTML markup for a basic linked list.
-
-<ul data-role="listview">
- <li><a href="acura.html">Acura</a></li>
- <li><a href="audi.html">Audi</a></li>
- <li><a href="bmw.html">BMW</a></li>
-</ul>
-Style note on non-inset lists: all standard, non-inset lists have a -15px margin to negate the 15px of padding on the content area to make lists extend to the edges of the screen. If you add other widgets above or below a list, the negative margin may make these elements overlap so you'll need to add additional spacing in your custom CSS.
- -By nesting child ul or ol inside list items, you can create nested lists. When a list item with a child list is clicked, the framework will show a new page populated with the title of the parent in the header and the list of child elements. These dynamic nested lists are styled with the "b" theme swatch (blue in the default theme) to indicate that you are in a secondary level of navigation. Lists can be nested multiple levels deep and all pages and linking will be automatically handled by the framework. Note that the page of each nested listview is created when the parent page loads and for each nested page the page-events will trigger. Please also note that the title of subpages will contain the text of the first element in the parent list item including its elements. So make sure to use a single element for the list item caption and put other elements like count bubbles behind that caption as shown in the demo below.
To set the swatch color of the child listviews, set the data-theme attribute on each list inside.
Style note on non-inset lists: all standard, non-inset lists have a -1em (16px) margin to negate the 1em padding on the content area to make lists extend to the edges of the screen. If you add other widgets above or below a list, the negative margin may make these elements overlap so you'll need to add additional spacing in your custom CSS.
Lists can also be created from ordered lists (ol) which is useful when presenting items that are in a sequence such as search results or a movie queue. When the enhanced markup is applied to the listview, jQuery Mobile will try to first use CSS to add numbers to the list and, if not supported, will fall back to injecting numbers with JavaScript.
Listviews can also be used to display a non-interactive list of items, usually as an inset list. This list is built from an unordered or ordered list that don't have linked list items. The framework styles the list items as buttons like the other list types (see theming lists), but without a gradient on the background.
+Listviews can also be used to display a non-interactive list of items, usually as an inset list. This list is built from an unordered or ordered list that don't have linked list items. The framework styles static list items identically to list items containing links, but static items receive the body background color (ui-body-a) rather than the button background color (ui-btn-a).
In cases where there is more than one possible action per list item, a split button can be used to offer two independently clickable items - the list item and a small arrow icon in the far right. To make a split list item, simply add a second link inside the li and the framework will add a vertical divider line, style the link as an icon-only arrow button, and set the title attribute of the link to the text of the link for accessibility.
You can set the icon for the right split icon by specifying a data-split-icon attribute on the listview with an icon name you want. The default icon is "arrow-r" but can be configured with the splitIcon listview option. By adding a data-icon attribute to the list item, you can set individual icons for each split. The theme swatch color of the split button defaults to "b" (blue in the default theme) but can be set by specifying a swatch letter with the data-split-theme attribute at the listview level or for individual splits with the data-theme attribute at the link level.
You can set the icon for the right split icon by specifying a data-split-icon attribute on the listview with an icon name you want. The default icon is "carat-r" but can be configured with the splitIcon listview option. By adding a data-icon attribute to the list item, you can set individual icons for each split. The theme swatch color of the split button defaults to "b" (blue in the default theme) but can be set by specifying a swatch letter with the data-split-theme attribute at the listview level or for individual splits with the data-theme attribute at the link level.
List items can be turned into dividers to organize and group the list items. This is done by adding the data-role="list-divider" to any list item. These items are styled with the bar swatch "b" by default (blue in the default theme) but you can specify a theme for dividers by adding the data-divider-theme attribute to the list element (ul or ol) and specifying a theme swatch letter.
List items can be turned into dividers to organize and group the list items. This is done by adding the data-role="list-divider" to any list item. These items are styled with the bar swatch "b" by default (blue in the default theme) but you can specify a theme for dividers by adding the data-divider-theme attribute to the list element (ul or ol) and specifying a theme swatch letter.
By default, the text used to create dividers is the uppercased first letter of the item's text. Alternatively you can specify divider text by setting the autodividersSelector option on the listview programmatically. For example, to add a custom selector to the element with id="mylistview":
+
Note that if you are using formatted list items that contain a floating element (for example ui-li-aside), this element precedes its siblings regardless of the order in your HTML markup. This results in the first character of the floating element being used as divider text. Therefore it is recommended to specify the divider text in this case.
-
+
If new list items are added to the list or removed from it, the dividers are not automatically updated: you should call refresh() on the listview to redraw the autodividers.
+ Hiding dividers
+ The listview hidedividers extension provides the option hideDividers. When set to true, and you call .listview( "refresh" ) after hiding a list item by adding the class ui-screen-hidden to it, the extension will hide those dividers that are followed immediately by another divider.
+
+
Search filter
- jQuery Mobile provides a very easy way to filter a list with a simple client-side search feature. To make a list filterable, simply add the data-filter="true" attribute to the list. The framework will then append a search box above the list and add the behavior to filter out list items that don't contain the current search string as the user types. The input's placeholder text defaults to "Filter items...". To configure the placeholder text in the search input, you can either bind to the mobileinit event and set the $.mobile.listview.prototype.options.filterPlaceholder option to a string of your choosing, or use the data attribute data-filter-placeholder on your listview. By default the search box will inherit its theme from its parent. The search box theme can be configured using the data attribute data-filter-theme on your listview.
+ As of jQuery Mobile 1.4.0 this functionality has been transferred to the filterable widget, which provides a more generic solution.
+ Note: Features such as automatic text input generation and special handling of listview dividers are deprecated as of 1.4.0. The documentation for filterable describes the migration path for listviews.
+
+ Filter reveal
+
+ The filter reveal feature makes is easy to build a simple autocomplete with local data. When a filterable list has the data-filter-reveal="true" attribute, it will auto-hide all the list items when the search field is blank. The data-filter-placeholder attribute can be added to specify the placeholder text for the filter. If you need to search against a long list of values, we provide a way to create a filter with a remote data source.
-
+
+
+ Remote autocomplete with listview filter
- If you want to change the way in which list items are filtered, i.e. fuzzy search or matching from the beginning of the string, you can configure the callback used internally by defining $.mobile.listview.prototype.options.filterCallback during mobileinit or after the widget has been created with $( "#mylist" ).listview( "option", "filterCallback", yourFilterFunction). Any function defined for the callback will be provided three arguments. First, the text of the current list item, second the value being searched for, and third the list item being filtered. A truthy value will result in a hidden list item. The default callback which filters entries without the searchValue as a substring is described below:
-
+ To use the filter as an autocomplete that taps into remote data sources, you can use the filterablebeforefilter event to dynamically populate a listview as a user types a search query. This is useful when you have a very large data set like cities, zip codes, or products that can't be loaded up-front locally. Use the view source button to see the JavaScript that powers this demo.
-
-function( text, searchValue, item ) {
- return text.toString().toLowerCase().indexOf( searchValue ) === -1;
-};
-
+ If you have a small list of items, you can use the listview filter reveal option to make an autocomplete with local listview data.
+
+
- To filter list items by values other than the text, add a data-filtertext attribute to the list item. The value of this attribute will be passed as the first argument to the filterCallback function instead of the text. Alternately you can use an attribute of your choosing as defined on the list item itself.
- By default, the listview filter simply searches against the content in each list item. If you want the filter to search against different content, add the data-filtertext attribute to the item and populate it with one or many keywords and phrases that should be used to match against. Note that if this attribute is added, the contents of the list item are ignored.
- This attribute is useful for dealing with allowing for ticker symbols and full company names to be searched, or for covering common spellings and abbreviations for countries.
-
-
-<li data-filtertext="NASDAQ:AAPL Apple Inc."><a href="#">Apple</a></li>
-<li data-filtertext="USA U.S.A. United States of America"><a href="#">United States</a></li>
-
+ Cities worldwide
-
+ After you enter at least three characters the autocomplete function will show all possible matches.
Text formatting & counts
The framework includes text formatting conventions for common list patterns like header/descriptions, secondary information and counts through semantic HTML markup.
@@ -107,150 +102,164 @@ function( text, searchValue, item ) {
To add text hierarchy, use headings to increase font emphasis and use paragraphs to reduce emphasis.
Supplemental information can be added to the right of each list item by wrapping content in an element with a class of ui-li-aside
-
+
-
+
Thumbnails & icons
To add thumbnails to the left of a list item, simply add an image inside a list item as the first child element. The framework will scale the image to 80 pixels square. To use standard 16x16 pixel icons in list items, add the class of ui-li-icon to the image element.
-
+
-
+
Inset lists
- If lists are embedded in a page with other types of content, an inset list packages the list into a block that sits inside the content area with a bit of margin and rounded corners (theme controlled). By adding the data-inset="true" attribute to the list (ul or ol), applies the inset appearance.
-
-
-
- Filter reveal
-
- The filter reveal feature makes is easy to build a simple autocomplete with local data. When a filterable list has the data-filter-reveal="true" attribute, it will auto-hide all the list items when the search field is blank. The data-filter-placeholder attribute can be added to specify the placeholder text for the filter. If you need to search against a long list of values, we provide a way to create a filter with a remote data source.
-
-
-
- Remote autocomplete with listview filter
+ If lists are embedded in a page with other types of content, an inset list packages the list into a block that sits inside the content area with a bit of margin and rounded corners (theme controlled). By adding the data-inset="true" attribute to the list (ul or ol), applies the inset appearance.
- To use the listview filter as an autocomplete that taps into remote data sources, you can use the listviewbeforefilter event to dynamically populate a listview as a user types a search query. This is useful when you have a very large data set like cities, zip codes, or products that can't be loaded up-front locally. Use the view source button to see the JavaScript that powers this demo.
-
- If you have a small list of items, you can use the listview filter reveal option to make an autocomplete with local listview data.
-
-
-
-
- Cities worldwide
-
- After you enter at least three characters the autocomplete function will show all possible matches.
+
Calling the listview plugin
-
+
You can directly call the listview plugin on any selector, just like any jQuery plugin:
-
+
Updating lists
- If you add items to a listview, you'll need to call the refresh() method on it to update the styles and create any nested lists that are added. For example:
-
+ If you add items to a listview, you'll need to call the refresh() method on it to update the styles. For example:
+
Note that the refresh() method only affects new nodes appended to a list. This is done for performance reasons. Any list items already enhanced will be ignored by the refresh process. This means that if you change the contents or attributes on an already enhanced list item, these won't be reflected. If you want a list item to be updated, replace it with fresh markup before calling refresh.
-
+
If you initially want to hide a list item you can do this by adding a class of ui-screen-hidden to the li element. Using this class ensures the corner styling is applied correctly as well as border-bottom on the last visible item.
This method returns a jQuery object containing all the immediate child pages of a nested list.
-If you manipulate a listview via JavaScript (e.g. add new LI elements), you must call the refresh method on it to update the visual styling.
@@ -281,7 +284,7 @@ $( document ).on( "mobileinit", function() { + + +jQuery Mobile has a very basic navbar widget that is useful for providing up to 5 buttons with optional icons in a bar, typically within a header or footer. There is also a persistent navbar variation that works more like a tab bar that stays fixed as you navigate across pages.
-A navbar is coded as an unordered list of links wrapped in a container element that has the data-role="navbar" attribute. This is an example of a two-button navbar:
A navbar is coded as an unordered list of links wrapped in a container element that has the data-role="navbar" attribute. This is an example of a two-button navbar:
-<div data-role="navbar">
- <ul>
- <li><a href="a.html">One</a></li>
- <li><a href="b.html">Two</a></li>
- </ul>
-</div><!-- /navbar -->
-When a link in the navbar is clicked it gets the active (selected) state. The ui-btn-active class is first removed from all anchors in the navbar before it is added to the activated link. If this is a link to another page, the class will be removed again after the transition has completed.
To set an item to the active state upon initialization of the navbar, add class="ui-btn-active" to the corresponding anchor in your markup. Additionaly add a class of ui-state-persist to make the framework restore the active state each time the page is shown while it exists in the DOM. The example below shows a navbar with item "One" set to active:
-<div data-role="navbar">
- <ul>
- <li><a href="a.html" class="ui-btn-active ui-state-persist">One</a></li>
- <li><a href="b.html">Two</a></li>
- </ul>
-</div><!-- /navbar -->
-Note that this on applies to navbars that are inside a page. If you use a true persistent toolbar that lives outside the page and want to set current item to the active state, you have to add a script that adds the class="ui-btn-active" class.
The navbar items are set to divide the space evenly so in this case, each button is 1/2 the width of the browser window:
@@ -38,74 +40,74 @@Adding a fourth more item will automatically make each button 1/4 the width of the browser window:
- +The navbar maxes out with 5 items, each 1/5 the width of the browser window:
- +If more than 5 items are added, the navbar will simply wrap to multiple lines:
- +Navbars with 1 item will simply render as 100%.
- +If you want to add a navbar to the top of the page, you can still have a page title and buttons. Just add the navbar container inside the header block, right after the title and buttons in the source order.
- +If you want to add a navbar to the bottom of the page so it acts more like a tab bar, simply wrap the navbar in a container with a data-role="footer"
-<div data-role="footer">
- <div data-role="navbar">
- <ul>
- <li><a href="#">One</a></li>
- <li><a href="#">Two</a></li>
- <li><a href="#">Three</a></li>
- </ul>
- </div><!-- /navbar -->
-</div><!-- /footer -->
-Icons can be added to navbar items by adding the data-icon attribute specifying a standard mobile icon to each anchor. By default, icons are added above the text (data-iconpos="top"). The following examples add icons to a navbar in a footer.
Icons can be added to navbar items by adding the data-icon attribute specifying a standard mobile icon to each anchor. By default, icons are added above the text (data-iconpos="top"). The following examples add icons to a navbar in a footer.
The icon position is set on the navbar container instead of for individual links within for visual consistency. For example, to place the icons below the labels, add the data-iconpos="bottom" attribute to the navbar container.
The icon position is set on the navbar container instead of for individual links within for visual consistency. For example, to place the icons below the labels, add the data-iconpos="bottom" attribute to the navbar container.
-<div data-role="navbar" data-iconpos="bottom">
-This will result in a bottom icon alignment:
- +The icon position can be set to data-iconpos="left":
Or the icon position can be set to data-iconpos="right":
You can add any of the popular icon libraries like Glyphish to achieve the iOS style tab that has large icons stacked on top of text labels. All that is required is a bit of custom styles to link to the icons and position them in the navbar. Here is an example using Glyphish icons and custom styles (view page source for styles) in our navbar:
@@ -113,7 +115,7 @@Icons by Joseph Wain / glyphish.com. Licensed under the Creative Commons Attribution 3.0 United States License.
Navbars inherit the theme swatch from their parent container, just like buttons. If a navbar is placed in the header or footer toolbar, it will inherit the default toolbar swatch "a" for bars unless you set this in the markup.
Here are a few examples of navbars in various container swatches that automatically inherit their parent's swatch letter. Note that in these examples, instead of using a data-theme attribute, we're manually adding the swatch classes to apply the body swatch (ui-body-a) and the class to add the standard body padding (ui-body), but the inheritance works the same way:
+
The page loading widget handles the task of displaying the loading dialog when jQuery Mobile pulls in content via Ajax. The page loading dialog was previously configured globally with three settings $.mobile.loadingMessage, $.mobile.loadingMessageTextVisible, and $.mobile.loadingMessageTheme which are now deprecated. In addition to the methods for showing and hiding, $.mobile.showPageLoadingMsg and $.mobile.hidePageLoadingMsg are also deprecated.
The page loading widget handles the task of displaying the loading dialog when jQuery Mobile pulls in content via Ajax. It can also be displayed manually for custom loading actions using the $.mobile.loading helper method (See the global method docs).
The page loading widget handles the task of displaying the loading dialog when jQuery Mobile pulls in content via AJAX. It can also be displayed manually for custom loading actions using the $.mobile.loading helper method (See the global method docs).
To configure the loading dialog globally the following settings can be defined on its prototype during the mobileinit event.
-
- $( document ).on( "mobileinit", function() {
- $.mobile.loader.prototype.options.text = "loading";
- $.mobile.loader.prototype.options.textVisible = false;
- $.mobile.loader.prototype.options.theme = "a";
- $.mobile.loader.prototype.options.html = "";
- });
-
-
+These settings will be overridden by the deprecated settings to preserve backward compatibility. Once the deprecated settings are removed these defaults will only be superseded by the method params object described in the global method docs under $.mobile.loading.
These defaults will only be superseded by the method params object described in the global method docs under $.mobile.loading.
-
- $.mobile.loading( "show", {
- text: "foo",
- textVisible: true,
- theme: "z",
- html: ""
- });
-
-
- Deprecated in 1.2 - use $.mobile.loading( "hide" ) instead, see examples above
- //hide the page loader
- $.mobile.hidePageLoadingMsg();
- $.mobile.loader prototype options as described in the widget docs or can be controlled via a params object.
Deprecated in 1.2 - use $.mobile.loading( "show" ) instead, see examples above
- //cue the page loader
- $.mobile.showPageLoadingMsg();
-
- //use theme swatch "b", a custom message, and no spinner
- $.mobile.showPageLoadingMsg( "b", "This is only a test", true );
- The page widget is responsible for managing a single item in jQuery Mobile's page-based architecture. It is designed to support either single page widgets within a HTML document, or multiple local internal linked page widgets within a HTML document.
-The goal of this model is to allow developers to create websites using best practices — where ordinary links will "just work" without any special configuration — while creating a rich, native-like experience that can't be achieved with standard HTTP requests.
+The goal of this model is to allow developers to create websites using best practices — where ordinary links will "just work" without any special configuration — while creating a rich, native-like experience that can't be achieved with standard HTTP requests.
+ +The page widget will auto-enhance its content upon creation. This means that it will instantiate widgets on its child elements by invoking .enhanceWithin() on itself.
The dialog which you can set to true to obtain a page styled like a dialog, such as in the example below:
+
Caveat: Documents containing multiple pages cause Internet Explorer 7 to exhibit incorrect behavior when its "Back" button is pressed. In particular, if the user navigates between several of the pages internal to the document that has been loaded and then clicks the "Back" button to return to the start page, there will be occasions when clicking the "Back" button does not cause a return to the previous page. However, clicking the "Back" button enough times will eventually return the user through the performed navigation sequence back to the start page.
-Thus, if Internet Explorer 7 represents a significant proportion of the targeted user base, we recommended that pages be organized as individual HTML documents containing single page widgets, rather than as a single HTML document containing multiple internal pages.
Pages have both data-external-page="true" and data-dom-cache="false" when you call bindRemove(), otherwise the method will do nothing.
Returns the selector used to filter elements which are not to be enhanced.
+Removes the background swatch from the page widget's container (usually the body).
+Sets a new background swatch for the page widget's container (usually the body).
+jQuery Mobile allows you to replace the browser's standard HTTP navigation with AJAX-based navigation. It overrides the browser's default link handling behavior. It intercepts clicks on anchors containing links to other documents and upon each such click it checks whether the document can be retrieved via AJAX. A link has to meet the following criteria in order for the document to which it links to be retrieved via AJAX: +
$.mobile.linkBindingEnabled must be true.data-rel="back"data-rel="externaldata-ajax="false"target attribute must not be present$.mobile.ajaxEnabled must be true.If these criteria are met jQuery Mobile retrieves the document via AJAX. It is important to realize that, while the document is retrieved in its entirety, only the first jQuery Mobile page is displayed. The header and the rest of the body are discarded. Thus, it is not possible to retrieve a multi-page document via AJAX, nor is it possible to execute scripts located in the header.
+ +After AJAX retrieval, jQuery Mobile displays the page via a transition. The transition can be specified on the link that opens the page using the data-transition attribute. If no transition is specified, then $.mobile.defaultPageTransition is used or, if the incoming page is a dialog, then $.mobile.defaultDialogTransition is used. Note: The dialog widget is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0.
If the browser supports the replaceState API the location bar is updated such that it displays the URL of the document that was retrieved via AJAX. This latter step has the following implication for site/application design: Since the user can copy the URL of a page other than the start page, the application must be designed such that it can start from any of its pages. The best way to achieve this is to include jQuery Mobile and your application code in the header for all the pages of the site/application, and ensure initial state consistency during the pagecreate event.
Callbacks bound to this event can call preventDefault() on the event to indicate that they are handling the load request. Callbacks that do this MUST make sure they call resolve() or reject() on the deferred object reference contained in the object passed to the callback via its ui parameter.
preventDefault() on the event MUST call resolve() or reject() on this object so that change() requests resume processing. Deferred object observers expect the deferred object to be resolved like this:
+or rejected like this:
+change() call.change() request fails to load the page.change() call that triggered the event.change() call.pagehide event, this event is not triggered on the "fromPage" but the Note that this event will not be dispatched during the transition of the first page at application startup since there is no previously active page.
+You can access the nextPage properties via the second argument of a bound callback function. For example:
For these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes. This can be done in the mobileinit handler, as described on the global config page.
$.ajax() success callback.$.ajax() error callback. It may also be null.By default, after dispatching this event, the framework will display a page failed message and call reject() on the deferred object contained within the event's ui parameter. Callbacks can prevent this default behavior from executing by calling preventDefault() on the event.
preventDefault() on the event, MUST call resolve() or reject() on this object so that change() requests resume processing. Deferred object observers expect the deferred object to be resolved like this:
+or rejected like this:
+$.ajax() error callback.null, are "timeout", "error", "abort", and "parsererror". This is what gets passed as the 2nd argument to the framework's $.ajax() error callback.null. This is what gets passed as the 3rd argument to the framework's $.ajax() error callback.pageshow event, this event is not triggered on the "toPage" but the You can access the prevPage properties via the second argument of a bound callback function. For example:
For these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes. This can be done in the mobileinit handler, as described on the global config page.
change() ignores requests to change to the current active page. Setting this option to true allows the request to execute. Developers should note that some of the page transitions assume that the fromPage and toPage of a change() request are different, so they may not animate as expected. Developers are responsible for either providing a proper transition, or turning it off for this specific case.
+ | true | The |
| false | The |
change() completion. If not specified, the value of the data-url attribute of the page element is used.reload instead.
+ Whether to force a reload of the page even when it is already in the DOM. Used only when the 'url' argument is a URL.
+true you can simulate returning to a previous page, even when the actual navigation sequence is in a forward direction.undefined which means rely on the value of the @data-role attribute defined on the element.undefined, the value of $.mobile.defaultPageTransition (currently "fade") will be used for pages, and $.mobile.defaultDialogTransition (currently "pop") will be used for dialogs.
+ Default value: undefined
reload instead.
+ Whether to force a reload of the page even when it is already in the DOM. Used only when the 'url' argument is a URL.
+undefined which means rely on the value of the @data-role attribute defined on the element.Callbacks for this event will receive a data object as their 2nd arg. This data object has the following properties on it:
-nextPage (object)
- Note that this event will not be dispatched during the transition of the first page at application startup since there is no previously active page.
-You can access the prevPage or nextPage properties via the second argument of a bound callback function. For example:
-$( "div" ).on( "pageshow", function( event, ui ) {
- alert( "This page was just hidden: " + ui.prevPage );
-});
-
-$( "div" ).on( "pagehide", function( event, ui ) {
- alert( "This page was just shown: " + ui.nextPage );
-});
-Also, for these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes. This can be done in the mobileinit handler, as described on the global config page.
The replacement for
pagecreate. Simply replace pageinit in the above example.Callbacks bound to this event will be passed a data object as its 2nd arg. This object contains the following information:
-url (string)
- $.mobile.loadPage() by the caller.absUrl (string)
- dataUrl (string)
- options (object)
- $.mobile.loadPage().xhr (object)
- $.ajax() success callback.textStatus (null or string)
- $.ajax() error callback.The replacement for
By default, after dispatching this event, the framework will display a page failed message and call reject() on the deferred object contained within the event's data object. Callbacks can prevent this default behavior from executing by calling preventDefault() on the event.
The data object, passed as the 2nd arg to the callback function contains the following properties:
-url (string)
- $.mobile.loadPage() by the caller.absUrl (string)
- dataUrl (string)
- deferred (object)
- preventDefault() on the event, *MUST* call resolve() or reject() on this object so that changePage() requests resume processing. Deferred object observers expect the deferred object to be resolved like this:
-
-$( document ).on( "pageloadfailed", function( event, data ) {
-
- // Let the framework know we're going to handle things.
-
- event.preventDefault();
-
- // ... attempt to load some other page ...
- // at some point, either in this callback, or through
- // some other async means, call resolve, passing in
- // the following args, plus a jQuery collection object
- // containing the DOM element for the page.
-
- data.deferred.resolve( data.absUrl, data.options, page );
-
-});
-or rejected like this:
-
-$( document ).on( "pageloadfailed", function( event, data ) {
-
- // Let the framework know we're going to handle things.
-
- event.preventDefault();
-
- // ... attempt to load some other page ...
- // at some point, if the load fails, either in this
- // callback, or through some other async means, call
- // reject like this:
-
- data.deferred.reject( data.absUrl, data.options );
-
-});
-options (object)
- $.mobile.loadPage().xhr (object)
- $.ajax() error callback.textStatus (null or string)
- $.ajax() error callback.errorThrown (null, string, object)
- $.ajax() error callback.The replacement for
Callbacks for this event will receive a data object as their 2nd arg. This data object has the following properties on it:
-prevPage (object)
- You can access the prevPage or nextPage properties via the second argument of a bound callback function. For example:
-$( "div" ).on( "pageshow", function( event, ui ) {
- alert( "This page was just hidden: " + ui.prevPage );
-});
-
-$( "div" ).on( "pagehide", function( event, ui ) {
- alert( "This page was just shown: " + ui.nextPage );
-});
-Also, for these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes. This can be done in the mobileinit handler, as described on the global config page.
The replacement for
Panels are designed to be as flexible as possible to make it easy to create menus, collapsible columns, drawers, inspectors panes and more. +
Panels are designed to be as flexible as possible to make it easy to create menus, collapsible columns, drawers, inspectors panes and more.
A panel must be a sibling to the header, content and footer elements inside a jQuery Mobile page. You can add the panel markup either before or after these elements, but not in between. A panel cannot be placed outside a page, but this constraint will be removed in a future version.
+ +A panel must be a sibling to the header, content, and footer elements inside a jQuery Mobile page. You can add the panel markup either before or after these elements, but not in between.
Here is an example of the panel before the header, content and footer in the source order:
-
-<div data-role="page">
+
Alternately, it's possible to add the panel markup after the header, content and footer in the source order, just before the end of the page container. Where in the source order you place the panel markup will depend on how you want to page content to read for people experiencing the page in a C-grade device (HTML only) or for a screen reader.
If a page contains a panel the framework wraps the header, content and footer sections in a div. When opening a panel with display mode "reveal" or "push" the transition is applied to this wrapper. An exception is fixed headers and footers. Those are not included in the wrapper, but will transition in sync with it. Be aware of the fact that all your visible page content should live inside those page sections.
CSS Multi-column Layout
-
+
To avoid blinks when opening a panel, we force hardware acceleration on WebKit browsers. The CSS that is used to do this can cause issues with buttons and form elements on the page if their container has a CSS multi-column layout (column-count). To resolve this you have to set the following rule for the element or its container:
-
+
Panel markup conventions
-
+
A panel consists of a container with a data-role="panel" attribute and a unique ID. This ID will be referenced by the link or button to open and close the panel. The most basic panel markup looks like this:
-
-<div data-role="panel" id="mypanel">
- <!-- panel content goes here -->
-</div>
-
+
- The position of the panel on the screen is set by the data-position attribute. The defaults to left, meaning it will appear from the left edge of the screen. Specify data-position="right" for it to appear from the right edge instead.
+ The position of the panel on the screen is set by the data-position attribute. The position defaults to left, meaning it will appear from the left edge of the screen. Specify data-position="right" for it to appear from the right edge instead.
The display mode of the panel is set by the data-display attribute. The defaults to reveal, meaning the panel will sit under the page and reveal as the page slides away. Specify data-display="overlay" for the panel to appear on top of the page contents. A third mode, data-display="push" animates both the panel and page at the same time.
-
+
Here is an example of a panel with a custom position and display option set:
-
-<div data-role="panel" id="mypanel" data-position="right" data-display="push">
- <!-- panel content goes here -->
-</div>
-
+
Dynamic content
-
+
When you dynamically add content to a panel or make hidden content visible while the panel is open, you have to trigger the updatelayout event on the panel.
-
+
The framework will check the new height of the panel contents and, in case this exceeds the screen height, set the page min-height to this height and unfix panels with data-position-fixed="true". See also Panel positioning.
Opening a panel
-
- A panel's visibility is toggled by a link somewhere on the page or by calling the panel's open method directly. The defaults place the panel on the left and it will be revealed. Open a panel programmatically like this:
-$( "#idofpanel" ).panel( "open" , optionsHash );
+ A panel's visibility is toggled by a link somewhere on the page or by calling the panel's open method directly. The defaults place the panel on the left in "reveal" mode. Open a panel programmatically like this:
+
- To control a panel from a link, point the href to references the ID of the panel you want to toggle (mypanel in the example above). This instructs the framework to bind the link to the panel. This link will toggle the visibility of the panel so tapping it will open the panel, and tapping it again will close it.
-
-
-<a href="#mypanel">Open panel</a>
-
+
+ To control a panel from a link, point the href to the ID of the panel you want to toggle (mypanel in the example below). This instructs the framework to bind the link to the panel. This link will toggle the visibility of the panel so tapping it will open the panel, and tapping it again will close it.
+
+
When using markup to control panels, you can only have a single panel open at once. Clicking a link to open a panel while one is already open will auto-close the first. This is done to keep the markup-only configuration simple.
Closing a panel
-
- Clicking the link that opened the panel, swiping left or right, or tapping the Esc key will close the panel. To turn off the swipt o close behavior, add the data-swipe-close="false" attribute to the panel.
- By default, panels can also be closed clicking outside the panel onto the page contents. To prevent this behavior, add the data-dismissible="false" attribute to the panel. It's possible to have the panel and page sit side-by-side at wider screen widths and prevent the click-out-to-close behavior only above a certain screen width by applying a media query. See the responsive section below for details.
+ Clicking the link that opened the panel, swiping left or right, or tapping the Esc key will close the panel. To turn off the swipe-to-close behavior, add the data-swipe-close="false" attribute to the panel.
+
+ By default, panels can also be closed by clicking outside the panel onto the page contents. To prevent this behavior, add the data-dismissible="false" attribute to the panel. It's possible to have the panel and page sit side-by-side at wider screen widths and prevent the click-out-to-close behavior only above a certain screen width by applying a media query. See the responsive section below for details.
A panel can also be closed by calling the panel's close method directly.
-$( "#idofpanel" ).panel( "close" );
+
- It's common to also add a close button inside the panel. To add the link that will close the panel, add the data-rel="close" attribute to tell the framework to close that panel when clicked. It's important to ensure that this link also makes sense if JavaScript isn't available, so we recommend that the href points to the ID of the page where the user should jump to when closing. For example, if the button to open the panel is in the header bar that has and ID of my-header, the close link in the panel should be:
+ It's common to also add a close button inside the panel. To add the link that will close the panel, add the data-rel="close" attribute to tell the framework to close that panel when clicked. It's important to ensure that this link also makes sense if JavaScript isn't available, so we recommend that the href points to the ID of the page to which the user should jump when closing. For example, if the button to open the panel is in the header bar that has and ID of my-header, the close link in the panel should be:
-
-<a href="#my-header" data-rel="close">Close panel</a>
-
+
Panel animations
- Panels will animate if the browser supports 3D transforms, the same criteria for CSS animation support we use for page transitions. Panel animations use translateX CSS transforms to ensure they are hardware accelerated and smooth.
+ Panels will animate if the browser supports 3D transforms. The presence of such support is established by the same criteria for CSS animation support we use for page transitions. Panel animations use translateX CSS transforms to ensure they are hardware accelerated and smooth.
The framework has a feature test to detect if the required CSS properties are supported and will fall back to a simple hide/show if not available. After thorough testing, we decided to not animate panels on less capable platforms because the choppier animations weren't a better experience than a simple hide/show.
The animate option allows you to turn off panel animations for all devices. To turn off animations via markup, add the data-animate="false" attribute to the panel container.
-
- The use of hardware acceleration is triggered during initialization of the page to prevent blinks when opening a panel. Because this increases memory use you have to be aware of performance issues if you use long lists or scripts to dynamically inject content on a page with an animated panel.
+
+ The use of hardware acceleration is triggered during initialization of the page to prevent blinks when opening a panel. Because this increases memory use you have to be aware of performance issues if you use long lists or scripts to dynamically inject content on a page with an animated panel.
Panel positioning
- The panel will be displayed with the position:absolute CSS property, meaning it will scroll with the page. When a panel is a opened the framework checks to see if the bottom of the panel contents is in view and, if not, scrolls to the top of the page.
+ The panel will be displayed with the position:absolute CSS property, meaning it will scroll with the page. When a panel is opened the framework checks to see if the bottom of the panel contents is in view and, if not, scrolls to the top of the page.
You can set a panel to position:fixed, so its contents will appear no matter how far down the page you're scrolled, by adding the data-position-fixed="true" attribute to the panel. The framework also checks to see if the panel contents will fit within the viewport before applying the fixed positioning because this property would prevent the panel contents from scrolling and using overflow is not well supported enough to use at this time. If the panel contents are too long to fit within the viewport, the framework will simply display the panel without fixed positioning.
In general, we recommend that you place the buttons that open the panel at the very top of the screen which is the most common UI pattern for panels. This will avoid the need to scroll and also makes the transitions a bit smoother.
-
- Note that there are issues with fixed positioning within Android WebView applications (not the browser) that can cause layout issues, especially when hardware acceleration isn't enabled. We recommend not to use the fixed position panel option if deploying to an Android app. Also, if have a fixed on a page with fixed toolbars, the toolbars might not transition together with the page content.
+
+ Note that there are issues with fixed positioning within Android WebView applications (not the browser) that can cause layout issues, especially when hardware acceleration isn't enabled. We recommend not to use the fixed position panel option if deploying to an Android app. Also, if you have a fixed panel on a page with fixed toolbars, the toolbars might not transition together with the page content.
Styling panels
- By default, panels have very simple styles to let you customize them as needed. Panels are essentially just simple blocks with no margins that sit on either side of the page content. The framework wraps the panel content in a div with class ui-pannel-inner which has a padding of 15 pixels. If needed you can override this with custom CSS or use option classes.panelInner to set a different class name for the div
-
+ By default, panels have very simple styles to let you customize them as needed. Panels are essentially just simple blocks with no margins that sit on either side of the page content. The framework wraps the panel content in a div with class ui-pannel-inner which has a padding of 1em. If needed you can override this with custom CSS or use option classes.panelInner to set a different class name for the div.
+
Panels have a fixed width of 17em (272 pixels) which is narrow enough to still show some of the page contents when open to make clicking out to close easy, and still looks good on wider tablet or desktop screens. The styles to set widths on panels are fairly complex but these can be overridden with CSS as needed.
-
- Note that adding padding, borders, or margins directly to the panel container will alter the overall dimensions and could cause the positioning and animation to be affected. To avoid this, apply styles to the panel content wrapper (.ui-pannel-inner).
- Other than the theme background, width and 100% height styles, panels have very little styling on their own. The default theme for panels is "c". You can set a different theme for the panel by adding a data-theme to the panel container, or set data-theme="none" and add your own classes to style it as needed.
-
+ Note that adding padding, borders, or margins directly to the panel container will alter its overall dimensions and could cause the positioning and animation to be affected. To avoid this, apply styles to the panel content wrapper (.ui-pannel-inner).
+
+ Other than the theme background, width and 100% height styles, panels have very little styling of their own. The default theme for panels is "a". You can set a different theme for the panel by adding a data-theme to the panel container, or set data-theme="none" and add your own classes to style it as needed.
+
The framework applies the theme that is used for the page to the content wrapper. Before opening a panel that has display mode reveal or push, the page theme will be set to the same theme that is used for the panel. This is done to mask that most mobile browsers haven't finished painting the panel background when the animation to open it has already started. If you use a background image for a page, you have to set it for the ui-body-* class of the theme that you use for the page so it will be used as background of the content wrapper.
-
+
Making the panel responsive
- When the push or reveal display is used, a panel pushes the page aside when it opens. Since some of the page is pushed offscreen, the panel is modal and must be closed to interact with the page content again. On larger screens, you may want to have the panel work more like a collapsible column that can be opened and used alongside the page to take better use of the screen real estate.
+ When the push or reveal display is used, a panel pushes the page aside when it opens. Since some of the page is pushed offscreen, the panel is modal and must be closed to interact with the page content again. On larger screens, you may want to have the panel work more like a collapsible column that can be opened and used alongside the page to make better use of screen real estate.
To make the page work alongside the open panel, it needs to re-flow to a narrower width so it will fit next to the panel. This can be done purely with CSS by adding a left or right margin equal to the panel width (17em) to the page contents to force a re-flow. Second, the invisible layer placed over the page for the click out to dismiss behavior is hidden with CSS so you can click on the page and not close the menu.
Here is an example of these rules wrapped in a media query to only apply this behavior above 35em (560px):
-
-
+
+
+
Applying a preset breakpoint
-
- Included in the widget styles is a breakpoint preset for this behavior that kicks in at 55em (880px). This breakpoint is not applied by default to make it easier for you to write custom breakpoints that work best for your content and design. To apply the breakpoint preset, add the ui-responsive-panel class to the page wrapper (not the panel).
-
+
+ Included in the widget styles is a breakpoint preset for this behavior that kicks in at 55em (880px). This breakpoint is not applied by default to make it easier for you to write custom breakpoints that work best for your content and design. To apply the breakpoint preset, add the ui-responsive-panel class to the page (not the panel).
To create a popup, add the data-role="popup" attribute to a div with the popup contents. Then create a link with the href set to the id of the popup div, and add the attribute data-rel="popup" to tell the framework to open the popup when the link is tapped. This is a similar markup pattern to the dialog widget. A popup div has to be nested inside the same page as the link.
-<a href="#popupBasic" data-rel="popup">Open Popup</a>
+
This will result in the following popup:
The popup consists of two elements: the screen, which is a transparent or translucent element that covers the entire document, and the container, which is the popup itself. If your original element had an id attribute, the screen and the container will each receive an id attribute based on it. The screen's id will be suffixed with "-screen", and the container's id will be suffixed with "-popup" (in the above example, id="popupBasic-screen" and id="popupBasic-popup", respectively).
-
+
The framework adds a small amount of margin to text elements, but it's really just a container with rounded corners and a shadow which serves as a blank slate for your designs (even these features can be disabled via options).
This simple styling makes it easy to add in widgets to create a variety of different interactions. Here are a few real-world examples that combine the various settings and styles you can achieve out of the box with popups:
@@ -26,16 +27,16 @@
Scaling images: Lightbox examples
-
+
The framework CSS contains rules that make images that are immediate children of the popup scale to fit the screen. Because of the absolute positioning of the popup container and screen, the height is not adjusted to screen height on all browsers. You can prevent vertical scrolling with a simple script that sets the max-height of the image.
-
- In the two examples below the divs with data-role="popup" have a class of photopopup.
+
+
In the two examples below the divs with data-role="popup" have a class of photopopup.
-
- The handler is bound to the popupbeforeposition event, which ensures the image is not only scaled before it is shown but also when the window is resized (e.g. orientation change). In this code example the height is reduced by 60 to take a top and bottom tolerance of 30 pixels into account.
-
+ The handler is bound to the popupbeforeposition event, which ensures the image is not only scaled before it is shown but also when the window is resized (e.g. orientation change). In this code example the height is reduced by 60 to take a top and bottom tolerance of 30 pixels into account.
+
+
+
Working with iframes in popups
-
+
You may need to embed an iframe into a popup to use a 3rd party widget. Here, we'll walk through a few real-world examples of working with iframes: videos and maps.
Video example
-
+
Here is an example of a 3rd party video player embedded in a popup:
-
- The markup is an iframe inside a popup container. The popup will have a 15 pixels padding because of class ui-content and a one pixel border because the framework will add class ui-body-d to the popup.
-
-
-<div data-role="popup" id="popupVideo" data-overlay-theme="a" data-theme="d" data-tolerance="15,15" class="ui-content">
- <iframe src="http://player.vimeo.com/video/41135183" width="497" height="298" seamless></iframe>
-
-</div>
-
+ The markup is an iframe inside a popup container. The popup will have a 15 pixels padding because of class ui-content and a one pixel border because the framework will add class ui-body-a to the popup.
+
+
When using an iframe inside a popup it is important to initially set the width and height attributes to 0. This prevents the page to breaking on platforms like Android 2.3. Note that you have to set the attributes, because setting the width and height with CSS is not sufficient. You can leave the actual width and height in the markup for browsers that have JavaScript disabled and use attr() to set the zero values upon the pageinit event.
Next, bind to the popupbeforeposition event to set the desired size of the iframe when the popup is shown or when the window is resized (e.g. orientation change). For the iframe examples on this page a custom function scale() is used to scale down the iframe to fit smaller screens. Expand the section below to view the code of this function.
-
+
scale()
The window width and height are decreased by 30 to take the tolerance of 15 pixels at each side into account.
-
+};
+]]>
Note: This function is not part of the framework. Copy the code into your script to use it.
-
-
+
+
When the popup is closed the width and height should be set back to 0. You can do this by binding to the popupafterclose event.
-
+
This is the complete script and the link to open the video popup:
-
-
+
+
+
Note that the video will still be playing in the iframe when the popup is closed. If available you can use the 3rd party API to stop the video on the popupafterclose event. Another way is to create the iframe when the popup is opened and destroy it when the popup is closed, but this would drop support for browsers that have JavaScript disabled.
-
+
Map example
In the second example, an iframe is used to display Google Maps API. Using an iframe prevents issues with the controls of the map.
-
+
This is the markup of the popup including a right close button:
-
-<div data-role="popup" id="popupMap" data-overlay-theme="a" data-theme="a" data-corners="false" data-tolerance="15,15">
+
Expand the section below to view the source of the iframe.
-
+
map.html
-
-<!DOCTYPE html>
-<html>
-<head>
- <meta charset="utf-8">
- <title>Map</title>
- <script>
- function initialize() {
- var myLatlng = new google.maps.LatLng( 51.520838, -0.140261 );
- var myOptions = {
- zoom: 15,
- center: myLatlng,
- mapTypeId: google.maps.MapTypeId.ROADMAP
- }
- var map = new google.maps.Map( document.getElementById( "map_canvas" ), myOptions );
- }
- </script>
- <script src="http://maps.google.com/maps/api/js?sensor=false"></script>
- <style>
- html {
- height: 100%;
- overflow: hidden;
- }
- body {
- margin: 0;
- padding: 0;
- height: 100%;
- }
- #map_canvas {
- height: 100%;
- }
- </style>
-</head>
-<body onload="initialize()">
-
- <div id="map_canvas"></div>
-
-</body>
-</html>
-
+
+
+
+
+ Map
+
+
+
+
+
+
+
+
+]]>
-
- Setting the size of the iframe is done exactly the same as for the video example, with one exception. You should also set the width and height of the div that contains the map to prevent the page to break on platforms like Android 2.3. In this example the ID of this div is #map_canvas.
-
+
+ Setting the size of the iframe is done exactly the same as for the video example, with one exception. You should also set the width and height of the div that contains the map to prevent the page from breaking on platforms like Android 2.3. In this example the ID of this div is #map_canvas.
+
This is the complete script and the link to open the map popup:
-
-
-$( document ).on( "pageinit", function() {
- $( "#popupMap iframe" )
- .attr( "width", 0 )
- .attr( "height", 0 );
-
- $( "#popupMap iframe" ).contents().find( "#map_canvas" )
- .css( { "width" : 0, "height" : 0 } );
-
- $( "#popupMap" ).on({
- popupbeforeposition: function() {
- var size = scale( 480, 320, 0, 1 ),
- w = size.width,
- h = size.height;
- $( "#popupMap iframe" )
- .attr( "width", w )
- .attr( "height", h );
-
- $( "#popupMap iframe" ).contents().find( "#map_canvas" )
- .css( { "width": w, "height" : h } );
- },
- popupafterclose: function() {
- $( "#popupMap iframe" )
- .attr( "width", 0 )
- .attr( "height", 0 );
-
- $( "#popupMap iframe" ).contents().find( "#map_canvas" )
- .css( { "width": 0, "height" : 0 } );
- }
- });
-});
-
-
- Overlay panels
-
- Taking customization further, here is an example of a popup that has been customized to look like a vertical panel with three mini buttons:
-
-
- Here is the HTML markup for the button and panel:
-
-<a href="#popupPanel" data-rel="popup" data-transition="slide" data-position-to="window" data-role="button">Open panel</a>
-
-<div data-role="popup" id="popupPanel" data-corners="false" data-theme="none" data-shadow="false" data-tolerance="0,0">
-
- <button data-theme="a" data-icon="back" data-mini="true">Back</button>
- <button data-theme="a" data-icon="grid" data-mini="true">Menu</button>
- <button data-theme="a" data-icon="search" data-mini="true">Search</button>
-
-</div>
-
-
- To style the panel, and attach it to the right edge, the following CSS is used. Note that #popupPanel-popup is the ID of the container div generated by the framework.
-
-#popupPanel-popup {
- right: 0 !important;
- left: auto !important;
-}
-#popupPanel {
- width: 200px;
- border: 1px solid #000;
- border-right: none;
- background: rgba(0,0,0,.5);
- margin: -1px 0;
-}
-#popupPanel .ui-btn {
- margin: 2em 15px;
-}
-
-
- Because the popup container is positioned absolute, you can't make the panel full height with height:100%;. This small script sets the height of the popup to the actual screen height.
-
-$( "#popupPanel" ).on({
- popupbeforeposition: function() {
- var h = $( window ).height();
-
- $( "#popupPanel" ).css( "height", h );
- }
+
Calling the popup plugin
This plugin will autoinitialize on any page that contains a div with the attribute data-role="popup". However, if needed you can directly call the popup plugin on any selector, just like any jQuery plugin and programmatically work with the popup options, methods, and events API:
-
-
+
+
Opening popups
-
+
Using the markup-based configuration, when a link with the data-rel="popup" is tapped, the corresponding popup container with the id referenced in the href of the link will be shown. To open a popup programmatically, call popup with the open method on the popup container:
-
-
+
+
Closing popups
By default popups can be closed either by clicking outside the popup widget or by pressing the Esc key. To prevent this, the data-dismissible="false" attribute can be added to the popup. Popups can also be closed via the close method:
-
-
+
+
+
-
To add an explicit close button to a popup, add a link with the role of button into the popup container with a data-rel="back" attribute which will close the popup when tapped. We have created helper classes to position buttons in the upper left (ui-btn-left) or upper right (ui-btn-right) of the popup but you may need to tweak these or add custom positioning styles depending on your design. We recommend adding standard content padding to the popup to make room for the buttons (see next section).
-
-
-
-<div data-role="popup">
- <a href="#" data-rel="back" data-role="button" data-theme="a" data-icon="delete" data-iconpos="notext" class="ui-btn-right">Close</a>
+
+
+
+
-
+
Adding padding
-
- For popups with formatted text, padding is needed. We recommend adding the ui-content class to the popup container which adds the standard 15px of padding, just like the page content container. Write your own styles to create a more customized design if needed.
-
-
-<a href="#popupPadded" data-rel="popup" data-role="button">Popup with padding</a>
-
-<div data-role="popup" id="popupPadded" class="ui-content">
- <p>This is a popup with the <code>ui-content</code> class added to the popup container.</p>
-</div>
-
-
+
+ For popups with formatted text, padding is needed. We recommend adding the ui-content class to the popup container which adds the standard 1em (16px) of padding, just like the page content container. Write your own styles to create a more customized design if needed.
+
+
+
This will result in the following popup with content padding:
-
+
When padding is added, we apply a few style rules to negate the top margin for the first heading or paragraph in the popup and do the same for the last element's bottom margin. This keep the popups from having too much vertical space when the content padding and element margins combine.
-
-
+
+
Positioning options
By default, popups open centered vertically and horizontally over the thing you clicked (the origin) which is good for popups used as tooltips or menus. The framework also applies some basic collision detection rules to ensure that the popup will appear on-screen so the ultimate position may not always be centered over the origin.
- For situations like a dialog or lightbox where the popup should appear centered within the window instead of over the origin, add the data-position-to attribute to the link and specify a value of window.
- It's also possible to specify any valid selector as the value of position-to in addition to origin and window. For example, if you add data-position-to="#myElement" the popup will be positioned over the element with the id myElement.
+ For situations like a dialog or lightbox where the popup should appear centered within the window instead of over the origin, add the data-position-to attribute to the link and specify a value of window.
+ It's also possible to specify any valid selector as the value of position-to in addition to origin and window. For example, if you add data-position-to="#myElement" the popup will be positioned over the element with the id myElement.
A few examples:
-
+
The popup's placement constraints, which may cause the popup not to appear centered as desired, are as follow:
- The width of the popup will be limited using CSS
max-width to the width of the window minus a tolerance of 15px on either side.
- - A tolerance from the edges of the window (15px from each of the sides and 30px from the top and the bottom) will be observed when the popup fits inside the window. Tall popups are allowed to overflow the top and bottom edges of the window. Those parts of the popup can be viewed by manually scrolling the document. This tolerance is a configurable option.
+ - A tolerance from the edges of the window (15px from each of the sides and 30px from the top and the bottom) will be observed when the popup fits inside the window. Tall popups are allowed to overflow the top and bottom edges of the window. Those parts of the popup can be viewed by manually scrolling the document. This tolerance can be configured via the tolerance option.
- The top coordinate of the popup will never be negative. This ensures that the top of the popup will not be cut off.
- If centering the popup over an element would cause the overall height of the document to increase, the popup is shifted upwards at most until its top coordinate becomes 0.
-
+
Also note that a popup is currently always placed at the center of the window after an orientation change or window resize event.
- See methods for information about setting the popup position programmatically, including the option to specify x and y coordinates.
+ See methods for information about setting the popup position programmatically, including the option to specify x and y coordinates.
Setting transitions
By default, popups have no transition to make them open as quickly as possible. To set the transition used for a popup, add the data-transition attribute to the link that references the popup. The reverse version of the transition will be used when closing the popup.
-
-
-<a href="#transitionExample" data-transition="flip" data-rel="popup">
- Flip transition
-</a>
-
-
+
+
+
For performance reasons on mobile devices, we recommend using simpler transitions like pop, fade or none for smooth and fast popup animations, especially with larger or complex widgets within a popup. To view all transition types, you must be on a browser that supports 3D transforms. By default, devices that lack 3D support (such as Android 2.x) will fallback to "fade" for all transition types. See the transitions page for detailed information on the transition system.
-
+
When you launch the popup from any of the buttons, the data-transition set on the button will be used. However, if you launch the popup programmatically, such as via $( "#transitionExample" ).popup( "open" ), the data-transition attribute specified in the definition of the popup will be used if present.
-
Theming the popup and overlay
-
+
The popup plugin provides two theme-related options: data-theme and data-overlay-theme. The data-theme option refers to the theme of the popup itself, whereas data-overlay-theme refers to the theme of the popup's background, which covers the entire window behind the popup.
data-theme will be inherited from the page, and will always have a valid value when the popup opens, unless you explicitly specify data-theme="none", in which case the popup will have a transparent background.
The data-overlay-theme will never be set, and the popup's background, although always present when the popup is shown, will be completely transparent, unless explicitly set using for example data-overlay-theme="a". In this case, the background will fade in, partially obscuring the rest of the window, to further direct attention to the popup. Here is an example of an explicitly themed popup:
-
-<div id="both" data-role="popup" data-theme="e" data-overlay-theme="a" class="ui-content">
- ...Popup contents...
-</div>
-
-
+
+
-
- Note: Chaining of popups not allowed
+
+ Arrows
+ The extension widgets/popup.arrow provides the arrow option, which is also exposed as a data attribute. For example, data-arrow="t,b" will result in the popup being displayed with a top or a bottom arrow.
+ When an arrow is requested using the arrow option, the popup is positioned along one of the edges of the popup such that the arrow points at the center of the origin. The value of the arrow option is a comma-separated list of letters referring to the edges of the popup along which the framework should attempt to place the arrow:
+
+ t The framework should attempt to place the popup such that the arrow somewhere along the top edge of the popup points at the center of the origin. r The framework should attempt to place the popup such that the arrow somewhere along the right edge of the popup points at the center of the origin. b The framework should attempt to place the popup such that the arrow somewhere along the bottom edge of the popup points at the center of the origin. l The framework should attempt to place the popup such that the arrow somewhere along the left edge of the popup points at the center of the origin.
+
+ For each edge given in the list, the framework calculates
+
+ - the distance between the tip of the arrow and the center of the origin, and
+ - whether minimizing the above distance would cause the arrow to appear too close to one of the corners of the popup along the given edge.
+
+ If the second condition applies, the edge is discarded as a possible solution for placing the arrow. Otherwise, the calculated distance is examined. If it is 0, meaning that the popup can be placed exactly such that the tip of the arrow points at the center of the origin, no further edges are examined, and the popup is positioned along the last examined edge. Thus, the order in which the edges are given matters.
+ The example below shows a popup with an arrow either along its left edge or along its top edge.
+
+
+
+
+ Note: Chaining of popups not allowed
The framework does not currently support chaining of popups so it's not possible to embed a link from one popup to another popup. All links with a data-rel="popup" inside a popup will not do anything at all.
This also means that custom select menus will not work inside popups, because they are themselves implemented using popups. If you place a select menu inside a popup, it will be rendered as a native select menu, even if you specify data-native-menu="false".
A workaround to get chained popups working is the use of a timeout for example in the popupafterclose event bound to the invoking popup. In the following example, when the first popup is closed, the second will be opened by a delayed call to the open method:
-
+
+
+ The div or, if the element is not inside a page, it will become the last child element of the body. It then wraps the element in a container div, and prepends a newly created element that serves as the modal overlay screen to the parent of the container.
+ The example below includes an entire jQuery Mobile page rather than just the popup. This helps illustrate where you must place the markup for the pre-rendered popup widget in relation to the jQuery Mobile page on which it is to appears. In the example, the popup has the attribute data-overlay-theme="b" to reflect the fact that the modal overlay screen has an associated theme.
+
+
+
+
+
1.2
+
+
The default rangeslider with these settings is displayed like this:
-
+
Step increment
To force the range to snap to a specific increment, add the step attribute to the input. By default, the step is 1, but in this example, the step is 0.1 and the maximum value is 10.
In this example, the acceptable range is 0-100.
-
-<div data-role="rangeslider">
- <label for="range-10a">Rangeslider:</label>
- <input name="range-10a" id="range-10a" min="0" max="10" step=".1" value="0" type="range" />
- <label for="range-10b">Rangeslider:</label>
- <input name="range-10b" id="range-10b" min="0" max="10" step=".1" value="10" type="range" />
-</div>
-
+
This will produce an input that snaps to increments of 0.1. 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.
Fill highlight
- By default, there is a highlight fill on the track between the two slider handles. To remove it, add the data-highlight="false" attribute to the input. The fill uses active state swatch.
-
-
-<div data-role="rangeslider" data-highlight="false">
- <label for="range-2a">Rangeslider (default is "true"):</label>
- <input name="range-2a" id="range-2a" min="0" max="100" value="0" type="range" />
- <label for="range-2b">Rangeslider:</label>
- <input name="range-2b" id="range-2b" min="0" max="100" value="100" type="range" />
-</div>
-
+ By default, there is a highlight fill on the track between the two slider handles. To remove it, add the data-highlight="false" attribute to the input. The fill uses the active state swatch.
+
+
-
+
Theming the slider
To set the theme swatch for the rangeslider, add a data-theme attribute to the inputs which will apply the theme to the inputs, handles and track. The track swatch can be set separately by adding the data-track-theme attribute to apply the down state version of the selected button swatch.
-
-<div data-role="rangeslider" data-track-theme="b" data-theme="a">
- <label for="range-3a">Rangeslider:</label>
- <input name="range-3a" id="range-3a" min="0" max="100" value="0" type="range" />
- <label for="range-3b">Rangeslider:</label>
- <input name="range-3b" id="range-3b" min="0" max="100" value="100" type="range" />
-</div>
-
+
This will produce a themed rangeslider:
-
+
Mini version
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-
-<div data-role="rangeslider" data-mini="true">
- <label for="range-4a">Rangeslider:</label>
- <input name="range-4a" id="range-4a" min="0" max="100" value="0" type="range" />
- <label for="range-4b">Rangeslider:</label>
- <input name="range-4b" id="range-4b" min="0" max="100" value="100" type="range" />
-</div>
-
+
This will produce a rangeslider and its corresponding inputs that are not as tall as the standard version. The inputs also have a smaller text size.
Field containers
- Optionally wrap the rangeslider markup in a container with the data-role="fieldcontain" attribute 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.
+ Optionally wrap the rangeslider markup in a container with class ui-field-contain 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.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Use the ui-field-contain class instead.
-
-<div data-role="fieldcontain">
- <div data-role="rangeslider">
- <label for="range-7a">Rangeslider:</label>
- <input name="range-7a" id="range-7a" min="0" max="100" value="0" type="range" />
- <label for="range-7b">Rangeslider:</label>
- <input name="range-7b" id="range-7b" min="0" max="100" value="100" type="range" />
- </div>
-</div>
-
+
The rangeslider is now displayed like this:
-
+
Sliders also respond to key commands. Right Arrow, Up Arrow and Page Up keys increase the value; Left Arrow, Down Arrow and Page Down keys decrease it. To move the slider to its minimum or maximum value, use the Home or End key, respectively.
Calling the rangeslider plugin
- This plugin will auto initialize on any page that contains a text input with the type="range" attribute. However, if needed you can directly call the rangeslider plugin on any selector, just like any jQuery plugin:
+ This plugin will auto initialize on any page that contains a div with the data-role="rangeslider" attribute. However, if needed you can directly call the rangeslider plugin on any selector, just like any jQuery plugin:
+
+
-
-$( "input" ).rangeslider();
-
-
-
1.3
-
+
-
- triggered when a rangeslider is created
-
-
-
-
-
+
- triggered when the input values are normalized (generally happens when you try to drag one handle past the other).
+ triggered when the input values are normalized (generally happens when you try to drag one handle past the other).
-
- enable a disabled rangeslider.
-
-
-
- disable a rangeslider.
-
-
+
update the rangeslider.
If you manipulate a rangeslider via JavaScript, you must call the refresh method on it to update the visual styling.
diff --git a/entries/responsive-grid.xml b/entries/responsive-grid.xml
index e804f977..32e5e368 100644
--- a/entries/responsive-grid.xml
+++ b/entries/responsive-grid.xml
@@ -4,103 +4,105 @@
Responsive Grid
Reponsive layout grids
-
+
Responsive grids
-
+
When using layout grids for building full-level layouts, it may make sense to apply responsive web design (RWD) principles to ensure that the layout adapts to a wide range screen widths.
The simplest form of responsive behavior swaps from a stacked layout on narrow screens like a smartphone to the multi-column grid layouts at wider screens. This can be done by targeting styles to specific screen widths by using CSS media queries.
-
+
Making the grids responsive
-
+
By default, the grid classes will result in a multi column layout across all screen widths. The styles to make the grids responsive are added by applying a media query with rules to switch to the stacked style presentation below a specific screen width.
-
+
We normally recommend starting with mobile-first approach for media queries: starting with the styles that apply to the smallest screen sizes in the core widget styles, then progressively layering breakpoints up to larger screens by using min-width media queries.
However, in the case of grids we can use a max-width media query to only apply the stacked grid styles below a width breakpoint. This allows us to leverage all the default grid styles but just tweak them at narrow widths.
-
+
Without the custom styles, our grid will be a 3 column layout across all screen widths:
-
+
In our custom styles, we want this grid to stack at narrow widths, then switch to a standard 3 column layout. At very wide screen widths, we want first column to take up 50% of the width, like this:
-
+
-
+
To make this responsive, start by adding the my-breakpoint class to the grid container that references the custom breakpoint in your custom stylesheet:
-
-<div class="ui-grid-b my-breakpoint">
- <div class="ui-block-a">Block A</div>
- <div class="ui-block-b">Block B</div>
- <div class="ui-block-c">Block C</div>
-</div><!-- /grid-b -->
-
-
+
+
Adding the stack breakpoint at narrow widths
-
+
This class is used to scope the styles within the custom media query so they will only apply when this class is added to the grid container. The media query wraps the conditional styles we only want applied below 50em.
In your media queries, use em units instead of pixels to ensure that the media query will take font size into account in addition to just screen width. To calculate a screen widths in ems, divide the target width in pixels by 16 which is the default font size of the body.
-
-
+
+
Within this media query, we set the width to 100% and negate the float property to make the grid blocks stack below 50em screen widths. These rules are applied to every grid type by stacking up selectors for all the grid classes from ui-block-a to ui-block-e on the styles.
-
-
+
+
That is all it takes to make grids responsive and it's easy to add additional styling rules to each breakpoint to change it up even more. We encourage you to create as many custom breakpoints as you need based on your unique content and layout needs.
-
+
Adding a widescreen breakpoint to adjust ratios
Building on the example above, we can add an additional breakpoint to shift the widths to make the first column 50% width and the other two 25% above 75em (1,200 pixels) by layering an additional min-width media query to tweak widths in our custom style like this:
-
-
+
+
+
Note the slightly narrower widths set to work around rounding issues across platforms.
-
+
Applying a preset breakpoint
-
+
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 the multi-column presentation on larger phones, tablet and desktop devices.
To use this preset breakpoint, add the ui-responsive class to the grid container to apply the stacked presentation below 560px (35em). If this breakpoint doesn't work for your content, we encourage you to write a custom breakpoint as described above.
- <div class="ui-grid-b ui-responsive">
-
+
+
These are standard grids that are made responsive by ui-responsive class to the grid container:
Grid A (50/50)
-
+
Grid B (33/33/33)
-
+
-
+
Grid C (25/25/25/25)
-
+
-
+
Grid D (20/20/20/20/20)
-
+
1.3
@@ -114,32 +116,32 @@
A basic example of responsive grids
1.0
-
+
scrollstop
Triggers when a scroll finishes.
-
+
1.0
-
+
+
Selectmenu Widget
Creates a select menu widget
The select menu is based on a native select element, which is hidden from view and replaced with a custom-styled select button that matches the look and feel of the jQuery Mobile framework. The select menu is ARIA-enabled and keyboard accessible on the desktop as well.
By default, the framework leverages the native OS options menu to use with the custom button. When the button is clicked, the native OS menu will open. When a value is selected and the menu closes, the custom button's text is updated to match the selected value. Please note that the framework also offers the possibility of having custom (non-native) select menus.
To add a select menu to your page, start with a standard select element populated with a set of option elements. Set the for attribute of the label to match the id of the select 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.
-
+
The framework will find all select elements and automatically enhance them into select menus, no need to apply a data-role attribute. To prevent the automatic enhancement of a select, add data-role="none" attribute to the select.
-
-
-<label for="select-choice-0" class="select">Shipping method:</label>
-<select name="select-choice-0" id="select-choice-0">
- <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>
-
+
+
This will produce a basic select menu. The default styles set the width of the input to 100% of the parent container and stacks the label on a separate line.
-
+
Mini version
-
+
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-
-<label for="select-choice-min" class="select">Shipping method:</label>
-<select name="select-choice-min" id="select-choice-min" data-mini="true">
- <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>
-
-
+
+
This will produce a select that a not as tall as the standard version and has a smaller text size.
-
+
Field containers
-
- Optionally wrap the selects in a container with the data-role="fieldcontain" attribute to help visually group it in a longer form.
-
-
-<div data-role="fieldcontain">
- <label for="select-choice-1" class="select">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>
-
-
+
+ Optionally wrap the selects in a container with class ui-field-contain to help visually group it in a longer form.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
+
+
+
The select input is now displayed like this:
-
+
An example of a select with a long list of options:
Optgroups
The following example organizes the options into optgroup elements. Support for this feature in mobile selects is a bit spotty, but is improving.
-
-<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">Express: next day (disabled)</option>
- <option value="overnight">Overnight</option>
- </optgroup>
- </select>
-</div>
-
+
@@ -97,49 +98,49 @@
Because the label element will be associated with each individual select input and will be hidden for styling purposes, we recommend wrapping the selects in a fieldset element that has a legend which acts as the combined label for the grouped inputs.
- Lastly, one needs to wrap the fieldset in a div with data-role="controlgroup" attribute, so it can be styled as a group.
-
-
-<div data-role="fieldcontain">
- <fieldset data-role="controlgroup">
- <legend>Date of Birth:</legend>
-
- <label for="select-choice-month">Month</label>
- <select name="select-choice-month" id="select-choice-month">
- <option>Month</option>
- <option value="jan">January</option>
- <!-- etc. -->
- </select>
-
- <label for="select-choice-day">Day</label>
- <select name="select-choice-day" id="select-choice-day">
- <option>Day</option>
- <option value="1">1</option>
- <!-- etc. -->
- </select>
-
- <label for="select-choice-year">Year</label>
- <select name="select-choice-year" id="select-choice-year">
- <option>Year</option>
- <option value="2011">2011</option>
- <!-- etc. -->
- </select>
- </fieldset>
-</div>
-
-
+ Lastly, one needs to wrap the fieldset in a div with data-role="controlgroup" attribute, so it can be styled as a group.
+
+
+
Horizontally grouped select inputs
Select inputs can also be used for grouped sets with more than one related selections. To make a horizontal button set, add the data-type="horizontal" to the fieldset. Note that the buttons which trigger the select will resize depending on the currently selected option’s value.
-
-<fieldset data-role="controlgroup" data-type="horizontal">
-
+
-
+
Theming selects
-
+
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:
@@ -150,48 +151,49 @@
You can optionally use custom-styled select menus instead of the native OS menu. The custom menu supports disabled options and multiple selection (whereas native mobile OS support for both is inconsistent), adds an elegant way to handle placeholder values, and restores missing functionality on certain platforms such as optgroup support on Android (all explained below). In addition, the framework applies the custom button's theme to the menu to better match the look and feel and provide visual consistency across platforms. Lastly, custom menus often look better on desktop browsers because native desktop menus are smaller than their mobile counterparts and tend to look disproportionate.
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.
-
+
To use custom menus on a specific select, just add the data-native-menu="false" attribute. Alternately, this can also programmatically set the select menu's nativeMenu configuration option to false in a callback bound to the mobileinit 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.
-
-
+
+
When the select has a small number of options that will fit on the device's screen, the menu will appear as a small overlay with a pop transition:
-
+
When it has too many options to show on the device's screen, the framework will automatically create a new "page" populated with a standard listview for the options. This allows us to use the native scrolling included on the device for moving through a long list. The text inside the label is used as the title for this page.
-
+
Disabled options
-
+
jQuery Mobile will automatically disable and style option tags with the disabled attribute. In the demo below, the second option "Rush: 3 days" has been set to disabled.
-
+
-
+
Placeholder options
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:
- - An option with no value attribute (or an empty value attribute)
+ - An option with no value attribute
+ - An option with an empty value attribute (
value=""). Indicating that an option should be used as a placeholder by providing the value attribute and setting it to "" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0.
- An option with no text node
- An option with a
data-placeholder="true" attribute. (This allows you to use an option that has a value and a textnode as a placeholder option).
You can disable this feature through the selectmenu plugin's hidePlaceholderMenuItems option, like this:
-
+
Examples of various placeholder options:
- Multiple selects
-
+ Multiple selects
+
If the multiple attribute is present in your markup, jQuery Mobile will enhance the element with a few extra considerations:
@@ -205,18 +207,18 @@ $.mobile.selectmenu.prototype.options.hidePlaceholderMenuItems = false;
-
+
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 label 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.
-
+
Optgroup support
-
+
If a select menu contains optgroup elements, jQuery Mobile will create a divider & group items based on the label attribute's text:
Theming selects
-
+
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:
@@ -225,25 +227,47 @@ $.mobile.selectmenu.prototype.options.hidePlaceholderMenuItems = false;
Calling the select menu plugin
-
+
The select menu plugin will auto initialize on any page that contains a select menu, without any need for a data-role attribute in the markup. However, you can directly call the select menu plugin on any selector, just like any normal jQuery plugin:
-
-$( "select" ).selectmenu();
-
-
+
+
1.0
+
-
-
- triggered when a text input is created
-
-
-
-
-
+
close an open select menu.
-
- enable a disabled text input.
-
-
-
- disable a text input.
-
-
+
open a closed select menu (custom menus only).
+
-
+
update the custom select.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.
@@ -375,7 +364,7 @@ $( document ).on( "mobileinit", function() {
Slider Widget
Creates a slider widget
Slider
+ Note: The To add a slider widget to your page, use a standard input with the type="range" attribute. The input's value is used to configure the starting position of the handle and the value is populated in the text input. Specify min and max attribute values to set the slider's range. If you want to constrain input to specific increments, add the step attribute. Set the value attribute to define the initial value. The framework will parse these attributes to configure the slider widget.
As you drag the slider's handle, the framework will update the native input's value (and vice-versa) so they are always in sync; this ensures that the value is submitted with the form.
Set the for attribute of the label to match the id of the input 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.
- The framework will find all input elements with a type="range" and automatically enhance them into a slider with an accompanying input without any need to apply a data-role attribute. To prevent the automatic enhancement of this input into a slider, add data-role="none" attribute to the input and wrap them in a div with the data-role="fieldcontain" attribute to group them.
+ The framework will find all input elements with a type="range" and automatically enhance them into a slider with an accompanying input without any need to apply a data-role attribute. To prevent the automatic enhancement of this input into a slider, add data-role="none" attribute to the input.
In this example, the acceptable range is 0-100.
-
-<label for="slider-1">Input slider:</label>
-<input type="range" name="slider-1" id="slider-1" value="60" min="0" max="100" />
-
+
The default slider with these settings is displayed like this:
-
+
Step increment
To force the slider to snap to a specific increment, add the step attribute to the input. By default, the step is 1, but in this example, the step is 50 and the maximum value is 500.
In this example, the acceptable range is 0-100.
-
-<label for="slider-1">Input slider:</label>
-<input type="range" name="slider-1" id="slider-1" value="60" min="0" max="100" />
-
+
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.
@@ -34,94 +35,95 @@
Fill highlight
To have a highlight fill on the track up to the slider handle position, add the data-highlight="true" attribute to the input. The fill uses active state swatch.
-
-
-<label for="slider-fill">Input slider:</label>
-<input type="range" name="slider-fill" id="slider-fill" value="60" min="0" max="100" data-highlight="true" />
-
+
+
-
+
Mini version
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-
-<label for="slider-mini">Input slider:</label>
-<input type="range" name="slider-mini" id="slider-mini" value="25" min="0" max="100" data-highlight="true" data-mini="true" />
-
+
This will produce a slider and its corresponding input that are not as tall as the standard version. The input also has a smaller text size.
Field containers
- Optionally wrap the slider markup in a container with the data-role="fieldcontain" attribute 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.
+ Optionally wrap the slider markup in a container with class ui-field-contain 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.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
-
-<div data-role="fieldcontain">
- <label for="slider-2">Input slider:</label>
- <input type="range" name="slider-2" id="slider-2" value="25" min="0" max="100" />
-</div>
-
+
The slider is now displayed like this:
-
+
Sliders also respond to key commands. Right Arrow, Up Arrow and Page Up keys increase the value; Left Arrow, Down Arrow and Page Down keys decrease it. To move the slider to its minimum or maximum value, use the Home or End key, respectively.
Calling the slider plugin
This plugin will auto initialize on any page that contains a text input with the type="range" attribute. However, if needed you can directly call the slider plugin on any selector, just like any jQuery plugin:
-
+
Theming the slider
To set the theme swatch for the slider, add a data-theme attribute to the input which will apply the theme to both the input, handle and track. The track swatch can be set separately by adding the data-track-theme attribute to apply the down state version of the selected button swatch.
-
-<div data-role="fieldcontain">
- <label for="slider-3">Input slider:</label>
- <input type="range" name="slider-3" id="slider-3" value="25" min="0" max="100" data-theme="a" data-track-theme="b" />
-</div>
-
+
This will produce a themed slider:
-
+
Flip Toggle Switch
-
+
A binary "flip" switch is a common UI element on mobile devices that is used for binary on/off or true/false data input. You can either drag the flip handle like a slider or tap one side of the switch.
To create a flip toggle, start with a select 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.
Set the for attribute of the label to match the id of the input 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.
-
-<label for="flip-1">Flip switch:</label>
-<select name="flip-1" id="flip-1" data-role="slider">
- <option value="off">Off</option>
- <option value="on">On</option>
-</select>
-
-
+
+
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.
-
+
Longer Labels
-
+
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:
-
-<div class="containing-element">
- <label for="flip-min">Flip switch:</label>
- <select name="flip-min" id="flip-min" data-role="slider">
- <option value="off">Switch Off</option>
- <option value="on">Switch On</option>
- </select>
-</div>
-
+
.containing-element .ui-slider-switch { width: 9em } will produce:
@@ -132,68 +134,69 @@ $( "input" ).slider();
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-
-<label for="flip-mini">Select slider:</label>
-<select name="flip-mini" id="flip-mini" data-role="slider" data-mini="true">
- <option value="off">Off</option>
- <option value="on">On</option>
-</select>
-
+
This will produce a flip switch that is not as tall as the standard version and has a smaller text size.
Field containers
- Optionally wrap the switch markup in a container with the data-role="fieldcontain" attribute 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.
+ Optionally wrap the switch markup in a container with class ui-field-contain 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.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
+
+
-
-<div data-role="fieldcontain">
- <label for="flip-2">Select slider:</label>
- <select name="flip-2" id="flip-2" data-role="slider" data-mini="true">
- <option value="off">Off</option>
- <option value="on">On</option>
- </select>
-</div>
-
-
The flip toggle switch is now displayed like this:
-
- Theming the flip switch
-
- Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the data-theme attribute on the select and specify a swatch letter.
-
-
-<div data-role="fieldcontain">
- <label for="flip-3">Flip switch:</label>
- <select name="flip-3" id="flip-3" data-role="slider" data-theme="a">
- <option value="no">No</option>
- <option value="yes">Yes</option>
- </select>
-</div>
-
-
- This results in a switch with the swatch "a" colors for the handle. Note that the lefthand "on" state gets the active state color.
+
+
Theming the flip switch
+
+ Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the data-theme attribute on the select and specify a swatch letter.
+
+
+
+ This results in a switch with the swatch "b" colors for the handle. Note that the lefthand "on" state gets the active state color.
- Here is a swatch "e" variation:
+
Here is a swatch "a" variation:
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.
- Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:
+ Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:
-
-<div data-role="fieldcontain">
- <label for="flip-5">Flip switch:</label>
- <select name="flip-5" id="flip-5" data-role="slider" data-theme="c" data-track-theme="a">
- <option value="no">No</option>
- <option value="yes">Yes</option>
- </select>
-</div>
-
+
-
+
Calling the switch plugin
This plugin will auto initialize on any page that contains a text input with the type="slider" attribute. However, if needed you can directly call the slider plugin on any selector, just like any jQuery plugin:
@@ -206,70 +209,44 @@ $( "input" ).slider();
Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the data-theme attribute on the select and specify a swatch letter.
-
-<div data-role="fieldcontain">
- <label for="flip-3">Flip switch:</label>
- <select name="flip-3" id="flip-3" data-role="slider" data-theme="a">
- <option value="no">No</option>
- <option value="yes">Yes</option>
- </select>
-</div>
-
-
+
+
This results in a switch with the swatch "a" colors for the handle. Note that the lefthand "on" state gets the active state color.
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.
Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:
-
-<div data-role="fieldcontain">
- <label for="flip-5">Flip switch:</label>
- <select name="flip-5" id="flip-5" data-role="slider" data-theme="c" data-track-theme="a">
- <option value="no">No</option>
- <option value="yes">Yes</option>
- </select>
-</div>
-
+
1.0
-
+
-
- triggered when a slider is created
-
-
-
-
-
+
- triggered when there's an initial interaction with the slider. Includes drags and taps.
+ triggered when there's an initial interaction with the slider. Includes drags and taps.
- triggered at the end of an interaction with the slider. Includes drags and taps.
+ triggered at the end of an interaction with the slider. Includes drags and taps.
-
- enable a disabled slider.
-
-
-
- disable a slider.
-
-
+
update the slider.
If you manipulate a slider via JavaScript, you must call the refresh method on it to update the visual styling.
@@ -320,7 +287,7 @@ $( document ).on( "mobileinit", function() {
@@ -330,7 +297,7 @@ $( document ).on( "mobileinit", function() {
+]]>
This method recieves a touchstart event and returns an object of data about the starting location.
$.event.special.swipe.stop Default:
-
+
+]]>
This method recieves a touchend event and returns an object of data about the ending location.
$.event.special.swipe.handleSwipe Default:
-
+ $.event.special.swipe.horizontalDistanceThreshold &&
+ Math.abs( start.coords[ 1 ] - stop.coords[ 1 ] ) < $.event.special.swipe.verticalDistanceThreshold ) {
start.origin.trigger( "swipe" )
- .trigger( start.coords[0] > stop.coords[ 0 ] ? "swipeleft" : "swiperight" );
+ .trigger( start.coords[0] > stop.coords[ 0 ] ? "swipeleft" : "swiperight" );
}
}
-
+]]>
This method recieves the start and stop objects and handles the logic for and triggering for the swipe events.
Swipe the green rectangle to change its color:
]]>
-
+
Swipe the green rectangle in the left direction to change its color:
]]>
-
+
Swipe the green rectangle in the right direction to change its color:
]]>
-
+
Creates a responsive table in column toggle mode
This table mode automatically hides less important columns at narrower widths and surfaces a button to open a menu that allows the user to choose what columns they want to see. In this mode, the author attempts to define which columns are most important to show across various widths by assigning a priority to each column.
-
- A user may choose to check as many columns as they want by tapping the "Columns..." button to open the column
+
+
A user may choose to check as many columns as they want by tapping the "Columns..." button to open the column
chooser popup. The popup contains a dynamically generated list of columns based on the table markup that can be checked and unchecked to adjust the visible columns.
-
+
Applying column chooser mode to a table
The column chooser mode requires a table element with two attributes: data-role="table" and data-mode="columntoggle". An ID attribute is also required on the table to associate it with the column chooser popup menu.
- <table data-role="table" data-mode="columntoggle" id="my-table">
-
+
+
How column toggle mode works
-
+
The plugin automates a few key things: it injects the column chooser button, and generates the popup with check list of columns that can be hidden or shown by the user. The list of columns in the chooser menu is populated by parsing the values (or abbr title) of the first row of header (TH) elements. Only headers that have a data-priority attribute are included in the column chooser; headers without this attribute won't made available in the chooser to allow developers to identify critical columns that shouldn't be hidden. If columns are hidden via responsive media queries, these will be unchecked in the chooser to reflect the current column visibility.
The automatic column hiding behavior is accomplished by CSS media queries that hide or show columns based on priority levels at various screen widths. Since each site will have different content and column configurations, we provide a simple media query block that you can copy, paste and customize for each project. This is explained in detail below.
The priorities assigned to headers and media queries used to hide columns act as a sensible default for showing the most important columns that will fit on a device. The column chooser menu gives users the ability to override these defaults and choose which columns they want to see. These user preferences take precedence over the priority mappings so if a column is manually checked, it will remain visible across all screen widths until the page is refreshed.
-
+
Because of the flexibility this plugin provides, it's possible for users to introduce horizontal scrolling if the data in each column is long or if many columns are selected to be shown on a smaller screen.
Setting column priority
@@ -31,59 +33,61 @@
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 data-priority 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.
To make a column persistent so it's not available for hiding, omit the data-priority attribute. This will make the column visible at all widths and won't be available in the column chooser menu.
-<th>I'm am 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>
-
+
+
-
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 data-priority="3" attribute, every cell in that column will assigned a ui-table-priority-3 class once enhanced. These classes are then used in media queries to hide and show columns based on screen width (see below).
-
-<td class="ui-table-priority-3">97%</td>
-
-
+
+
+
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 data-priority attribute so even though we default to using a numeric system of 1-6, any naming convention is possible.
-
- For example, if a priority of data-priority="critical" is added to the heading, a class of ui-table-priority-critial will be applied to each cell in that column. If a priority is assigned, the column will be made available for the toggling in the column menu and adds the classes to each cell, the rest of the styling and media query creation is up to you write in your custom stylesheet.
-
+
+ For example, if a priority of data-priority="critical" is added to the heading, a class of ui-table-priority-critial will be applied to each cell in that column. If a priority is assigned, the column will be made available for the toggling in the column menu and adds the classes to each cell, the rest of the styling and media query creation is up to you write in your custom stylesheet.
+
It is important to note that you are required to wrap your table headers in a <thead> ... </thead> block, and the table body in a <tbody> ... </tbody> block, as shown in the full demo Example.
-
+
Making the table responsive
-
+
The styles for the all priority columns (1-6) start as display:none in the structure stylesheet since we're taking a mobile-first approach to our styles. This means that only columns that should be persistent are visible in the styles to start.
-
+
The framework does not automatically include the the media queries to progressively display columns at wider widths. We do this to make it easier for developers to customize the media query widths for each priority level.
-
+
Media queries add the responsive behavior to show and hide columns by priority. Each media query is written using min-width widths so they build on top of each other. The widths are set in ems so they respond to font size changes. To calculate a pixel withs in em's, divide the target width by 16 (pixels) - it's that easy.
-
+
Inside each media query, we override the display:none style properties set on all the priority columns in the basic styles to display:table-cell so they become visible again and act as a table.
-
+
To customize the breakpoints, copy the following style block into your custom style overrides and adjust the min-width media query values for each priority level to specify where various priority columns should appear.
-
- In the example styles below for a my-custom-class class on the table, the priority 1 columns are shown first, at widths above 20em (320px), then priority 2 kicks in above 30em (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.
+
+ In the example styles below for a my-custom-class class on the table, the priority 1 columns are shown first, at widths above 20em (320px), then priority 2 kicks in above 30em (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.
-
-/* Show priority 1 at 320px (20em x 16px) */
+
Due to CSS specificity, you will also need to include the class definitions for the hidden and visible states after the custom breakpoints in your custom stylesheet so be sure to include these as well:
-
-/* Manually hidden */
+
+
Applying a preset breakpoint
-
+
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.
-
+
These breakpoints can applied by adding a class="ui-responsive" to the table element. Here is an example of a table with this class added:
- <table data-role="table" class="ui-responsive" data-mode="columntoggle" id="my-table">
+
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:
-
+
data-priority="1"- Displays the column at 320px (20em)
data-priority="2"- Displays the column at 480px (30em)
@@ -122,23 +128,135 @@
When the column chooser menu opens, the column checkboxes will be checked or unchecked based on the visibility of each column based on the media queries so it accurately reflects what is being seen. These media queries to hide or show columns act as sensible defaults for what columns should be shown based on the developer's understanding of the column importance and data values. The chooser menu allows the user to have control of the table presentation so this takes precedence over the default display.
If an unchecked column checkbox is checked by the user, they now take control of the column. Until the page is refreshed, the visibility of that column will now always be visible, even if the screen is re-sized. Behind the scenes, a class of ui-table-cell-visible is added to all the cells in that column to ensure they override any visibility set via media queries.
-
+
The same idea applies when a column is unchecked: from then on, the column won't be seen at any width because the class of ui-table-cell-hidden is added to each of the cells in that column.
Styling the button and column chooser popup
-
+
The column chooser popup is opened via a button that is generated by the framework. The button's text is "Columns..." by default but can be set by adding the data-column-btn-text attribute to the table to the text string you want in the button. The button will inherit the theme from the content area, just like all buttons, but the theme can be set manually by adding the data-column-btn-theme attribute to any swatch letter in your theme.
-
+
This button is injected directly before the table element and has basic styles to align it to the right but you may want to further customize the appearance of this button. To style all these buttons across your site, key off the ui-table-columntoggle-btn structural class on this link.
To target styles against only a specific button, use the unique href value that is generated to target a specific column chooser button. For example, a table with an ID of movie-table will generate a popup with an ID of movie-table-popup so a CSS selector of a[href="#movie-table-popup"] will target only the column popup button for this specific table.
-
+
The theme for the column chooser popup can be set by adding the data-column-popup-theme attribute to the table and specifying any swatch letter in your theme. For custom styles or scripting, all the column chooser popups can be targeted by using the ui-table-columntoggle-popup structural class added to these popups. To customize a single popup, use the generated ID based on the table ID that added to each specific popup (such as #movie-table-popup) to target a specific popup.
Working with grouped column headers
It's fairly common to need to logically group multiple columns together under a heading group for financial or scientific data. The framework can support the most simple version of this by allowing for two rows of table headers (TH), with the first row containing simple colspan attributes to group the columns below. In this configuration, the framework will parse the first row only for the priority and expose these heading groups as the options in the column chooser popup. In this configuration, the second heading will not be exposed as columns that can be hidden or shown independently of the groupings in the chooser.
-
+
+ The columntoggle table places an anchor before the table that invokes a popup listing the columns available for showing/hiding. The ID of the popup and thus the href of the anchor should be the ID of the table suffixed by the string -popup. You may separately pre-enhance the popup widget, or you may allow autoinitialization to enhance it.
+ The popup widget must contain a single controlgroup widget which in turn contains all the checkboxes representing the columns of the table.
+ In the example below the parameter data-column-btn-theme="b" is added to the table explicitly to indicate that the theme applied to the "Columns..." button is not the default (null).
+
+
+
+
+
+
+ table-columntoggle demo
+
+
+
+
+
+
+
+ jQuery Mobile Example
+
+
+
+
+
+ Rank
+ Movie Title
+ Year
+ Rating
+ Reviews
+
+
+
+
+ 1
+ Citizen Kane
+ 1941
+ 100%
+ 74
+
+
+ 2
+ Casablanca
+ 1942
+ 97%
+ 64
+
+
+ 3
+ The Godfather
+ 1972
+ 97%
+ 87
+
+
+ 4
+ Gone with the Wind
+ 1939
+ 96%
+ 87
+
+
+ 5
+ Lawrence of Arabia
+ 1962
+ 94%
+ 87
+
+
+ 6
+ Dr. Strangelove Or How I Learned to Stop Worrying and Love the Bomb
+ 1964
+ 92%
+ 74
+
+
+ 7
+ The Graduate
+ 1967
+ 91%
+ 122
+
+
+ 8
+ The Wizard of Oz
+ 1939
+ 90%
+ 72
+
+
+ 9
+ Singin' in the Rain
+ 1952
+ 89%
+ 85
+
+
+ 10
+ Inception
+ 2010
+ 84%
+ 78
+
+
+
+
+
+
+
+]]>
+
+
1.3
@@ -158,7 +276,7 @@
-
+
Since this plugin is written as an extension to the core table plugin, it binds to the tablecreate event but does not issue any additional events.
@@ -205,7 +324,7 @@
The reflow table mode works by collapsing the table columns into a stacked presentation that looks like blocks of label/data pairs for each row. Since the HTML source order of a table prohibits styling a table to look like this, the plugin dynamically adds a bit of markup to make the display work (without affecting accessibility). Here is a demo of a basic table using reflow mode:
-
+
Applying reflow mode to a table
-
+
The reflow responsive table mode is the simplest in terms of markup requirements because it only requires a table with a data-role="table" on the table element. There is no need to set the data-mode attribute since reflow is the default.
-
- <table data-role="table" id="my-table">
+
+
How reflow mode works
-
+
The plugin works by parsing the values (or abbr title) of the first row of header (th) elements found in the table. For example, in the table above, the third table header is parsed to grab the contents ("Year"):
- <th>Year</th>
+
The script then appends an element with the table header text before the contents of every cell in that column. For example, for every table cell in the year column:
-
- <td>1941</td>
-
+
+
+
An element is added before the text of each cell with a class of ui-table-cell-label:
- <td><b class="ui-table-cell-label">Year</b>1941</td>
-
+
+
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 display:block so they are stacked. The the label element injected into each cell is styled as display:inline-block with a min-width:30% rule to place the labels on the same line as the content at a consistent width to form a two column presentation.
-
+
It is important to note that you are required to wrap your table headers in a <thead> ... </thead> block, and the table body in a <tbody> ... </tbody> block, as shown in the full demo Example.
Making the table responsive
-
+
By default, a table with reflow mode will display the stacked presentation style on all screen widths. The styles to make the table responsive are added by applying a media query with rules to switch to the tabular style presentation above a specific screen width.
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):
-
-
-@media ( min-width: 40em ) {
- /* Show the table header rows and set all cells to display: table-cell */
+
+
+
It's best to use a class on the table to apply the breakpoint. Add these rules to your custom stylesheet that is included in the head of the page. We recommend creating a set of custom breakpoint classes that can be used to apply standard table breakpoints in your project.
-
+
In the example above, we're assuming there is a class of my-custom-breakpoint added to the table to apply the breakpoint. Each of the rules in the custom media query are scoped against that table class to target only tables that have the my-custom-breakpoint class.
-
+
In order for this technique to work, a browser must support media queries and the ability to style table cells as block-level elements. In testing, most popular desktop and mobile browsers meet these criteria, but older versions of Internet Explorer (8 and older) fall back to a normal table presentation. IE 9 can support this technique but there are a few additional styles needed so we recommend applying these in a max-width media query to only apply them below the table presentation because they are hard to negate.
Choosing a breakpoint
@@ -69,12 +77,14 @@
Applying a preset breakpoint
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 ui-responsive 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.
-
- <table data-role="table" class="ui-responsive">
-
-
+
+
+
+
Working with grouped column headers
-
+
It's fairly common to need to logically group multiple columns together under a heading group for financial or scientific data. The framework can support the most simple version of this by allowing for two rows of table headers (TH), with the first row containing simple colspan attributes to group the columns below. In this configuration, the framework will add a class to the label of the first cell in each group to allow you to style these differently and provide aditional visual hierarchy.
@@ -92,17 +102,17 @@
-
+
Since this plugin is written as an extension to the core table plugin, it binds to the tablecreate event but does not issue any additional events.
@@ -124,7 +134,7 @@ $( document ).on( "mobileinit", function() {
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:
@@ -52,25 +53,18 @@
- The first row of the table must contain the table headers, be sure to use
TH instead of TD tags
- To display longer table header text in the column chooser or reflow labels, wrap the text in the
TH with a abbr element and set the title. This string will be used in place.
-
+
Styling and theming tables
-
+
The responsive table plugin is as minimally styled as possible to give you a clean slate for your designs. The plugin focuses primarily on the difficult scripting elements: generating the labels for the reflow table and creating the button and column chooser popup. Out of the box, the table just has a few basic style rules to add a bit of padding and set the vertical alignment of cells to be top left for visual consistency.
The table will adapt to whatever content block it sits on, but there isn't an explicit theming attribute for this widget. We did this because it's simple enough to add theme classes like ui-body-a to individual cells if a more heavily themed look is wanted.
-
- Row strokes
- To add horizontal lines between each row, add a custom style to your stylesheet that adds a border to the table headers and cells. In this example, RGBA is used to set a color (black) at an opacity of 5% so this will work on any background color:
-
-.table-stroke thead th {
- border-bottom: 1px solid rgba(0, 0, 0, .1);
-}
-.table-stroke tbody th,
-.table-stroke tbody td {
- border-bottom: 1px solid rgba(0, 0, 0, .05);
-}
-
- This standard table stroke style can be also applied by adding table-stroke class to the table element. If you prefer a custom stroke style, use the example above as a starting point. Note that adding styles that set a color for the stroke will override a theme class so do not use these together.
-
+
+ Row strokes and stripes
+
+ The theme CSS contains a preset row strokes and alternating row stripes style which can be applied by adding table-stroke or table-stripe class to the table element.
+
+ Note: the table-stroke and table-stripe classes are deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. The demos contain an example how to apply these styles with custom CSS.
+
1.3
@@ -79,19 +73,12 @@
The classes option is only configurable via JavaScript because it expects an object literal value.
-
+
Triggered when a table is created
@@ -103,13 +90,16 @@ $( document ).on( "mobileinit", function() {
+
+ Re-process the entire table to ensure it is displayed correctly.
+
A basic example of a reponsive table.
Textinput Widget
Creates a textinput widget for textinput, textarea or search input
Text Input
-
- Text inputs and textareas are coded with standard HTML elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device. View the data- attribute reference to see all the possible attributes you can add to text inputs.
-
+
+ Text inputs and textareas are coded with standard HTML elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device.
+
To collect standard alphanumeric text, use an input with a type="text" attribute. Set the for attribute of the label to match the id of the input 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.
-
-<label for="basic">Text Input:</label>
-<input type="text" name="name" id="basic" value="" />
-
+
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.
-
+
Mini version
-
+
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-
-
-<label for="basic">Text Input:</label>
-<input type="text" name="name" id="basic" value="" data-mini="true" />
-
+
+
This will produce an input that is not as tall as the standard version and has a smaller text size.
-
- Clear button option
- To add a clear button to any input (like the search input), add the data-clear-btn="true" attribute. The text for this clear button can be customized via the data-clear-btn-text="clear input" 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 textareas.
+ Clear button option
+ The clearButton extension provides the clearBtn option.
+ To add a clear button to any input (like the search input), add the data-clear-btn="true" attribute. The text for this clear button can be customized via the data-clear-btn-text="clear input" 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 textarea elements.
-
-<label for="clear-demo">Text Input:</label>
-<input type="text" name="clear" id="clear-demo" value="" data-clear-btn="true" />
-
+
This markup creates a text input with a clear button that becomes visible as soon as a character has been entered.
-
-
+
+
Field containers
-
- Optionally wrap the text input in a container with the data-role="fieldcontain" attribute to help visually group it in a longer form.
-
-<div data-role="fieldcontain">
- <label for="name">Text Input:</label>
- <input type="text" name="name" id="name" value="" />
-</div>
-
+
+ Optionally wrap the text input in a container with class ui-field-contain to help visually group it in a longer form.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
+
+
The text input is now displayed like this:
-
+
More text input types
In jQuery Mobile, you can use existing and new HTML5 input types such as password, email, tel, number, and more. Some type values are rendered differently across browsers. For example, Chrome renders the range input as a slider. jQuery Mobile standardizes the appearance of range and search by dynamically changing their type to text. You can configure which input types are degraded to text with the page plugin's options.
-
+
One major advantage of using these more specific input types if that on mobile devices, specialized keyboards that speed data entry are offered in place of the standard text keyboard. Try the following inputs on a mobile device to see which display custom keyboards on various platforms.
-
+
Textareas
-
- For multi-line text inputs, use a textarea element. The framework will auto-grow the height of the textarea to avoid the need for an internal scrollbar.
- Set the for attribute of the label to match the id of the textarea so they are semantically associated, and wrap them in a div with the data-role="fieldcontain" attribute to group them.
-
-<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>
-
+ For multi-line text inputs, use a textarea element. The autogrow extension provides functionality for auto-growing the height of the textarea to avoid the need for an internal scrollbar.
+ Set the for attribute of the label to match the id of the textarea so they are semantically associated, and wrap them in a div with class ui-field-contain to group them.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
+
+
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:
-
-
-<div data-role="fieldcontain">
-<label for="textarea">Textarea:</label>
- <textarea name="textarea" id="textarea"></textarea>
-</div>
-
-
+
+
+
The textarea is displayed like this and will grow to fit new lines as you type:
-
+
Calling the textinput plugin
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 data-role attribute in the markup. However, if needed, you can directly call the textinput plugin on any selector, just like any jQuery plugin:
-
-$( "input" ).textinput();
-
-
+
+
Degraded input types
-
- jQuery Mobile degrades several HTML5 input types back to type=text or type=number after adding enhanced controls. For example, inputs with a type of range are enhanced with a custom slider control, and their type is set to number to offer a usable form input alongside that slider. Inputs with a type of search are degraded back to type=text after we add our own themable search input styling.
- The page plugin contains a list of input types that are set to either true which means they'll degrade to type=text, false which means they'll be left alone, or a string such as "number", which means they'll be converted to that type (such as the case of type=range).
-
- You can configure which types are changed via the page plugin's degradeInputs option, which can be manipulated externally via $.mobile.page.prototype.options.degradeInputs, which has properties: color, date, datetime, "datetime-local", email, month, number, range, search, tel, time, url, and week. Be sure to configure this inside an event handler bound to the mobileinit event, so that it applies to the first page as well as subsequent pages that are loaded.
+
+ The location of the map of input type degradations in the page plugin is deprecated as of 1.4.0. As of 1.5.0 the input type degradation functionality will be implemented by the degradeInputs module.
+
+ jQuery Mobile degrades several HTML5 input types back to type=text or type=number after adding enhanced controls. For example, inputs with a type of range are enhanced with a custom slider control, and their type is set to number to offer a usable form input alongside that slider. Inputs with a type of search are degraded back to type=text after we add our own themeable search input styling.
+ The degradeInputs module contains a list of input types that are set to either true which means they'll degrade to type=text, false which means they'll be left alone, or a string such as "number", which means they'll be converted to that type (such as the case of type=range).
+
+ You can configure which types are changed via $.mobile.degradeInputs, which has properties: color, date, datetime, "datetime-local", email, month, number, range, search, tel, time, url, and week. Be sure to configure this inside an event handler bound to the mobileinit event, so that it applies to the first page as well as subsequent pages that are loaded.
Search Input
- Search inputs are a new HTML type that is styled with pill-shaped corners and adds an "x" icon to clear the field once you start typing. Start with an input with a type="search" attribute in your markup.
+ 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.
Set the for attribute of the label to match the id of the input 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.
-
-<label for="search-basic">Search Input:</label>
-<input type="search" name="search" id="search-basic" value="" />
-
+
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.
-
+
Mini version
-
+
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
-
-
-<label for="search-mini">Search Input:</label>
-<input type="search" name="search-mini" id="search-mini" value="" data-mini="true"/>
-
+
+
This will produce a search input that is not as tall as the standard version and has a smaller text size.
-
+
Field containers
-
- Optionally wrap the search input in a container with the data-role="fieldcontain" attribute to help visually group it in a longer form.
-
-<div data-role="fieldcontain">
- <label for="search-2">Search Input:</label>
- <input type="search" name="search-2" id="search-2" value="" />
-</div>
-
+
+ Optionally wrap the search input in a container with tlass ui-field-contain to help visually group it in a longer form.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
+
+
The search input is now displayed like this:
-
+
Theming
The data-theme attribute can be added to the search input to set the theme to any swatch letter.
-
+
Setting the clear button text
-
- The text for the button used to clear the search input of text can be configured for all search inputs by binding to the mobileinit event and setting the
- $.mobile.textinput.prototype.options.clearSearchButtonText property to a string of your choosing.
-
+
+ The text for the button used to clear the search input of text can be configured for all search inputs by binding to the mobileinit event and setting the
+ $.mobile.textinput.prototype.options.clearBtnText property to a string of your choosing.
+ This option is provided by the clearButton extension.
+
Calling the textinput plugin
This plugin will auto-initialize on any page that contains a text input with the type="search" attribute without any need for a data-role attribute in the markup. However, if needed, you can directly call the textinput plugin on a selector, just like any jQuery plugin:
-
-
-$( ".mySearchInput" ).textinput();
-
+
+
+
+ The input-based widgets in div used for creating the style. textarea elements are not wrapped in such a div.
+ In the example below, we add the attribute data-corners="false" to the input, because the class ui-corner-all is absent from the wrapper, indicating that the value of the "corners" option should be false.
+
+
1.0
-
-
- triggered when a text input is created
-
-
-
-
-
-
+
-
- enable a disabled text input.
-
-
-
- disable a text input.
+
+ Refresh a text input.
+ This method is provided by the autogrow extension, and it sets the height of the textarea element based on its contents. You should call this method when the textarea element becomes visible to make sure that its initial height matches its contents.
@@ -235,7 +253,7 @@ $( document ).on( "mobileinit", function() {
@@ -245,7 +263,7 @@ $( document ).on( "mobileinit", function() {
diff --git a/entries/theme.xml b/entries/theme.xml
new file mode 100644
index 00000000..61eb9916
--- /dev/null
+++ b/entries/theme.xml
@@ -0,0 +1,20 @@
+
+
+
+ Theme
+ jQuery Mobile Theme
+
+ Theming Concepts
+ The jQuery Mobile theme provides the CSS framework necessary for providing a consistent and touch-friendly look and feel for your widgets across platforms. It is built around the following essential concepts:
+ Swatches
+ A swatch is one of several colour schemes provided by your theme. We use single-letter designations for swatches. The default jQuery Mobile theme provides two swatches. The "a" swatch is a neutral, gray swatch, and the "b" swatch has a darker color scheme designed to contrast with the "a" swatch. You can use "b" to draw special attention to elements in a user interface styled with "a", and vice versa.
+ The ThemeRoller allows you to create any number of swatches for a custom theme.
+ Active state
+ The theme defines an "active" state separately from all the swatches. The intention is to give immediate feedback upon a user action if there should be a brief processing delay. For example, most mobile devices implement a 300ms delay between the time when the user lifts her finger from the touchscreen and the triggering of the "click" event. jQuery Mobile adds the "active" state to a button whenever the device is poised to emit a "click" event so the user receives immediate feedback that the application is committed to processing the "click" in the next 300ms.
+ Theme inheritance
+ You do not need to specify a swatch for every widget you create. Despite this, most widgets have a "theme" option set to null by default so you may override the swatch for an individual widget. The default value of null makes it sufficient to specify a swatch on the outermost container for your user interface. The swatch will then be inherited by all the widgets in the container.
+ You can override the swatch for portions of a container by specifying a theme swatch for one of its subcontainers.
Note: Because of the nature of CSS, you cannot repeatedly alternate between two swatches.
+ If you use a widget outside a jQuery Mobile page (or you don't use pages at all) and there is no themed ancestor you have to set the theme option or add the applicable theme class in your markup if you want the widget to be styled. For example, if your panel markup is outside the page and it has a listview inside, you have to set a swatch on the panel for the panel to be styled properly. However, once you set the swatch for the panel, the listview will inherit the swatch from the panel.
+
+
diff --git a/entries/throttledresize.xml b/entries/throttledresize.xml
index 4e8d4c65..3bc69378 100644
--- a/entries/throttledresize.xml
+++ b/entries/throttledresize.xml
@@ -7,7 +7,7 @@
The throttleresize event is triggered if orientationchange is not natively supported.
This event triggers when the browser window resizes from:
- - an orientation change (orientation-enabled device);
+ - an orientation change (orientation-enabled device);
- changes in dimension ratio that replicates a landspace/portrait change (resizing a desktop browser).
@@ -17,9 +17,9 @@
var count = 0;
$(function() {
/*
- Bind an event handler to window's throttledresize event that, when triggered,
+ Bind an event handler to window's throttledresize event that, when triggered,
passes a reference of itself that is accessible by the callback function.
- */
+ */
$(window).on( 'throttledresize', throttledresizeHandler );
function throttledresizeHandler( event ) {
@@ -28,12 +28,12 @@
// You can also manually force this event to fire.
$(window).trigger( "throttledresize" );
- });
+ });
]]>
Visit this from your orientation-enabled device to see it in action!
-
+
1.0
diff --git a/entries/toolbar.xml b/entries/toolbar.xml
new file mode 100644
index 00000000..d1f9ebf9
--- /dev/null
+++ b/entries/toolbar.xml
@@ -0,0 +1,436 @@
+
+
+
+ Toolbar Widget
+ Adds toolbars to the top and/or bottom of the page.
+
+ Toolbars
+ Headers and footers are elements that precede resp. succeed the page content. The
+ Headers
+ The header bar serves as the page title, is usually the first element inside each mobile page, and typically contains a page title and up to two buttons.
+ Header structure
+ The header is a
+ 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.
+
+
+
+
+ Default header features
+
+ The header data-theme attribute to the header. For example, data-theme="b". When you use external headers you must set a theme, because there is no parent page from which it can inherit a theme.
+
+ Adding buttons
+
+
+ Note: The behavior whereby anchor elements are automatically enhanced as buttons is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must add button classes if you wish to style them as buttons.
+
+
+ In the standard header configuration, there are slots for buttons on either side of the text heading. Each button is typically an a (anchor) element or a button element that has the attribute data-role="button" set. To save space, buttons in
+
+ Default button positioning
+
+ Note: The behavior whereby the first two buttons automatically get the ui-btn-left and ui-btn-right 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.
+
+ The
+
+
+
+
+
+ Making buttons visually stand out
+
+ 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 data-theme attribute and set the color swatch for the button to "b" to make the "Save" button stand out.
+
+
+
+
+
+ Controlling button position with classes
+ 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 ui-btn-left or ui-btn-right to the anchor.
+
+
+
+
+
+ Adding buttons to
+ 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 class="ui-title" so that the bar can get the height and display correctly.
+
+
+
+
+
+ Adding Back buttons
+
+
+ Note: The options addBackBtn, backBtnTheme, and backBtnText have moved from the page widget to the
+
+ jQuery Mobile has a feature to automatically create and append "back" buttons to any header, though it is disabled by default. This is primarily useful in chromeless installed applications, such as those running in a native app webview. The framework automatically generates a "back" button on a header when the addBackBtn option is true. This can also be set via markup if the header div has a data-add-back-btn="true" attribute.
+ If you use the attribute data-rel="back" on an anchor, any clicks on that anchor will mimic the back button, going back one history entry and ignoring the anchor's default href. This is particularly useful when linking back to a named page, such as a link that says "home", or when generating "back" buttons with JavaScript, such as a button to close a dialog. When using this feature in your source markup, be sure to provide a meaningful href that actually points to the URL of the referring page. This will allow the feature to work for users in C-Grade browsers.
+ If you just want a reverse transition without actually going back in history, you should use the data-direction="reverse" attribute.
+
+ Customizing the back button text
+ If you'd like to configure the back button text, you can either use the data-back-btn-text="previous" attribute on your
$.mobile.
+
+ Default back button style
+ If you'd like to configure the back button role-theme, you can use:
$.mobile.
+If you're doing this programmatically, set this option inside the mobileinit event handler.
+
+ Custom header configurations
+ 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 div. 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.
+ 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 ui-bar class to apply standard bar padding and add the ui-bar-b class to assign the bar swatch styles from your theme. (The "b" can be any swatch letter.)
+
+
+
+
+
+ Note that .ui-bar should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width
+ By writing some simple styles, it's easy to build message bars like this:
+
+
+
+ Footers
+ The footer bar is usually the last element inside each mobile page, and tends to be more freeform than the header in terms of content and functionality, but typically contains a combination of text and buttons.
+
+ Footer bar structure
+ The footer bar has the same basic structure as the header except it uses the data-role attribute value of footer.
+
+
+
+
+ The footer data-theme attribute to the header. For example, data-theme="b". When you use external headers you must set a theme, because there is no parent page from which it can inherit a theme.
+
+ The page footer is very similar to the header in terms of options and configuration. The primary difference is that the footer is designed to be less structured than the header to allow more flexibility, so the framework doesn't automatically reserve slots for buttons to the left or right as it does in headers.
+ Since footers do not have the same prescriptive markup conventions as headers, we recommend using layout grids or writing custom styles to achieve the design you want.
+
+ Adding buttons
+
+ Note: The behavior whereby anchor elements are automatically enhanced as buttons is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must set the attribute data-role="button" on those anchors you wish the framework to enhance as buttons.
+
+
+ Any link or valid button markup with a data-role="button" attribute added to the footer will automatically be turned into a button. To save space, buttons in
+ By default, class="ui-bar" to the footer.
+
+
+
+ This creates this
+
+ Note that .ui-bar should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width
+
+ To group buttons together into a button set, wrap the links in a wrapper with data-role="controlgroup" and data-type="horizontal" attributes.
+
+
+
+ This creates a grouped set of buttons:
+
+
+ Adding form elements
+ Form elements and other content can also be added to toolbars. Here is an example of a select menu inside a footer bar. We recommend using mini-sized form elements in toolbars by adding the data-mini="true" attribute:
+
+
+
+ Fixed & Persistent footers
+ In situations where the footer is a global navigation element, you may want it to appear fixed so it doesn't scroll out of view. It's also possible to make a fixed toolbar persistent so it appears to not move between page transitions. This can be accomplished by using the persistent footer feature included in jQuery Mobile.
+ To make a footer persistent between transitions, add the data-id attribute to the footer of all relevant pages and use the same id value for each. For example, by adding data-id="myfooter" to the current page and the target page, the framework will keep the footer anchors in the same spot during the page animation. This effect will only work correctly if the header and footer toolbars are set to data-position="fixed" so they are in view during the transition.
+
+ Fixed toolbars
+ In browsers that support CSS position: fixed (most desktop browsers, iOS5+, Android 2.2+, BlackBerry 6, and others),
+
+ To enable this behavior on a header or footer, add the data-position="fixed" attribute to a jQuery Mobile
+
+ Fixed header markup example:
+
+
+ Fixed footer markup example:
+
+
+
+
+ Note: When you dynamically inject a fixed toolbar into the active page, you must afterwards call $.mobile.resetActivePageHeight(); to ensure that the page height remains correct. An example illustrates this.
+
+ Fullscreen Toolbars
+
+ Fullscreen fixed toolbars sit on top of the content at all times when they are visible, and unlike regular fixed toolbars, fullscreen toolbars do not fall back to static positioning when toggled. Instead they disappear from the screen entirely. Fullscreen toolbars are ideal for more immersive interfaces, like a photo viewer that is meant to fill the entire screen with the photo itself and no distractions.
+
+ To enable this option on a fixed header or footer, add the data-fullscreen attribute to the element.
+
+
+
+
+ Forms in toolbars
+ While all form elements are now tested to work correctly within static toolbars as of jQuery Mobile 1.1, we recommend extensive testing when using form elements within fixed toolbars or within any position: fixed elements. This can potentially trigger a number of unpredictable issues in various mobile browsers, Android 2.2/2.3 in particular (detailed in Known issues in Android 2.2/2.3, below).
+
+ Changes in jQuery Mobile 1.1
+ Prior to version 1.1, jQuery Mobile used dynamically re-positioned toolbars for the fixed header effect because very few mobile browsers supported the position:fixed CSS property, and simulating fixed support through the use of "fake" JavaScript overflow-scrolling behavior would have reduced our browser support reach, in addition to feeling unnatural on certain platforms. This behavior was not ideal, and jQuery Mobile 1.1 took a new approach to fixed toolbars that allows much broader support. The framework now offers true fixed toolbars on many popular platforms, while gracefully degrading non-supporting platforms to static positioning.
+
+ Polyfilling older platforms
+ The fixed toolbar plugin degrades gracefully on platforms that do not support CSS position:fixed properly, such as iOS4.3. If you still need to support fixed toolbars on that platform (with the show/hide behavior) included in previous releases, Filament Group has developed a polyfill that you can use.
+
+
+ - Github code repository with CSS, and JavaScript required for the fixed toolbars polyfill
+ - Preview URL using the code in the repo above
+
+
+ Just include the CSS and JS files after your references to jQuery Mobile and Fixed toolbars will work similarly to jQuery Mobile 1.0 on iOS4.3, with the inclusion of the new API for the 1.1 fixedtoolbar plugin.
+
+ If you have any improvements to suggest, fork the gist on github and let us know!
+
+ Known issue with form controls inside fixed toolbars, and programmatic scroll
+ An obscure issue exists in iOS5 and some Android platforms where form controls placed inside fixed-positioned containers can lose their hit area when the window is programatically scrolled (using window.scrollTo for example). This is not an issue specific to jQuery Mobile, but because of it, we recommend not programatically scrolling a document when using form controls inside jQuery Mobile fixed toolbars. This ticket from the Device Bugs project tracker explains this problem in more detail.
+
+ Known issues in Android 2.2/2.3
+ Android 2.2/2.3's implementation of position: fixed; can, in conjunction with seemingly unrelated styles and markup patterns, cause a number of strange issues, particularly in the case of position: absolute elements inside of position: fixed elements. While we've done our best to work around a number of these unique bugs within the scope of the library, custom styles may cause a number of issues.
+
+ - Form elements elsewhere on the page—select menus in particular—can fail to respond to user interaction when an empty absolute positioned element is placed within a fixed position element. In rare cases—and specific to Android 2.2—this can cause entire pages to fail to respond to user interaction. This can seemingly be solved by adding any character to the absolute positioned element, including a non-breaking space, and in some cases even whitespace.
+ - The above-described issue can also be triggered by an absolute positioned image inside of a fixed position element, but only when that image is using something other than its inherent dimensions. If a height or width is specified on the image using CSS, or the image src is invalid (thus having no inherent height and width), this issue can occur. If an image that is inherently, say, 50x50 pixels is placed in a fixed element and left at its inherent dimensions, this issue does not seem to occur.
+ - When a
position: fixed element appears anywhere on a page, most 2D CSS transforms will fail. Oddly, only translate transforms seem unaffected by this. Even more oddly, this issue is solved by setting a CSS opacity of .9 or below on the parent of the fixed element.
+ - Combinations of
position: fixed and overflow properties are best avoided, as both have been known to cause unpredictable issues in older versions of Android OS.
+ - Any element that triggers the on-screen keyboard, when placed inside a
position: fixed element, will fail to respond to user input when using anything other than the default keyboard. This includes Swype, XT9 or, it seems, any input method apart from the standard non-predictive keyboard.
+
+
+ While we will continue to try to find ways to mitigate these bugs as best we can, we currently advise against implementing fixed toolbars containing complicated user styles and form elements without extensive testing in all versions of Android's native browser.
+
+ No longer supported: touchOverflowEnabled
+ Prior to jQuery Mobile 1.1, true fixed toolbar support was contingent on native browser support for the CSS property overflow-scrolling: touch, which is currently only supported in iOS5. As of version 1.1, jQuery Mobile no longer uses this CSS property at all. We've removed all internal usage of this property in the framework, but we've left it defined globally on the $.mobile object to reduce the risk that its removal will cause trouble with existing applications. This property is flagged for removal, so please update your code to no longer use it. The support test for this property, however, remains defined under $.support and we have no plans to remove that test at this time.
+
+
+ 1.4
+
+
+
+
+
+
+
+
+
+ Update the If you manipulate a refresh method on it to update the visual styling.
+
+
+
+
+ Sets the top and bottom padding for the content element of the page to the height of the
+
+
+ Optional: The page containing the
+
+
+
+
+ A basic example of a header
+
+
+
+ A basic example of a page with fixed toolbars.
+
+
+
+ Injecting a fixed toolbar
+
+
+
diff --git a/entries/updatelayout.xml b/entries/updatelayout.xml
index a6970062..718be1b7 100644
--- a/entries/updatelayout.xml
+++ b/entries/updatelayout.xml
@@ -7,11 +7,11 @@
This event is triggered by components within the framework that dynamically show/hide content, and is meant as a generic mechanism to notify other components that they may need to update their size or position. Within the framework, this event is fired on the component element whose content was shown/hidden, and bubbles all the way up to the document element.
$( "#foo" ).hide().trigger( "updatelayout" );
-
+
1.0
-
+
+ <link rel="stylesheet" href="http://code.jquery.com/mobile/git/jquery.mobile-git.min.css">
+ <script src="http://code.jquery.com/jquery-1.10.2.min.js"></script>
+ <script src="http://code.jquery.com/mobile/git/jquery.mobile-git.min.js"></script>
<style>
</head>
<body>
diff --git a/grunt.js b/grunt.js
index cd4af15f..30e82dc7 100644
--- a/grunt.js
+++ b/grunt.js
@@ -38,7 +38,7 @@ grunt.initConfig({
watch: {
scripts: {
files: 'entries/*.xml',
- tasks: ['build'],
+ tasks: ['wordpress-deploy'],
options: {
interrupt: true
}
diff --git a/includes/core-extension-desc.xml b/includes/core-extension-desc.xml
new file mode 100644
index 00000000..7eec109c
--- /dev/null
+++ b/includes/core-extension-desc.xml
@@ -0,0 +1,2 @@
+
+This plugin extends jQuery's built-in . method may not fail directly, as the method still exists. However, the expected behavior will not occur.
diff --git a/includes/pre-rendered-common.xml b/includes/pre-rendered-common.xml
new file mode 100644
index 00000000..03fc3139
--- /dev/null
+++ b/includes/pre-rendered-common.xml
@@ -0,0 +1,7 @@
+
+
+ Providing pre-rendered markup
+ You can improve the load time of your page by providing the markup that the
+ By providing this markup yourself, and by indicating that you have done so by setting the attribute data-enhanced="true", you instruct the
+ When you provide such pre-rendered markup you must also set all the classes that the framework would normally set, and you must also set all data attributes whose values differ from the default to indicate that the pre-rendered markup reflects the non-default value of the corresponding widget option.
+
diff --git a/includes/widget-event-create.xml b/includes/widget-event-create.xml
new file mode 100644
index 00000000..9f3c08f2
--- /dev/null
+++ b/includes/widget-event-create.xml
@@ -0,0 +1,8 @@
+
+
+
+ Triggered when the
+
diff --git a/includes/widget-method-destroy.xml b/includes/widget-method-destroy.xml
new file mode 100644
index 00000000..344a979d
--- /dev/null
+++ b/includes/widget-method-destroy.xml
@@ -0,0 +1,6 @@
+
+
+
+ Removes the
+
diff --git a/includes/widget-method-disable.xml b/includes/widget-method-disable.xml
new file mode 100644
index 00000000..e2828b40
--- /dev/null
+++ b/includes/widget-method-disable.xml
@@ -0,0 +1,6 @@
+
+
+
+ Disables the
+
diff --git a/includes/widget-method-enable.xml b/includes/widget-method-enable.xml
new file mode 100644
index 00000000..0b1b650a
--- /dev/null
+++ b/includes/widget-method-enable.xml
@@ -0,0 +1,6 @@
+
+
+
+ Enables the
+
diff --git a/includes/widget-method-option.xml b/includes/widget-method-option.xml
new file mode 100644
index 00000000..b9652f52
--- /dev/null
+++ b/includes/widget-method-option.xml
@@ -0,0 +1,30 @@
+
+
+
+ Sets one or more options for the
+
+ Gets the value currently associated with the specified optionName.
+
+ The name of the option to get.
+
+
+
+ Gets an object containing key/value pairs representing the current
+
+
+ Sets the value of the optionName.
+
+ The name of the option to set.
+
+
+ A value to set for the option.
+
+
+
+ Sets one or more options for the
+
+ A map of option-value pairs to set.
+
+
+
diff --git a/includes/widget-method-widget.xml b/includes/widget-method-widget.xml
new file mode 100644
index 00000000..2a90c32c
--- /dev/null
+++ b/includes/widget-method-widget.xml
@@ -0,0 +1,6 @@
+
+
+
+ Returns a jQuery object containing the
+
diff --git a/includes/widget-option-defaults.xml b/includes/widget-option-defaults.xml
new file mode 100644
index 00000000..56b0b7a5
--- /dev/null
+++ b/includes/widget-option-defaults.xml
@@ -0,0 +1,8 @@
+
+
diff --git a/includes/widget-option-disabled.xml b/includes/widget-option-disabled.xml
new file mode 100644
index 00000000..07b4e337
--- /dev/null
+++ b/includes/widget-option-disabled.xml
@@ -0,0 +1,8 @@
+
+
diff --git a/includes/widget-option-enhanced.xml b/includes/widget-option-enhanced.xml
new file mode 100644
index 00000000..939e5754
--- /dev/null
+++ b/includes/widget-option-enhanced.xml
@@ -0,0 +1,7 @@
+
+
diff --git a/includes/widget-option-initSelector.xml b/includes/widget-option-initSelector.xml
new file mode 100644
index 00000000..428f8f13
--- /dev/null
+++ b/includes/widget-option-initSelector.xml
@@ -0,0 +1,19 @@
+
+
diff --git a/includes/widget-option-mini.xml b/includes/widget-option-mini.xml
new file mode 100644
index 00000000..6a9e1336
--- /dev/null
+++ b/includes/widget-option-mini.xml
@@ -0,0 +1,7 @@
+
+
diff --git a/includes/widget-option-theme.xml b/includes/widget-option-theme.xml
new file mode 100644
index 00000000..45d048a4
--- /dev/null
+++ b/includes/widget-option-theme.xml
@@ -0,0 +1,9 @@
+
+
diff --git a/package.json b/package.json
index 6151cbf2..cadbd30f 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
"grunt": "0.3.17",
"grunt-clean": "0.3.0",
"grunt-wordpress": "1.0.7",
- "grunt-jquery-content": "0.9.0",
+ "grunt-jquery-content": "0.10.7",
"grunt-check-modules": "0.1.0",
"grunt-contrib-watch": "0.1.4"
},
diff --git a/pages/data-attribute.html b/pages/data-attribute.html
index 7c77747e..94db83ac 100644
--- a/pages/data-attribute.html
+++ b/pages/data-attribute.html
@@ -18,7 +18,7 @@ Button
data-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
data-iconpos
@@ -45,7 +45,6 @@ Button
swatch letter (a-z)
-Multiple buttons can be wrapped in a container with a data-role="controlgroup" attribute for a vertically grouped set. Add the data-type="horizontal" attribute for the buttons to sit side-by-side. Add the data-mini="true" to get the mini/compact sized version for all the buttons that appear in the controlgroup.
Checkbox
Pairs of labels and inputs with type="checkbox" are auto-enhanced, no data-role required
@@ -63,7 +62,6 @@ Checkbox
swatch letter (a-z) - Added to the form element
-Multiple checkboxes can be wrapped in a container with a data-role="controlgroup" attribute for a vertically grouped set. Add the data-type="horizontal" attribute for the checkboxes to sit side-by-side. Add the data-mini="true" to get the mini/compact sized version for all the checkboxes that appear in the controlgroup.
Collapsible
A heading and content wrapped in a container with the data-role="collapsible"
@@ -74,7 +72,7 @@ Collapsible
data-collapsed-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search | false
data-content-theme
@@ -82,7 +80,7 @@ Collapsible
data-expanded-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b| check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
data-iconpos
@@ -108,7 +106,7 @@ Collapsible set
data-collapsed-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b| check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
data-content-theme
@@ -116,7 +114,7 @@ Collapsible set
data-expanded-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b| check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
data-iconpos
@@ -137,23 +135,32 @@ Collapsible set
-Content
+Content
+Deprecated as of 1.4.0 and will be removed in 1.5.0.
Container with data-role="content"
data-theme
- swatch letter (a-z)
+ Deprecated as of 1.4.0 and will be removed in 1.5.0. swatch letter (a-z)
Controlgroup
-DIV or FIELDSET container with data-role="controlgroup". Visually integrate multiple button-styled inputs of a single type (checkboxes, link-based buttons, radio buttons, selects) into a group. For grouping form checkboxes and radio buttons, the fieldset container is recommended inside a div container with the data-role="fieldcontain", to improve label styling.
+DIV or FIELDSET container with data-role="controlgroup". Visually integrate multiple button-styled elements.
+
+ data-exclude-invisible
+ true | false - Sets whether to exclude invisible children in the assignment of rounded corners
+
data-mini
true | false - Compact sized version for all items in the controlgroup
+
+ data-theme
+ swatch letter (a-z)
+
data-type
horizontal | vertical - For horizontal or vertical item alignment
@@ -211,38 +218,9 @@ Enhancement
Any link or form element inside data-ajax="false" containers will be ignored by the framework's navigation functionality when $.mobile.ignoreContentEnabled is set to true.
-Field container
+Field container
Container with data-role="fieldcontain" wrapped around label/form element pair
-
-Fixed Toolbar
-Container with data-role="header" or data-role="footer" plus the attribute data-position="fixed"
-
-
- data-disable-page-zoom
- true | false - User-scaling-ability for pages with fixed toolbars
-
-
- data-fullscreen
- true | false - Setting toolbars over the page-content
-
-
- data-tap-toggle
- true | false - Ability to toggle toolbar-visibility on user tap/click
-
-
- data-transition
- slide | fade | none - Show/hide-transition when a tap/click occurs
-
-
- data-update-page-padding
- true | false - Have the page top and bottom padding updated on resize, transition, "updatelayout" events (the framework always updates the padding on the "pageshow" event).
-
-
- data-visible-on-page-show
- true | false - Toolbar-visibility when parent page is shown
-
-
-
+Note: data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
Flip toggle switch
Select with data-role="slider" and two option element
@@ -266,51 +244,7 @@ Flip toggle switch
-Footer
-Container with data-role="footer"
-
-
- data-id
- string - Unique ID. Required for persistent footers
-
-
- data-position
- fixed
-
-
- data-fullscreen
- true | false - Used in conjunction with fixed toolbars
-
-
- data-theme
- swatch letter (a-z)
-
-
-
-
-Header
-Container with data-role="header"
-
-
- data-id
- string - Unique ID. Required for persistent headers
-
-
- data-position
- fixed
-
-
- data-fullscreen
- true | false - Used in conjunction with fixed toolbars
-
-
- data-theme
- swatch letter (a-z)
-
-
-
-
-Link
+Link
Links, including those with a data-role="button", and form submit buttons share these attributes
@@ -383,7 +317,7 @@ Listview
data-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search | false
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b| check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search | false
data-inset
@@ -391,7 +325,7 @@ Listview
data-split-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b| check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search
data-split-theme
@@ -413,7 +347,7 @@ Listview item
data-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search | false
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b| check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search | false
data-role
@@ -426,7 +360,7 @@ Listview item
The data-icon attribute is only applicable for a listview item if it contains a link.
-Navbar
+Navbar
A number of LIs wrapped in a container with data-role="navbar"
@@ -437,40 +371,20 @@ Navbar
To add icons to the navbar items, the data-icon attribute is used, specifying a standard mobile icon for each item.
Navbars inherit the theme-swatch from their parent container. Setting the data-theme attribute to a navbar is not supported. The data-theme attribute can be set individually to the links inside a navbar.
-Page
+Page
Container with data-role="page"
-
- data-add-back-btn
- true | false - Auto add back button, header only
-
-
- data-back-btn-text
- string
-
-
- data-back-btn-theme
- swatch letter (a-z)
-
-
- data-close-btn-text
- string - Text for the close button, dialog only
-
data-dom-cache
true | false
-
- data-fullscreen
- true | false - Used in conjunction with fixed toolbars Deprecated in 1.1 - use on header and footer instead.
-
data-overlay-theme
- swatch letter (a-z) - Overlay theme when the page is opened in a dialog
+ swatch letter (a-z) - Overlay theme when the page is opened as a dialog
data-theme
- swatch letter (a-z) - Default "c"
+ swatch letter (a-z) - Default "a"
data-title
@@ -547,9 +461,8 @@ Radio button
swatch letter (a-z) - Added to the form element
- Multiple radion buttons can be wrapped in a container with a data-role="controlgroup" attribute for a vertically grouped set. Add the data-type="horizontal" attribute for the radio buttons to sit side-by-side. Add the data-mini="true" to get the mini/compact sized version for all the radio buttons that appear in the controlgroup.
-Select
+Selectmenu
All select form elements are auto-enhanced, no data-role required
@@ -558,7 +471,7 @@ Select
data-icon
- home | delete | plus | arrow-u | arrow-d | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search | false
+ home | delete | plus | arrow-u | arrow-d | carat-l | carat-t | carat-r | carat-b | check | gear | grid | star | custom | arrow-r | arrow-l | minus | refresh | forward | back | alert | info | search | false
data-iconpos
@@ -593,9 +506,8 @@ Select
swatch letter (a-z) - Added to the form element
-Multiple selects can be wrapped in a fieldset with a data-role="controlgroup" attribute for a vertically grouped set. Add the data-type="horizontal" attribute for the selects to sit side-by-side.
-Slider
+Slider
Inputs with type="range" are auto-enhanced, no data-role required
@@ -621,7 +533,7 @@ Slider
-Text input & Textarea
+Textinput
Input type="text|number|search|etc." or textarea elements are auto-enhanced, no data-role required
@@ -645,3 +557,63 @@ Text input & Textarea
swatch letter (a-z) - Added to the form element
+
+
+Toolbar
+Container with data-role="header" or data-role="footer"
+
+
+ data-add-back-btn
+ true | false - Auto add back button, header only
+
+
+ data-back-btn-text
+ string - Header only
+
+
+ data-back-btn-theme
+ swatch letter (a-z) - Header only
+
+
+ data-id
+ string - Unique ID. Required for persistent footers
+
+
+ data-position
+ fixed
+
+
+ data-theme
+ swatch letter (a-z)
+
+
+
+
+Fixed toolbar
+Container with data-role="header" or data-role="footer" plus the attribute data-position="fixed"
+
+
+ data-disable-page-zoom
+ true | false - User-scaling-ability for pages with fixed toolbars
+
+
+ data-fullscreen
+ true | false - Setting toolbars over the page-content
+
+
+ data-tap-toggle
+ true | false - Ability to toggle toolbar-visibility on user tap/click
+
+
+ data-transition
+ slide | fade | none - Show/hide-transition when a tap/click occurs
+
+
+ data-update-page-padding
+ true | false - Have the page top and bottom padding updated on resize, transition, "updatelayout" events (the framework always updates the padding on the "pageshow" event).
+
+
+ data-visible-on-page-show
+ true | false - Toolbar-visibility when parent page is shown
+
+
diff --git a/pages/global-config.html b/pages/global-config.html
index 9f8c011a..647cc4f5 100644
--- a/pages/global-config.html
+++ b/pages/global-config.html
@@ -14,7 +14,7 @@ The mobileinit event
-$(document).on("mobileinit", function(){
+$( document ).on( "mobileinit", function() {
//apply overrides here
});
@@ -34,8 +34,8 @@ The mobileinit event
-$(document).on("mobileinit", function(){
- $.extend( $.mobile , {
+$( document ).on( "mobileinit", function() {
+ $.extend( $.mobile , {
foo: bar
});
});
@@ -45,7 +45,7 @@ The mobileinit event
Alternatively, you can set them using object property notation.
-$(document).on("mobileinit", function(){
+$( document ).on( "mobileinit", function() {
$.mobile.foo = bar;
});
@@ -57,73 +57,103 @@ Configurable options
The following defaults are configurable via the $.mobile object:
- activeBtnClass string, default: "ui-btn-active"- The CSS class used for "active" button state.
+ activeBtnClass string, default: "ui-btn-active"- The CSS class used for "active" button state.Deprecated in 1.4 and will be removed in 1.5. The class "ui-btn-active" will continue to be applied to elements as before.
- activePageClass string, default: "ui-page-active"- The CSS class used for the page currently in view or in a transition.
+ activePageClass string, default: "ui-page-active"- The CSS class used for the page currently in view or in a transition.Deprecated in 1.4 and will be removed in 1.5. The class "ui-page-active" will continue to be applied to elements as before.
- ajaxEnabled boolean, default: trueajaxEnabled boolean, default: true- jQuery Mobile will automatically handle link clicks and form submissions through Ajax, when possible. If false, URL hash listening will be disabled as well, and URLs will load as ordinary HTTP requests.
- allowCrossDomainPages boolean, default: falseallowCrossDomainPages boolean, default: false- When jQuery Mobile attempts to load an external page, the request runs through
$.mobile.loadPage(). This will only allow cross-domain requests if $.mobile.allowCrossDomainPages is set to true. Because the jQuery Mobile framework tracks what page is being viewed within the browser's location hash, it is possible for a cross-site scripting (XSS) attack to occur if the XSS code in question can manipulate the hash and set it to a cross-domain URL of its choice. This is the main reason that the default setting for $.mobile.allowCrossDomainPages is set to false. In PhoneGap apps that must "phone home" by loading assets off a remote server, both the $.support.cors AND $.mobile.allowCrossDomainPages must be set to true.
- autoInitializePage boolean, default: trueautoInitializePage boolean, default: true- When the DOM is ready, the framework should automatically call
$.mobile.initializePage. If false, the page will not initialize and will be visually hidden until $.mobile.initializePage is manually called.
- buttonMarkup.hoverDelay integer, default: 200- Set the delay for touch devices to add the hover and down classes on touch interactions for buttons throughout the framework. Reducing the delay here results in a more responsive feeling ui, but will often result in the downstate being applied during page scrolling.
+
+ - Set the delay for touch devices to add the hover and down classes on touch interactions for buttons throughout the framework. Reducing the delay here results in a more responsive feeling ui, but will often result in the downstate being applied during page scrolling.
+ Deprecated in 1.4 - use
$.mobile.hoverDelay instead.
- defaultDialogTransition string, default: 'pop'- Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions.
+ defaultDialogTransition string, default: 'pop'- Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions.
+ Deprecated in 1.4.
+
When using pages styled as dialogs (data-role="page" data-dialog="true"), if you wish for them to have a different transition than regular pages, you must specify the transition on the link that opens them by adding the attribute data-transition="pop" to the link. "pop" is just an example. You may specify any transition you wish, such as "slide", "flip", or "none".
+
Similarly, when calling the pagecontainer's change() method, you must also specify the transition explicitly, if you wish it to be different from the $.mobile.defaultPageTransition:
+
+$( ":mobile-pagecontainer" )
+ .pagecontainer( "change", "dialog.html", { transition: "pop" } );
+
+
+
- defaultPageTransition string, default: 'fade'defaultPageTransition string, default: 'fade'- Set the default transition for page changes that use Ajax. Note: default changed from 'slide' to 'fade' in 1.1. Set to 'none' for no transitions.
- dynamicBaseEnabled boolean, default: truedegradeInputs object- This setting influences the default behaviour of the function $.mobile.degradeInputsWithin(). It specifies how inputs are to be degraded. Each property is the name of an input type, and the property's value is either
false, meaning to leave inputs of the given type untouched, or a string giving an alternative input type into which elements of the given input type should be converted. By default, only input elements of type "range" and of type "search" are degraded:
+
+ "color", default: false- The input type to which to convert
input elements of type "color".
+ "date", default: false- The input type to which to convert
input elements of type "date".
+ "datetime", default: false- The input type to which to convert
input elements of type "datetime".
+ "datetime-local", default: false- The input type to which to convert
input elements of type "datetime-local".
+ "email", default: false- The input type to which to convert
input elements of type "email".
+ "month", default: false- The input type to which to convert
input elements of type "month".
+ "number", default: false- The input type to which to convert
input elements of type "number".
+ "range", default: "number"- The input type to which to convert
input elements of type "range".
+ "search", default: "text"- The input type to which to convert
input elements of type "search".
+ "tel", default: false- The input type to which to convert
input elements of type "tel".
+ "time", default: false- The input type to which to convert
input elements of type "time".
+ "url", default: false- The input type to which to convert
input elements of type "url".
+ "week", default: false- The input type to which to convert
input elements of type "week".
+
+
+
+ dynamicBaseEnabled boolean, default: true- When this property is set to
false the base tag value in browsers that support a dynamic base tag and URL prefixes in browsers that don't won't be updated to reflect where the page was loaded from. This means that resource references that are relative to the page on which they are defined may break. This option is available for web frameworks that operate under a universal base tag value where all links and assets are relative to a signal base.
- getMaxScrollForTransition integer, default: 3focusClass string, default: "ui-focus"- The CSS class used for "active" button state.Deprecated in 1.4 and will be removed in 1.5. The class "ui-focus" will continue to be applied to elements as before.
+
+ getMaxScrollForTransition integer, default: 3- Set a scroll position breakpoint for transitions. If the scroll position is greater than the window height multiplied by the value that has been set, transition "none" will be used.
- gradeA function that returns a boolean, default: a function returning the value of $.support.mediaquerygradeA function that returns a boolean, default: a function returning the value of $.support.mediaquery- Any support conditions that must be met in order to proceed.
- hashListeningEnabled boolean, default: truehashListeningEnabled boolean, default: true- jQuery Mobile will automatically listen and handle changes to the location.hash. Disabling this will prevent jQuery Mobile from handling hash changes, which allows you to handle them yourself or use simple deep-links within a document that scroll to a particular id.
- ignoreContentEnabled boolean, default: falseignoreContentEnabled boolean, default: false- Warning: Setting this property to true will cause performance degradation on enhancement. Once set, all automatic enhancements made by the framework to each enhanceable element of the user's markup will first check for a
data-enhance=false parent node. If one is found the markup will be ignored. This setting and the accompanying data attribute provide a mechanism through which users can prevent enhancement over large sections of markup.
- linkBindingEnabled boolean, default: truekeepNative Selector, default: ":jqmData(role='none'), :jqmData(role='nojs')"- Elements matching the selector specified in this option will never be enhanced. This is different from ignoreContentEnabled because it does not affect the children of elements that match this selector.
+
+ linkBindingEnabled boolean, default: true- jQuery Mobile will automatically bind the clicks on anchor tags in your document. Setting this option to false will prevent all anchor click handling including the addition of active button state and alternate link bluring. This should only be used when attempting to delegate the click management to another library or custom code.
- loadingMessage string, default: "loading"-
- Set the text that appears when a page is loading. If set to false, the message will not appear at all.
- Deprecated in 1.2 - use
$.mobile.loader.prototype.options.text instead. See the loader docs for more.
-
-
- loadingMessageTextVisible boolean, default: false-
- Whether the text should be visible when a loading message is shown. The text is always visible for loading errors.
- Deprecated in 1.2 - use
$.mobile.loader.prototype.options.textVisible instead. See the loader docs for more.
-
-
- loadingMessageTheme string, default: "a"-
- The theme that the loading message box uses when text is visible.
- Deprecated in 1.2 - use
$.mobile.loader.prototype.options.theme instead. See the loader docs for more.
-
-
- maxTransitionWidth integer, boolean, default: falsemaxTransitionWidth integer, boolean, default: false- Set a max width for transitions. The option accepts any number representing a pixel width and its default value
false. If a number value is set, transition "none" will be used if the window is wider than the specified value.
- minScrollBack integer, default: 250- Minimum scroll distance that will be remembered when returning to a page.
+ minScrollBack integer, default: 0- Minimum scroll distance that will be remembered when returning to a page.Deprecated in 1.4 and will be removed in 1.5. Any and all scrolling will be remembered. This matches native behavior. The old default value of 250 has changed to 0 during the deprecation period.
- ns string, default: ""ns string, default: ""- The namespace used in data attributes (e.g., data-role). Can be set to any string, including a blank string which is the default. When using, it's clearest if you include a trailing dash, such as "mynamespace-" which maps to
data-mynamespace-foo="...".
If you use data- namespacing, you will need to update/override one selector in the theme CSS. The following data selectors should incorporate the namespace you're using:
@@ -132,28 +162,22 @@ Configurable options
- pageLoadErrorMessage string, default: "Error Loading Page"pageLoadErrorMessage string, default: "Error Loading Page"- Set the text that appears when a page fails to load through Ajax.
- pageLoadErrorMessageTheme string, default: "e"pageLoadErrorMessageTheme string, default: "e"- Set the theme that the error message box uses.
- phonegapNavigationEnabled boolean, default: false- Replace calls to
window.history.back with PhoneGap's navigation helper where it is available. This addresses navigation issues on page refresh in Android PhoneGap applications using jQuery Mobile.
- pushStateEnabled boolean, default: truepushStateEnabled boolean, default: true- Enhancement to use
history.replaceState in supported browsers, to convert the hash-based Ajax URL into the full document path. Note that we recommend disabling this feature if Ajax is disabled or if external links are used extensively.
- subPageUrlKey string, default: "ui-page"- The url parameter used for referencing widget-generated sub-pages (such as those generated by nested listviews). Translates to example.html&ui-page=subpageIdentifier. The hash segment before &ui-page= is used by the framework for making an Ajax request to the URL where the sub-page exists.
+ subPageUrlKey string, default: "ui-page"- The url parameter used for referencing widget-generated sub-pages (such as those generated by nested listviews). Translates to example.html&ui-page=subpageIdentifier. The hash segment before &ui-page= is used by the framework for making an Ajax request to the URL where the sub-page exists.
+ Deprecated in 1.4 since this option only affects nested listviews, which have been removed.
- touchOverflowEnabled boolean, default: false-
- Enable smoother page transitions and true fixed toolbars in devices that support both the
overflow: and overflow-scrolling: touch; CSS properties.
- Deprecated in 1.1.0
-
-
- transitionFallbacks.[transition] string, default: "fade"transitionFallbacks.[transition] string, default: "fade"- Set the fallback transition for browsers that don't support 3D transforms for a specific transition type.
-
diff --git a/pages/icons.html b/pages/icons.html
new file mode 100644
index 00000000..b86dd7e9
--- /dev/null
+++ b/pages/icons.html
@@ -0,0 +1,28 @@
+
+
+
+Icons
+
+jQuery Mobile provides a number of icons that can be used by applying a data-icon attribute or a ui-icon- class to a suitable widget.
+There is an SVG and PNG image of each icon. By default the SVG icons, that look great on both SD and HD screens, are used. On platforms that don't support SVG the framework falls back to PNG icons. The icon name is self-describing. For example, the following will display a button with a home icon:
+
+
+Home
+
+
+
+The following is a full list of the icons provided:
+
+
+
+Icons and themes
+The semi-transparent black circle behind the white icon ensures good contrast on any background color so it works well with the jQuery Mobile theming system. Here are examples of the same icons sitting on top of a range of different color swatches with themed buttons.
+
+
+
diff --git a/pages/index.html b/pages/index.html
index 254a449e..46f7a642 100644
--- a/pages/index.html
+++ b/pages/index.html
@@ -1,5 +1,5 @@
jQuery Mobile is the easiest way to build sites and apps that are accessible on all popular smartphone, tablet and desktop devices.
@@ -10,9 +10,9 @@
You can contribute to the project by reporting issues, suggesting new features, or submitting pull requests. Please read our Contributing Guidelines before submitting.
-This site provides API documentation for jQuery Mobile 1.3.0 final.
+This site provides API documentation for jQuery Mobile 1.4.
-jQuery Mobile 1.3.0 supports jQuery 1.7.0 to 1.9.1
+jQuery Mobile 1.4 supports jQuery 1.8 to 1.10 and 2.0
@@ -21,8 +21,7 @@ Can't find what you're looking for?
Perhaps one of the following sites will help:
-- jQuery Mobile Demo Center
-- jQuery Mobile 1.2.0 Documentation
+- jQuery Mobile 1.4 Demos
- jQuery Core API Documentation
- jQuery UI API Documentation
- jQuery Learning Center
diff --git a/pages/tabs.html b/pages/tabs.html
new file mode 100644
index 00000000..2e0ac3c7
--- /dev/null
+++ b/pages/tabs.html
@@ -0,0 +1,10 @@
+
+
+This widget is imported unchanged from jQuery UI. Nevertheless, in keeping with jQuery Mobile widget features, the options documented on its jQuery UI API reference page are also available as data-* attributes.
diff --git a/resources/button/example2.html b/resources/button/example2.html
deleted file mode 100644
index 67e37e03..00000000
--- a/resources/button/example2.html
+++ /dev/null
@@ -1,33 +0,0 @@
-
-
-
- Page Title
-
-
-
-
-
-
-
-
-
-
-
-
- Link button
-
-
-
-
-
diff --git a/resources/button/example33.html b/resources/button/example33.html
deleted file mode 100644
index e3b0dffe..00000000
--- a/resources/button/example33.html
+++ /dev/null
@@ -1,37 +0,0 @@
-
-
-
- Page Title
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/resources/button/example34.html b/resources/button/example34.html
deleted file mode 100644
index 7fff65d2..00000000
--- a/resources/button/example34.html
+++ /dev/null
@@ -1,37 +0,0 @@
-
-
-
- Page Title
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/resources/button/example35.html b/resources/button/example35.html
deleted file mode 100644
index d42db0e3..00000000
--- a/resources/button/example35.html
+++ /dev/null
@@ -1,72 +0,0 @@
-
-
-
- Page Title
-
-
-
-
-
-
-
-
-
-
-
-
- Swatch "a" on container with themed buttons inside
-
- Swatch "b" on container with themed buttons inside
-
- Swatch "c" on container with themed buttons inside
-
- Swatch "d" on container with themed buttons inside
-
- Swatch "e" on container with themed buttons inside
-
-
-
-
-
-
diff --git a/resources/button/example47.html b/resources/button/example47.html
deleted file mode 100644
index 5edc3e12..00000000
--- a/resources/button/example47.html
+++ /dev/null
@@ -1,33 +0,0 @@
-
-
-
- Page Title
-
-
-
-
-
-
-
-
-
-
-
-
- Theme A
-
-
-
-
-
diff --git a/resources/button/example48.html b/resources/button/example48.html
new file mode 100644
index 00000000..a2aacc4b
--- /dev/null
+++ b/resources/button/example48.html
@@ -0,0 +1,38 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/resources/button/example49.html b/resources/button/example49.html
new file mode 100644
index 00000000..aa3f2759
--- /dev/null
+++ b/resources/button/example49.html
@@ -0,0 +1,41 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/resources/button/example5.html b/resources/button/example5.html
index 04fac0d9..75dea789 100644
--- a/resources/button/example5.html
+++ b/resources/button/example5.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example6.html b/resources/button/example6.html
index e74e1770..b9c062b8 100644
--- a/resources/button/example6.html
+++ b/resources/button/example6.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example7.html b/resources/button/example7.html
index fa73a04f..b590f4fd 100644
--- a/resources/button/example7.html
+++ b/resources/button/example7.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example1.html b/resources/buttonMarkup/example1.html
similarity index 54%
rename from resources/button/example1.html
rename to resources/buttonMarkup/example1.html
index bb4cae15..19061597 100644
--- a/resources/button/example1.html
+++ b/resources/buttonMarkup/example1.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
diff --git a/resources/button/example10.html b/resources/buttonMarkup/example10.html
similarity index 85%
rename from resources/button/example10.html
rename to resources/buttonMarkup/example10.html
index 2cb96617..824648ce 100644
--- a/resources/button/example10.html
+++ b/resources/buttonMarkup/example10.html
@@ -1,30 +1,30 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
-
-
+
+
+
Bars - data-icon="bars"
My button
Edit - data-icon="edit"
@@ -69,4 +69,3 @@
-
diff --git a/resources/button/example11.html b/resources/buttonMarkup/example11.html
similarity index 56%
rename from resources/button/example11.html
rename to resources/buttonMarkup/example11.html
index 52d5da7b..94cec363 100644
--- a/resources/button/example11.html
+++ b/resources/buttonMarkup/example11.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example12.html b/resources/buttonMarkup/example12.html
similarity index 64%
rename from resources/button/example12.html
rename to resources/buttonMarkup/example12.html
index 3cb83710..28814164 100644
--- a/resources/button/example12.html
+++ b/resources/buttonMarkup/example12.html
@@ -1,30 +1,30 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
-
-
+
+
+
Creates this button with right-aligned icon:
Delete
Icons can also be positioned above the text by specifying data-iconpos="top"
@@ -35,4 +35,3 @@
-
diff --git a/resources/button/example15.html b/resources/buttonMarkup/example15.html
similarity index 56%
rename from resources/button/example15.html
rename to resources/buttonMarkup/example15.html
index 491d1028..ae101fc1 100644
--- a/resources/button/example15.html
+++ b/resources/buttonMarkup/example15.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example16.html b/resources/buttonMarkup/example16.html
similarity index 73%
rename from resources/button/example16.html
rename to resources/buttonMarkup/example16.html
index 178fcd2e..9286a79e 100644
--- a/resources/button/example16.html
+++ b/resources/buttonMarkup/example16.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example17.html b/resources/buttonMarkup/example17.html
similarity index 64%
rename from resources/button/example17.html
rename to resources/buttonMarkup/example17.html
index b757fbd1..b54925c5 100644
--- a/resources/button/example17.html
+++ b/resources/buttonMarkup/example17.html
@@ -1,30 +1,30 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
-
-
+
+
+
diff --git a/resources/buttonMarkup/example2.html b/resources/buttonMarkup/example2.html
new file mode 100644
index 00000000..4fefb34a
--- /dev/null
+++ b/resources/buttonMarkup/example2.html
@@ -0,0 +1,32 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+ Link button
+
+
+
+
diff --git a/resources/button/example20.html b/resources/buttonMarkup/example20.html
similarity index 69%
rename from resources/button/example20.html
rename to resources/buttonMarkup/example20.html
index d292b006..184fde1b 100644
--- a/resources/button/example20.html
+++ b/resources/buttonMarkup/example20.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
By default, all buttons in the body content are styled as block-level elements so they fill the width of the screen:
Button
However, if you want a more compact button that is only as wide as the text and icons inside, add the data-inline="true" attribute to the button:
@@ -33,4 +33,3 @@
-
diff --git a/resources/button/example22.html b/resources/buttonMarkup/example22.html
similarity index 70%
rename from resources/button/example22.html
rename to resources/buttonMarkup/example22.html
index 9f118a28..08fc5d93 100644
--- a/resources/button/example22.html
+++ b/resources/buttonMarkup/example22.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example24.html b/resources/buttonMarkup/example24.html
similarity index 69%
rename from resources/button/example24.html
rename to resources/buttonMarkup/example24.html
index b71170e7..6e8cd672 100644
--- a/resources/button/example24.html
+++ b/resources/buttonMarkup/example24.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
- When an icon is added to an inline button, the button will grow wider to accommodate the icon:
+
+ When an icon is added to an inline button, the button will grow wider to accommodate the icon:
Cancel
Save
A mini version of the same:
@@ -35,4 +35,3 @@
-
diff --git a/resources/button/example26.html b/resources/buttonMarkup/example26.html
similarity index 61%
rename from resources/button/example26.html
rename to resources/buttonMarkup/example26.html
index 02aa3a19..507538df 100644
--- a/resources/button/example26.html
+++ b/resources/buttonMarkup/example26.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
Yes
No
diff --git a/resources/button/example27.html b/resources/buttonMarkup/example27.html
similarity index 86%
rename from resources/button/example27.html
rename to resources/buttonMarkup/example27.html
index a5acc5a8..bdce8557 100644
--- a/resources/button/example27.html
+++ b/resources/buttonMarkup/example27.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
Horizontal grouped buttons:
Yes
@@ -63,4 +63,3 @@
-
diff --git a/resources/button/example3.html b/resources/buttonMarkup/example3.html
similarity index 55%
rename from resources/button/example3.html
rename to resources/buttonMarkup/example3.html
index 8e86ff21..6e5a9328 100644
--- a/resources/button/example3.html
+++ b/resources/buttonMarkup/example3.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
diff --git a/resources/buttonMarkup/example33.html b/resources/buttonMarkup/example33.html
new file mode 100644
index 00000000..edc71eff
--- /dev/null
+++ b/resources/buttonMarkup/example33.html
@@ -0,0 +1,33 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/resources/buttonMarkup/example34.html b/resources/buttonMarkup/example34.html
new file mode 100644
index 00000000..9fa676e1
--- /dev/null
+++ b/resources/buttonMarkup/example34.html
@@ -0,0 +1,33 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/resources/buttonMarkup/example35.html b/resources/buttonMarkup/example35.html
new file mode 100644
index 00000000..9a37fe18
--- /dev/null
+++ b/resources/buttonMarkup/example35.html
@@ -0,0 +1,41 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/resources/button/example4.html b/resources/buttonMarkup/example4.html
similarity index 53%
rename from resources/button/example4.html
rename to resources/buttonMarkup/example4.html
index 76ecec22..a0624d0c 100644
--- a/resources/button/example4.html
+++ b/resources/buttonMarkup/example4.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example40.html b/resources/buttonMarkup/example40.html
similarity index 55%
rename from resources/button/example40.html
rename to resources/buttonMarkup/example40.html
index 195862fe..df1e2897 100644
--- a/resources/button/example40.html
+++ b/resources/buttonMarkup/example40.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
diff --git a/resources/button/example41.html b/resources/buttonMarkup/example41.html
similarity index 55%
rename from resources/button/example41.html
rename to resources/buttonMarkup/example41.html
index 466429d5..22f982bc 100644
--- a/resources/button/example41.html
+++ b/resources/buttonMarkup/example41.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
diff --git a/resources/button/example42.html b/resources/buttonMarkup/example42.html
similarity index 56%
rename from resources/button/example42.html
rename to resources/buttonMarkup/example42.html
index a01e3d16..5a5fb17f 100644
--- a/resources/button/example42.html
+++ b/resources/buttonMarkup/example42.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
diff --git a/resources/button/example43.html b/resources/buttonMarkup/example43.html
similarity index 53%
rename from resources/button/example43.html
rename to resources/buttonMarkup/example43.html
index 26e5835d..0742dbec 100644
--- a/resources/button/example43.html
+++ b/resources/buttonMarkup/example43.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
- No icon shadow
+
-
diff --git a/resources/button/example44.html b/resources/buttonMarkup/example44.html
similarity index 55%
rename from resources/button/example44.html
rename to resources/buttonMarkup/example44.html
index 60f5e5d3..1210b1f5 100644
--- a/resources/button/example44.html
+++ b/resources/buttonMarkup/example44.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example45.html b/resources/buttonMarkup/example45.html
similarity index 54%
rename from resources/button/example45.html
rename to resources/buttonMarkup/example45.html
index 52141fd7..1823a044 100644
--- a/resources/button/example45.html
+++ b/resources/buttonMarkup/example45.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/button/example46.html b/resources/buttonMarkup/example46.html
similarity index 55%
rename from resources/button/example46.html
rename to resources/buttonMarkup/example46.html
index 8221eb8b..f354d823 100644
--- a/resources/button/example46.html
+++ b/resources/buttonMarkup/example46.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
diff --git a/resources/buttonMarkup/example47.html b/resources/buttonMarkup/example47.html
new file mode 100644
index 00000000..15a4611a
--- /dev/null
+++ b/resources/buttonMarkup/example47.html
@@ -0,0 +1,32 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+ Theme B
+
+
+
+
diff --git a/resources/buttonMarkup/example48.html b/resources/buttonMarkup/example48.html
new file mode 100644
index 00000000..9ec7d7e1
--- /dev/null
+++ b/resources/buttonMarkup/example48.html
@@ -0,0 +1,32 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+ Example
+
+
+
+
diff --git a/resources/buttonMarkup/example49.html b/resources/buttonMarkup/example49.html
new file mode 100644
index 00000000..563d7f0b
--- /dev/null
+++ b/resources/buttonMarkup/example49.html
@@ -0,0 +1,32 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+ Home
+
+
+
+
diff --git a/resources/button/example8.html b/resources/buttonMarkup/example8.html
similarity index 65%
rename from resources/button/example8.html
rename to resources/buttonMarkup/example8.html
index a9f078cd..7e119c79 100644
--- a/resources/button/example8.html
+++ b/resources/buttonMarkup/example8.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
Creates this button with an icon:
Delete
A more compact button with the data-mini="true" attribute added to the button:
@@ -33,4 +33,3 @@
-
diff --git a/resources/checkbox/example1.html b/resources/checkbox/example1.html
index 47ff1591..ca607ccb 100644
--- a/resources/checkbox/example1.html
+++ b/resources/checkbox/example1.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
diff --git a/resources/checkbox/example2.html b/resources/checkbox/example2.html
index 5f6c4605..29a6e1fd 100644
--- a/resources/checkbox/example2.html
+++ b/resources/checkbox/example2.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
-
diff --git a/resources/checkbox/example3.html b/resources/checkbox/example3.html
index 845cfb77..3f02432b 100644
--- a/resources/checkbox/example3.html
+++ b/resources/checkbox/example3.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
+
+
-
diff --git a/resources/checkbox/example4.html b/resources/checkbox/example4.html
index 257de8bc..5497a272 100644
--- a/resources/checkbox/example4.html
+++ b/resources/checkbox/example4.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
+
+
-
diff --git a/resources/checkbox/example5.html b/resources/checkbox/example5.html
index 450059df..ba240c16 100644
--- a/resources/checkbox/example5.html
+++ b/resources/checkbox/example5.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
+
+
@@ -44,4 +44,3 @@
-
diff --git a/resources/checkbox/example6.html b/resources/checkbox/example6.html
new file mode 100644
index 00000000..62a4bd78
--- /dev/null
+++ b/resources/checkbox/example6.html
@@ -0,0 +1,41 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/resources/collapsible-set/example7.html b/resources/collapsible-set/example7.html
deleted file mode 100644
index 9f43d97f..00000000
--- a/resources/collapsible-set/example7.html
+++ /dev/null
@@ -1,45 +0,0 @@
-
-
-
- Page Title
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Section header, swatch B
- Collapsible content, swatch "b"
-
-
- Section header, swatch A
- Collapsible content, swatch "a"
-
-
- Section header, swatch E
- Collapsible content, swatch "d"
-
-
-
-
-
-
\ No newline at end of file
diff --git a/resources/collapsible/example1.html b/resources/collapsible/example1.html
index f90dc39f..bfe346a5 100644
--- a/resources/collapsible/example1.html
+++ b/resources/collapsible/example1.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
I'm a header
I'm the collapsible content. By default I'm closed, but you can click the header to open me.
@@ -33,4 +33,3 @@ I'm a header
-
diff --git a/resources/collapsible/example10.html b/resources/collapsible/example10.html
new file mode 100644
index 00000000..8b12795a
--- /dev/null
+++ b/resources/collapsible/example10.html
@@ -0,0 +1,36 @@
+
+
+
+ Page Title
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/resources/collapsible/example2.html b/resources/collapsible/example2.html
index 4f4fa3d6..23b3c0d3 100644
--- a/resources/collapsible/example2.html
+++ b/resources/collapsible/example2.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
I'm a header
I'm the collapsible content. I'm expanded by default because I have the "collapsed" state set to false.
@@ -33,4 +33,3 @@ I'm a header
-
diff --git a/resources/collapsible/example3.html b/resources/collapsible/example3.html
index 7ccbbf37..c9db5bf5 100644
--- a/resources/collapsible/example3.html
+++ b/resources/collapsible/example3.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
I'm a header
I'm the collapsible content.
@@ -33,4 +33,3 @@ I'm a header
-
diff --git a/resources/collapsible/example4.html b/resources/collapsible/example4.html
index c8c199a4..7389f37c 100644
--- a/resources/collapsible/example4.html
+++ b/resources/collapsible/example4.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
I'm a mini header
I'm the collapsible content.
@@ -33,4 +33,3 @@ I'm a mini header
-
diff --git a/resources/collapsible/example5.html b/resources/collapsible/example5.html
index 4fb12add..9070e742 100644
--- a/resources/collapsible/example5.html
+++ b/resources/collapsible/example5.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
I have custom icons
data-collapsed-icon="arrow-r" and data-expanded-icon="arrow-d"
@@ -33,4 +33,3 @@ I have custom icons
-
diff --git a/resources/collapsible/example6.html b/resources/collapsible/example6.html
index 2765fa1d..edf58d12 100644
--- a/resources/collapsible/example6.html
+++ b/resources/collapsible/example6.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
+
I'm a header
data-iconpos="right"
@@ -33,4 +33,3 @@ I'm a header
-
diff --git a/resources/collapsible/example7.html b/resources/collapsible/example7.html
index 95a53ae4..339bb02f 100644
--- a/resources/collapsible/example7.html
+++ b/resources/collapsible/example7.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
+
+
Header
- I'm the collapsible content with a themed content block set to "c".
+ I'm the collapsible content with a themed content block set to "b".
-
diff --git a/resources/collapsible/example8.html b/resources/collapsible/example8.html
index 8222663a..a55410b4 100644
--- a/resources/collapsible/example8.html
+++ b/resources/collapsible/example8.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
- Header swatch A
- I'm the collapsible content with a themed content block set to "a".
-
-
-
+
+
Header swatch B
- I'm the collapsible content with a themed content block set to "d".
+ I'm the collapsible content with a themed content block set to "b".
+
+
+
+ Header swatch a
+ I'm the collapsible content with a themed content block set to "b".
-
diff --git a/resources/collapsible/example9.html b/resources/collapsible/example9.html
index fc10cff7..9f6476de 100644
--- a/resources/collapsible/example9.html
+++ b/resources/collapsible/example9.html
@@ -1,13 +1,13 @@
-
-
-
- Page Title
+
+
+
+ Page Title
-
+
-
-
-
+
+
+
-
+
-
+
-
-
+
+
I'm a header
I'm the collapsible content. By default I'm open and displayed on the page, but you can click the header to hide me.
-
-
+
+
I'm a nested collapsible with a child collapsible
I'm a child collapsible.
-
+
Nested inside again.
Three levels deep now.
-
-
+
+
Section 3: Form elements