Classes

Categories: CSS Framework

Classes
Description:CSS classes for common styles
Style Classes
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.
Widget-specific classes
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.
Button-specific classes
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
Icon classes
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 33 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 ().
Theme-related classes
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.
Grid Layout
Categories: CSS Framework
Grid Layoutversion added: 1.0
Description: Multi-column layout grids
Using multiple column layouts isn't generally recommended on a mobile device because
of the narrow screen width, but there are times where you may need to place small
elements side-by-side (like buttons or navigation tabs, for example).
The jQuery Mobile framework provides a simple way to build CSS-based columns
through a block style class convention called ui-grid.
There are four preset layouts that can be used in any situation that requires columns:
two-column (using the ui-grid-a class)
three-column (using the ui-grid-b class)
four-column (using the ui-grid-c class)
five-column (using the ui-grid-d class)
Grids are 100% width, completely invisible (no borders or backgrounds) and don't have
padding or margins, so they shouldn't interfere with the styles of elements placed inside
them.
Within the grid container, child elements are assigned ui-block-a/b/c/d/e in a sequential
manner which makes each "block" element float side-by-side, forming the grid. The
ui-block-a class essentially clears the floats which will start a new line (see multiple row
grids, below).
Two column grids
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:
1
2
3
4
<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 -->u
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:
1
2
3
4
<fieldset class="ui-grid-a">
<div class="ui-block-a"><button type="submit" data-theme="a">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.
1
2
3
4
5
6
7
<div class="ui-grid-a">
<div class="ui-block-a"><button type="button" data-theme="a">Previous</button></div>
<div class="ui-block-b"><button type="button" data-theme="a">Next</button></div>
</div>
<div class="ui-grid-solo">
<div class="ui-block-a"><button type="button" 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.
Three-column grids
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.
1
2
3
4
5
<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:
Four-column grids
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.
Five-column grids
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.
Multiple row grids
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 in toolbars
Grids are helpful for creating layouts within a toolbar. Here's a footer with a 4 column grid.
Example:
A basic example of grid layout
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>grid-layout demo</title>
<link rel="stylesheet" href="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.css">
<script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
<script src="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.js"></script>
</head>
<body>
<div data-role="page" id="page1">
<div data-role="header">
<h1>Grid Layout Example</h1>
</div>
<div role="main" class="ui-content">
<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 -->
</div>
</div>
24
25
26
</body>
</html>
Demo:
Responsive Grid
Categories: CSS Framework
Responsive Gridversion added: 1.3
Description: 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:
1
2
3
4
5
<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.
1
2
3
4
5
6
7
8
9
10
@media all and (max-width: 50em) {
.my-breakpoint .ui-block-a,
.my-breakpoint .ui-block-b,
.my-breakpoint .ui-block-c,
.my-breakpoint .ui-block-d,
.my-breakpoint .ui-block-e {
width: 100%;
float:none;
}
}
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-ato 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:
1
2
3
4
5
6
7
@media all and (min-width: 75em) {
.my-breakpoint.ui-grid-b .ui-block-a { width: 49.95%; }
.my-breakpoint.ui-grid-b .ui-block-b,
.my-breakpoint.ui-grid-b .ui-block-c { width: 24.925%; }
.my-breakpoint.ui-grid-b .ui-block-a { clear: left; }
}
}
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 below560px (35em). If this breakpoint doesn't work for your content,
we encourage you to write a custom breakpoint as described above.
1 <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)
Example:
A basic example of responsive grids
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>responsive-grid demo</title>
<link rel="stylesheet" href="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.css">
<script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
<script src="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.js"></script>
<style>
@media all and (max-width: 35em) {
.my-breakpoint .ui-block-a,
.my-breakpoint .ui-block-b,
.my-breakpoint .ui-block-c,
.my-breakpoint .ui-block-d,
.my-breakpoint .ui-block-e {
width: 100%;
float:none;
}
}
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
@media all and (min-width: 45em) {
.my-breakpoint.ui-grid-b .ui-block-a { width: 49.95%; }
.my-breakpoint.ui-grid-b .ui-block-b,
.my-breakpoint.ui-grid-b .ui-block-c { width: 24.925%; }
}
</style>
</head>
<body>
<div data-role="header">
<h1>Responsive Grid Example</h1>
</div>
<div role="main" class="ui-content">
<div class="ui-grid-b my-breakpoint">
<div class="ui-block-a"><div class="ui-body ui-body-d">Block A</div></div>
<div class="ui-block-b"><div class="ui-body ui-body-d">Block B</div></div>
<div class="ui-block-c"><div class="ui-body ui-body-d">Block C</div></div>
</div>
</body>
</html>
Demo:
Category: Widgets
Widgets are feature-rich, stateful plugins that have a full life-cycle, along with methods
and events. Check out the widget factorydocumentation for more details.
Note: The base widget ($.mobile.widget) is deprecated as of 1.4 and will be removed in
1.5. It is now sufficient to base your custom jQuery Mobile widgets on the jQuery UI
widget factory itself. This means that in your call to $.widget() you can omit the base
altogether.
1
2
3
4
5
6
7
8
9
10
11
$.widget( "my.widget", /* NOTE: no base needed */ {
options: {
/* ... */
},
_create: function() {
/* ... */
}
/* ... */
});
Button Widget
Creates a button widget
Checkboxradio Widget
Creates a checkboxradio widget
Collapsible Widget
Creates a collapsible block of content
Collapsibleset Widget
Creates a set of collapsible blocks of content
Controlgroup Widget
Groups buttons together.
Dialog Widget
Opens content in an interactive overlay.
Filterable Content
Makes the children of an element filterable.
Fixedtoolbar Widget
See Toolbar Widget
Flipswitch Widget
Creates a flipswitch widget
Footer Widget
See Toolbar Widget
Header Widget
See Toolbar Widget
Listview Widget
Creates a listview widget
Loader Widget
Handles the task of displaying the loading dialog when jQuery Mobile pulls in content via
Ajax.
Navbar Widget
Creates a navbar widget
Page Widget
Primary unit of content.
Pagecontainer Widget
Manages a collection of pages.
Panel Widget
Creates a panel widget
Popup Widget
Opens content in a popup.
Rangeslider Widget
Creates a rangeslider widget
Selectmenu Widget
Creates a select menu widget
Slider Widget
Creates a slider widget
Table Widget
Creates a responsive table
Column-Toggle Table Widget
Creates a responsive table in column toggle mode
Reflow Table Widget
Creates a responsive table in reflow mode
Tabs Widget
A single content area with multiple panels, each associated with a header in a list.
Textinput Widget
Creates a textinput widget for textinput, textarea or search input
Toolbar Widget
Adds toolbars to the top and/or bottom of the page.
Navbar Widget
Categories: Widgets
Navbar Widgetversion added: 1.0
Description: Creates a navbar widget
QuickNavExamples
Options
defaults
disabled
iconpos
initSelector
Methods
Events
create
Simple navbar
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:
1
2
3
4
5
6
<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:
1
2
3
4
5
6
<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:
Adding a third item will automatically make each button 1/3 the width of the browser
window:
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%.
Navbars in headers
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.
Navbars in footers
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"
1
2
3
4
5
6
7
8
9
<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 in navbars
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.
1 <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":
Using 3rd party icon sets
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:
Icons by Joseph Wain / glyphish.com. Licensed under the Creative Commons Attribution
3.0 United States License.
Theming navbars
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:
To set the theme color for a navbar item, add the data-theme attribute to the individual links
and specify a theme swatch. Note that applying a theme swatch to the navbar container is
not supported.
Options
defaultsType: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and
causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves
option values from data attributes. This can improve startup time.
This option is also exposed as a data attribute: data-defaults="true".
Code examples:
Initialize the navbar with the defaults option specified:
1 $( ".selector" ).navbar({ defaults: true });
Get or set the defaults option, after initialization:
1
2
3
4
5
// getter
var defaults = $( ".selector" ).navbar( "option", "defaults" );
// setter
$( ".selector" ).navbar( "option", "defaults", true );
disabledType: Boolean
Default: false
Disables the navbar if set to true.
This option is also exposed as a data attribute: data-disabled="true".
Code examples:
Initialize the navbar with the disabled option specified:
1 $( ".selector" ).navbar({ disabled: true });
Get or set the disabled option, after initialization:
1
2
// getter
var disabled = $( ".selector" ).navbar( "option", "disabled" );
3
4
5
// setter
$( ".selector" ).navbar( "option", "disabled", true );
iconposType: String
Default: "top"
Positions the icon in the button. Possible values: left, right, top, bottom, none, notext. The
notext value will display an icon-only button with no text feedback.
1 <div data-role="navbar" data-iconpos="bottom">
initSelectorType: Selector
Default: See below
The default initSelector for the navbar widget is:
1 ":jqmData(role='navbar')"
Note: This option is deprecated in 1.4.0 and will be removed in 1.5.0.
As of jQuery Mobile 1.4.0, the initSelector is no longer a widget option. Instead, it is
declared directly on the widget prototype. Thus, you may specify a custom value by
handling the mobileinitevent and overwriting the initSelector on the prototype:
1
2
3
$( document ).on( "mobileinit", function() {
$.mobile.navbar.prototype.initSelector = "div.custom";
});
Note: Remember to attach the mobileinit handler after you have loaded jQuery, but before
you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading
process.
The value of this option is a jQuery selector string. The framework selects elements
based on the value of this option and instantiates navbar widgets on each of the resulting
list of elements.
(version deprecated: 1.4.0)
Events
create()Type: navbarcreate
triggered when a navbar is created
This method does not accept any arguments.
Note: The ui object is empty but included for consistency with other events.
Code examples:
Initialize the navbar with the create callback specified:
1
2
3
$( ".selector" ).navbar({
create: function( event, ui ) {}
});
Bind an event listener to the navbarcreate event:
1 $( ".selector" ).on( "navbarcreate", function( event, ui ) {} );
Example:
A basic example of a navbar
1
2
3
4
5
6
7
8
9
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>navbar demo</title>
<link rel="stylesheet" href="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.css">
<script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
<script src="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.js"></script>
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
</head>
<body>
<div data-role="page" id="page1">
<div data-role="header">
<h1>jQuery Mobile Example</h1>
</div>
<div role="main" class="ui-content">
<p>Some Content here</p>
</div>
<div data-role="footer">
<div data-role="navbar">
<ul>
<li><a href="#" class="ui-btn-active">One</a></li>
<li><a href="#">Two</a></li>
</ul>
</div><!-- /navbar -->
</div><!-- /footer -->
</div><!-- /page -->
</body>
</html>
Demo:
Pagecontainer Widget
Categories: Widgets
Pagecontainer Widgetversion added: 1.4
Description: Manages a collection of pages.
QuickNav
Options
defaults
disabled
theme
Methods
change
getActivePage
load
Events
beforeload
beforetransition
changefailed
create
hide
load
loadfailed
show
transition
Smooth Navigation Between Pages
Note: The pagecontainer widget is designed to be a singleton instantiated by the
framework on the bodyelement. This limitation will be removed in future versions of
jQuery Mobile.
jQuery Mobile's central abstraction is the use of multiple pages inside a single HTML
document. The children of the bodyare all div elements that have been enhanced into
page widgets. These are jQuery Mobile pages.
Only one page is visible at a time. Upon navigation, the currently visible page is hidden,
and another page is shown. Moving from one page to another is accomplished via a
transition. This is not possible when navigating between HTML documents via HTTP,
because the browser discards all state associated with the source page when navigating
to the target page, making it impossible to perform this task via a smooth transition effect
such as a fade or a slide.
Multipage Documents
In its simplest form, the HTML document retrieved by the browser has a body consisting of
several div elements which are enhanced using the page widget. Each such page has an
id attribute to distinguish it from other pages.
The pages can be interlinked using anchors. When the user clicks such an anchor, a new
history entry is created, and the page to which the anchor refers is displayed by means of
a smooth transition from the previous page. The example below illustrates a multipage
setup. Note: If the example below animates using a fade transition instead of the slide
transition requested in the anchor, it is because your browser does not support CSS 3D
transforms.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<!doctype html>
<html>
<head>
<title>Multipage example</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.css" />
<script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
<script src="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.js"></script>
</head>
<body>
<div data-role="page" id="page1">
<div data-role="header">
<h1>Page 1</h1>
</div>
<div role="main" class="ui-content">
<a href="#page2" data-transition="slide" class="ui-btn ui-corner-all ui-btn-inline">Go To Page 2</a>
</div>
</div>
<div data-role="page" id="page2">
<div data-role="header">
<h1>Page 2</h1>
</div>
<div role="main" class="ui-content">
<a href="#page1" data-rel="back" data-transition="slide" class="ui-btn ui-corner-all ui-btn-inline">Go Back To Page 1</a>
</div>
</div>
</body>
</html>
HTTP-analogous navigation via Ajax
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:
The global configuration option $.mobile.linkBindingEnabled must be true.
The click event's default must not be prevented and it must be a left-click.
The link must not have any of the following attributes:
data-rel="back"
data-rel="external
data-ajax="false"
The target attribute must not be present
The global configuration option $.mobile.ajaxEnabled must be true.
The link must be to the same domain or it must be to a permitted
cross-domain-request destination.
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.
Options
defaultsType: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and
causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves
option values from data attributes. This can improve startup time.
This option is also exposed as a data attribute: data-defaults="true".
Code examples:
Initialize the pagecontainer with the defaults option specified:
1 $( ".selector" ).pagecontainer({ defaults: true });
Get or set the defaults option, after initialization:
1
2
3
4
5
// getter
var defaults = $( ".selector" ).pagecontainer( "option", "defaults" );
// setter
$( ".selector" ).pagecontainer( "option", "defaults", true );
disabledType: Boolean
Default: false
Disables the pagecontainer if set to true.
This option is also exposed as a data attribute: data-disabled="true".
Code examples:
Initialize the pagecontainer with the disabled option specified:
1 $( ".selector" ).pagecontainer({ disabled: true });
Get or set the disabled option, after initialization:
1
2
3
4
5
// getter
var disabled = $( ".selector" ).pagecontainer( "option", "disabled" );
// setter
$( ".selector" ).pagecontainer( "option", "disabled", true );
themeType: String
Default: a
Sets the color scheme (swatch) for the pagecontainer widget. It accepts a single letter
from a-z that maps to the swatches included in your theme.
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b".
Code examples:
Initialize the pagecontainer with the theme option specified:
1 $( ".selector" ).pagecontainer({ theme: "b" });
Get or set the theme option, after initialization:
1
2
3
4
5
// getter
var theme = $( ".selector" ).pagecontainer( "option", "theme" );
// setter
$( ".selector" ).pagecontainer( "option", "theme", "b" );
Methods
change( to, options )Returns: jQuery (plugin only)
to
Type: String or jQuery
The URL to which to navigate. This can be specified either as a string, or as a jQuery
collection object containing the page DOM element.
options
Type: Object
allowSamePageTransition (default: false)
Type: Boolean
By default, 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.
changeHash (default: true)
Type: Boolean
Whether to create a new browser history entry as part of the navigation sequence.
Possible values:
true
The pagecontainer will create a browser history entry as part of moving to the
desired page. Thus, the user can use the browser's "Back" and "Forward"
buttons to navigate between the source page and the destination page.
false
The pagecontainer will navigate to the desired page without creating a new
browser history entry. The desired page replaces the current page, and the
browser's "Back" and "Forward" buttons cannot be used to navigate between
the source page and the destination page.
dataUrl (default: undefined)
Type: String
The URL to use when updating the browser location upon change() completion. If not
specified, the value of the data-url attribute of the page element is used.
loadMsgDelay (default: 50)
Type: Number
The number of milliseconds by which to delay the appearance of the loading message. If
the load completes within this time, no loading message is displayed.
reloadPage (default: false)
Type: Boolean
Note: This property is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0.
Use property 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.
(version deprecated: 1.4.0)
reload (default: false)
Type: Boolean
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.
reverse (default: false)
Type: Boolean
Whether the transition shall be applied in reverse. By setting this value to true you can
simulate returning to a previous page, even when the actual navigation sequence is in a
forward direction.
role (default: undefined)
Type: String
The data-role value to be used when displaying the page. By default this is undefined
which means rely on the value of the @data-role attribute defined on the element.
showLoadMsg (default: true)
Type: Boolean
Whether to display a message indicating that the page is loading.
transition (default: undefined)
Type: String
The transition that should be used for the page change. If the value is 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
type (default: "get")
Type: String
The type of HTTP request to use ("get", "post", etc.). Used only when the 'to' argument is
a URL.
Code examples:
Invoke the change method:
1 $( ".selector" ).pagecontainer( "change" );
Programmatically change from one page to another.
1 $( ":mobile-pagecontainer" ).pagecontainer( "change", "confirm.html", { role: "dialog" } );
getActivePage()Returns: jQuery
Return the currently active page.
This method does not accept any arguments.
Code examples:
Invoke the getActivePage method:
1 $( ".selector" ).pagecontainer( "getActivePage" );
load( url, options )Returns: Promise
url
Type: String or jQuery
The URL from which to load the page. This can be an absolute or a relative URL (e.g.
"about/us.html"). You can also specify a jQuery collection object.
options
Type: Object
A hash containing options that affect the behavior of the method.
type (default: "get")
Type: String
The type of HTTP request to use ("get", "post", etc.).
data (default: undefined)
Type: Object or String
The data to send with an Ajax page request.
reloadPage (default: false)
Type: Boolean
Note: This property is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0.
Use property 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.
(version deprecated: 1.4.0)
reload (default: false)
Type: Boolean
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.
role (default: undefined)
Type: String
The data-role value to be used when displaying the page. By default this is undefined
which means rely on the value of the @data-role attribute defined on the element.
showLoadMsg (default: true)
Type: Boolean
Whether to display a message indicating that the page is loading.
loadMsgDelay (default: 50)
Type: Number
The number of milliseconds by which to delay the appearance of the loading message. If
the load completes within this time, no loading message is displayed.
Code examples:
Invoke the load method:
1 $( ".selector" ).pagecontainer( "load" );
Load an external page, enhance its content, and insert it into the DOM.
1 $( ":mobile-pagecontainer" ).pagecontainer( "load", "confirm.html", { role: "dialog" } );
Events
beforeload( event, ui )Type: pagecontainerbeforeload
Triggered before any load request is made.
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.
event
Type: Event
ui
Type: Object
url
Type: String
The absolute or relative URL that was passed into load() by the caller.
absUrl
Type: String
The absolute version of the url. If url was relative, it is resolved against the url used to
load the current active page.
dataUrl
Type: String
The filtered version of absUrl to be used when identifying the page and updating the
browser location when the page is made active.
deferred
Type: Deferred
Deferred to be resolved or rejected upon completion of content load. Callbacks that call
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$( document ).on( "pagecontainerbeforeload", function( event, data ) {
// Let the framework know we're going to handle the load.
event.preventDefault();
// ... load the document then insert it into the DOM ...
// 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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$( document ).on( "pagecontainerbeforeload", function( event, data ) {
// Let the framework know we're going to handle the load.
event.preventDefault();
// ... load the document then insert it into the DOM ...
// 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
Type: Object
This object contains the options that were passed into load().
Code examples:
Initialize the pagecontainer with the beforeload callback specified:
1
2
3
$( ".selector" ).pagecontainer({
beforeload: function( event, ui ) {}
});
Bind an event listener to the pagecontainerbeforeload event:
1 $( ".selector" ).on( "pagecontainerbeforeload", function( event, ui ) {} );
beforetransition( event, ui )Type: pagecontainerbeforetransition
Triggered before the transition between two pages starts.
event
Type: Event
ui
Type: Object
absUrl
Type: String
The absolute version of the url. If url was relative, it is resolved against the url used to
load the current active page.
options
Type: Object
The configuration options to be used for the current change() call.
originalHref
Type: String
The href from the link that started the page change process.
toPage
Type: jQuery
This property represents the page to which the caller wishes to transition. It is a jQuery
collection object containing the page DOM element.
Code examples:
Initialize the pagecontainer with the beforetransition callback specified:
1
2
3
$( ".selector" ).pagecontainer({
beforetransition: function( event, ui ) {}
});
Bind an event listener to the pagecontainerbeforetransition event:
1 $( ".selector" ).on( "pagecontainerbeforetransition", function( event, ui ) {} );
changefailed( event, ui )Type: pagecontainerchangefailed
Triggered when the change() request fails to load the page.
event
Type: Event
ui
Type: Object
toPage
Type: jQuery or String
This property represents the page the caller wishes to make active. It may be either a
jQuery collection object containing the page DOM element, or an absolute/relative url to
an internal or external page, in which case the value exactly matches the first argument to
the change() call that triggered the event.
options
Type: Object
The configuration options to be used for the current change() call.
Code examples:
Initialize the pagecontainer with the changefailed callback specified:
1
2
3
$( ".selector" ).pagecontainer({
changefailed: function( event, ui ) {}
});
Bind an event listener to the pagecontainerchangefailed event:
1 $( ".selector" ).on( "pagecontainerchangefailed", function( event, ui ) {} );
create( event, ui )Type: pagecontainercreate
Triggered when the pagecontainer is created.
event
Type: Event
ui
Type: Object
Note: The ui object is empty but included for consistency with other events.
Code examples:
Initialize the pagecontainer with the create callback specified:
1
2
3
$( ".selector" ).pagecontainer({
create: function( event, ui ) {}
});
Bind an event listener to the pagecontainercreate event:
1 $( ".selector" ).on( "pagecontainercreate", function( event, ui ) {} );
hide( event, ui )Type: pagecontainerhide
Triggered after the transition animation has completed. Note: Unlike the deprecated
pagehide event, this event is not triggered on the "fromPage" but the pagecontainer
widget's element.
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:
1
2
3
$( ":mobile-pagecontainer" ).on( "pagecontainerhide", function( event, ui ) {
alert( "This page was just shown: " + ui.nextPage );
});
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.
event
Type: Event
ui
Type: Object
nextPage
Type: jQuery
A jQuery collection object that contains the page DOM element to which we just
transitioned.
Code examples:
Initialize the pagecontainer with the hide callback specified:
1
2
3
$( ".selector" ).pagecontainer({
hide: function( event, ui ) {}
});
Bind an event listener to the pagecontainerhide event:
1 $( ".selector" ).on( "pagecontainerhide", function( event, ui ) {} );
load( event, ui )Type: pagecontainerload
Triggered after the page is successfully loaded and inserted into the DOM.
event
Type: Event
ui
Type: Object
url
Type: String
The absolute or relative URL that was passed into load() by the caller.
absUrl
Type: String
The absolute version of the url. If url was relative, it is resolved against the url used to
load the current active page.
dataUrl
Type: String
The filtered version of absUrl to be used when identifying the page and updating the
browser location when the page is made active.
options
Type: Object
This object contains the options that were passed into load().
xhr
Type: XMLHttpRequest
The jQuery XMLHttpRequest object used when attempting to load the page. This is what
gets passed as the 3rd argument to the framework's $.ajax() success callback.
textStatus
Type: String
According to the jQuery Core documentation, this will be a string describing the status.
This is what gets passed as the 2nd argument to the framework's $.ajax() error callback. It
may also be null.
Code examples:
Initialize the pagecontainer with the load callback specified:
1
2
3
$( ".selector" ).pagecontainer({
load: function( event, ui ) {}
});
Bind an event listener to the pagecontainerload event:
1 $( ".selector" ).on( "pagecontainerload", function( event, ui ) {} );
loadfailed( event, ui )Type: pagecontainerloadfailed
Triggered if the page load request failed.
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.
event
Type: Event
ui
Type: Object
url
Type: String
The absolute or relative URL that was passed into load() by the caller.
absUrl
Type: String
The absolute version of the url. If url was relative, it is resolved against the url used to
load the current active page.
dataUrl
Type: String
The filtered version of absUrl to be used when identifying the page and updating the
browser location when the page is made active.
deferred
Type: Deferred
Callbacks that call 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:
1
2
3
$( document ).on( "pageloadfailed", function( event, data ) {
// Let the framework know we're going to handle things.
4
5
6
7
8
9
10
11
12
13
14
15
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$( 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
Type: Object
This object contains the options that were passed into load().
xhr
Type: XMLHttpRequest
The jQuery XMLHttpRequest object used when attempting to load the page. This is what
gets passed as the first argument to the framework's $.ajax() error callback.
textStatus
Type: String
According to the jQuery Core documentation, possible values for this property, aside from
null, are "timeout", "error", "abort", and "parsererror". This is what gets passed as the 2nd
argument to the framework's $.ajax() error callback.
errorThrown
Type: String or Object
According to the jQuery Core documentation, this property may be an exception object if
one occurred, or if an HTTP error occurred this will be set to the textual portion of the
HTTP status. Otherwise it will be null. This is what gets passed as the 3rd argument to the
framework's $.ajax() error callback.
Code examples:
Initialize the pagecontainer with the loadfailed callback specified:
1
2
3
$( ".selector" ).pagecontainer({
loadfailed: function( event, ui ) {}
});
Bind an event listener to the pagecontainerloadfailed event:
1 $( ".selector" ).on( "pagecontainerloadfailed", function( event, ui ) {} );
show( event, ui )Type: pagecontainershow
Triggered after the transition animation has completed.Note: Unlike the deprecated
pageshow event, this event is not triggered on the "toPage" but the pagecontainer widget's
element.
You can access the prevPage properties via the second argument of a bound callback
function. For example:
1
2
3
$( ":mobile-pagecontainer" ).on( "pagecontainershow", function( event, ui ) {
alert( "This page was just hidden: " + ui.prevPage );
});
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.
event
Type: Event
ui
Type: Object
prevPage
Type: jQuery
A jQuery collection object that contains the page DOM element that we just transitioned
away from. Note that this collection is empty when the first page is transitioned in during
application startup.
Code examples:
Initialize the pagecontainer with the show callback specified:
1 $( ".selector" ).pagecontainer({
2
3
show: function( event, ui ) {}
});
Bind an event listener to the pagecontainershow event:
1 $( ".selector" ).on( "pagecontainershow", function( event, ui ) {} );
transition( event, ui )Type: pagecontainertransition
Triggered after the page change transition completes.
event
Type: Event
ui
Type: Object
absUrl
Type: String
The absolute version of the url of the destination page. If url was relative, it is resolved
against the url used to load the current active page.
options
Type: Object
This object contains the options that were passed into load().
originalHref
Type: String
The href from the link that started the page change process.
toPage
Type: jQuery
This property represents the page to which the caller has transitioned. It is a jQuery
collection object containing the page DOM element.
Code examples:
Initialize the pagecontainer with the transition callback specified:
1
2
3
$( ".selector" ).pagecontainer({
transition: function( event, ui ) {}
});
Bind an event listener to the pagecontainertransition event:
1 $( ".selector" ).on( "pagecontainertransition", function( event, ui ) {} );