Pages
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 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.
Dialogs
The page widget has the option dialog
which you can set to true
to obtain a page styled like a dialog, such as in the example below:
<div data-role="page" data-dialog="true"> <div data-role="header"> <h2>Are you sure?</h2> </div> <div class="ui-content" role="main"> <h2>Are you sure you wish to exit the application?</h2> <p>You have unsaved changes. If you exit without saving them, you will lose them.</p> <div class="ui-grid-a"> <div class="ui-block-a"> <a href="#" id="exit-button" class="ui-btn ui-btn-b ui-shadow ui-corner-all">Exit</a> </div> <div class="ui-block-b"> <a href="#" id="cancel-button" class="ui-btn ui-shadow ui-corner-all">Cancel</a> </div> </div> </div> </div>
You can programmatically close a page styled as a dialog by navigating to another page. For example, you can use the pagecontainer
change
method:
$( ":mobile-pagecontainer" ).pagecontainer( "change", "somepage.html" );
You can also simply go back:
$.mobile.back();
"left"
dialog
extension. Sets the position of the dialog close button in the header.
Possible values:
- "left"
- The button will be placed on the left edge of the titlebar.
- "right"
- The button will be placed on the right edge of the titlebar.
- "none"
- The dialog will not have a close button.
This option is also exposed as a data attribute: data-close-btn
.
Code examples:
Initialize the page with the closeBtn
option specified:
$( ".selector" ).page({ closeBtn: "none" });
Get or set the closeBtn
option, after initialization:
// Getter var closeBtn = $( ".selector" ).page( "option", "closeBtn" ); // Setter $( ".selector" ).page( "option", "closeBtn", "none" );
"Close"
dialog
extension. Customizes the text of the close button which is helpful for translating this into different languages. The close button is displayed as an icon-only button by default so the text isn't visible on-screen, but is read by screen readers so this is an important accessibility feature.
This option is also exposed as a data attribute: data-close-btn-text="Fermer"
.
Code examples:
Initialize the page with the closeBtnText
option specified:
$( ".selector" ).page({ closeBtnText: "Fermer" });
Get or set the closeBtnText
option, after initialization:
// Getter var closeBtnText = $( ".selector" ).page( "option", "closeBtnText" ); // Setter $( ".selector" ).page( "option", "closeBtnText", "Fermer" );
null, inherited from parent
Note:This option is deprecated in 1.4.0 and will be removed in 1.5.0.
Sets the color scheme (swatch) for the content div
of the page 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-content-theme="b"
.
Code examples:
Initialize the page with the contentTheme
option specified:
$( ".selector" ).page({ contentTheme: "b" });
Get or set the contentTheme
option, after initialization:
// Getter var contentTheme = $( ".selector" ).page( "option", "contentTheme" ); // Setter $( ".selector" ).page( "option", "contentTheme", "b" );
true
dialog
extension. Sets whether to draw the dialog with rounded corners.
This option is also exposed as a data attribute: data-corners="false"
.
Code examples:
Initialize the page with the corners
option specified:
$( ".selector" ).page({ corners: false });
Get or set the corners
option, after initialization:
// Getter var corners = $( ".selector" ).page( "option", "corners" ); // Setter $( ".selector" ).page( "option", "corners", false );
false
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 page with the defaults
option specified:
$( ".selector" ).page({ defaults: true });
Get or set the defaults
option, after initialization:
// Getter var defaults = $( ".selector" ).page( "option", "defaults" ); // Setter $( ".selector" ).page( "option", "defaults", true );
Note:This option is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Use $.mobile.degradeInputs
instead.
false
dialog
extension. Sets whether the page should be styled like a dialog.
This option is also exposed as a data attribute: data-dialog="true"
.
Code examples:
Initialize the page with the dialog
option specified:
$( ".selector" ).page({ dialog: true });
Get or set the dialog
option, after initialization:
// Getter var dialog = $( ".selector" ).page( "option", "dialog" ); // Setter $( ".selector" ).page( "option", "dialog", true );
false
true
. This option is also exposed as a data attribute: data-disabled="true"
.
Code examples:
Initialize the page with the disabled
option specified:
$( ".selector" ).page({ disabled: true });
Get or set the disabled
option, after initialization:
// Getter var disabled = $( ".selector" ).page( "option", "disabled" ); // Setter $( ".selector" ).page( "option", "disabled", true );
false
Sets whether to keep the page in the DOM after the user has navigated away from it.
This option is also exposed as a data attribute: data-dom-cache="true"
.
Code examples:
Initialize the page with the domCache
option specified:
$( ".selector" ).page({ domCache: true });
Get or set the domCache
option, after initialization:
// Getter var domCache = $( ".selector" ).page( "option", "domCache" ); // Setter $( ".selector" ).page( "option", "domCache", true );
See below
The default initSelector
for the page widget is:
":jqmData(role='page')"
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 mobileinit
event and overwriting the initSelector
on the prototype:
$( document ).on( "mobileinit", function() { $.mobile.page.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 page widgets on each of the resulting list of elements.
(version deprecated: 1.4.0)null
Note:This option is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Use $.mobile.keepNative
instead.
The value of this option is a selector that will be used in addition to the keepNativeDefault option to prevent elements matching it from being enhanced.
This option is also exposed as a data attribute: data-keep-native=".do-not-enhance
.
Code examples:
Initialize the page with the keepNative
option specified:
$( ".selector" ).page({ keepNative: ".do-not-enhance" });
Get or set the keepNative
option, after initialization:
// Getter var keepNative = $( ".selector" ).page( "option", "keepNative" ); // Setter $( ".selector" ).page( "option", "keepNative", ".do-not-enhance" );
":jqmData(role='none'), :jqmData(role='nojs')"
Note:This option is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Use $.mobile.keepNative
instead.
The value of this option is a selector that will be used to prevent elements matching it from being enhanced.
This option is also exposed as a data attribute: data-keep-native-default=".do-not-enhance
.
Code examples:
Initialize the page with the keepNativeDefault
option specified:
$( ".selector" ).page({ keepNativeDefault: ".do-not-enhance" });
Get or set the keepNativeDefault
option, after initialization:
// Getter var keepNativeDefault = $( ".selector" ).page( "option", "keepNativeDefault" ); // Setter $( ".selector" ).page( "option", "keepNativeDefault", ".do-not-enhance" );
"a"
dialog
extension. 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 element to set the overlay to any swatch letter.
Possible values: swatch letter (a-z)
This option is also exposed as a data attribute: data-overlay-theme="b"
.
Code examples:
Initialize the page with the overlayTheme
option specified:
$( ".selector" ).page({ overlayTheme: "b" });
Get or set the overlayTheme
option, after initialization:
// Getter var overlayTheme = $( ".selector" ).page( "option", "overlayTheme" ); // Setter $( ".selector" ).page( "option", "overlayTheme", "b" );
"a"
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b"
.
Code examples:
Initialize the page with the theme
option specified:
$( ".selector" ).page({ theme: "b" });
Get or set the theme
option, after initialization:
// Getter var theme = $( ".selector" ).page( "option", "theme" ); // Setter $( ".selector" ).page( "option", "theme", "b" );
- callbackType: Function()An optional callback to replace the internal handling of the page removal. The internal callback only removes the page if it is not being hidden as part of a same-page transition.
Invoke the method:
$( ".selector" ).page( "bindRemove", function() { alert( 'Page hidden' ); } );
Note:This method is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. The new keepNative option replaces it.
Returns the selector used to filter elements which are not to be enhanced.
(version deprecated: 1.4.0)- This method does not accept any arguments.
Invoke the keepNativeSelector method:
$( ".selector" ).page( "keepNativeSelector" );
Note:This method is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0.
Removes the background swatch from the page widget's container (usually the body).
(version deprecated: 1.4.0)- This method does not accept any arguments.
Invoke the removeContainerBackground method:
$( ".selector" ).page( "removeContainerBackground" );
Note:This method is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0.
Sets a new background swatch for the page widget's container (usually the body).
(version deprecated: 1.4.0)- themeType: String
Invoke the setContainerBackground method:
$( ".selector" ).page( "setContainerBackground", "b" );
pagebeforecreate
Triggered before a page is created. If one of the handlers returns false, the page is not created.
- eventType: Event
Note: The ui
object is empty but included for consistency with other events.
Initialize the page with the beforecreate callback specified:
$( ".selector" ).page({ beforecreate: function( event, ui ) {} });
Bind an event listener to the pagebeforecreate event:
$( ".selector" ).on( "pagebeforecreate", function( event, ui ) {} );
pagecreate
Triggered after a page has been created and enhancements to the page have been made.
- eventType: Event
Note: The ui
object is empty but included for consistency with other events.
Initialize the page with the create callback specified:
$( ".selector" ).page({ create: function( event, ui ) {} });
Bind an event listener to the pagecreate event:
$( ".selector" ).on( "pagecreate", function( event, ui ) {} );
A basic example of a page.
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>page demo</title> <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css"> <script src="//code.jquery.com/jquery-1.10.2.min.js"></script> <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script> </head> <body> <div data-role="page" id="page1"> <div data-role="header"> <h1>Page header (optional): Example page</h1> </div> <div role="main" class="ui-content"> <h2>Page content</h2> <p>Page content goes here.</p> </div> <div data-role="footer"> <h1>Page footer (optional)</h1> </div> </div> </body> </html>
Please login to continue.