Page Widget

Categories: Widgets

Page Widgetversion added: 1.0

Description: Primary unit of content.

QuickNavExamples

Options

Methods

Events

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
<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:

1
 
$( ":mobile-pagecontainer" ).pagecontainer( "change", "somepage.html" );

You can also simply go back:

1
 
$.mobile.back();

Options

classes 

Type: Object
Default: 
{}

Specify additional classes to add to the widget's elements. Any of classes specified in the Theming section can be used as keys to override their value. To learn more about this option, check out the learn article about the classes option.

Code examples:

Initialize the page with the classes option specified, changing the theming for the ui-page class:

1
2
3
4
5
 
$( ".selector" ).page({
  classes: {
    "ui-page": "highlight"
  }
});

Get or set a property of the classes option, after initialization, here reading and changing the theming for the ui-page class:

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).page( "option", "classes.ui-page" );
 
// Setter
$( ".selector" ).page( "option", "classes.ui-page", "highlight" );

closeBtn 

Type: String
Default: "left"
This option is provided by the 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:

1
2
3
 
$( ".selector" ).page({
  closeBtn: "none"
});

Get or set the closeBtn option, after initialization:

1
2
3
4
5
 
// Getter
var closeBtn = $( ".selector" ).page( "option", "closeBtn" );
 
// Setter
$( ".selector" ).page( "option", "closeBtn", "none" );

closeBtnText 

Type: String
Default: "Close"
This option is provided by the 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:

1
2
3
 
$( ".selector" ).page({
  closeBtnText: "Fermer"
});

Get or set the closeBtnText option, after initialization:

1
2
3
4
5
 
// Getter
var closeBtnText = $( ".selector" ).page( "option", "closeBtnText" );
 
// Setter
$( ".selector" ).page( "option", "closeBtnText", "Fermer" );

contentTheme 

Type: String
Default: 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".

(version deprecated: 1.4.0)
Code examples:

Initialize the page with the contentTheme option specified:

1
2
3
 
$( ".selector" ).page({
  contentTheme: "b"
});

Get or set the contentTheme option, after initialization:

1
2
3
4
5
 
// Getter
var contentTheme = $( ".selector" ).page( "option", "contentTheme" );
 
// Setter
$( ".selector" ).page( "option", "contentTheme", "b" );

corners 

Type: Boolean
Default: true
This option is provided by the 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:

1
2
3
 
$( ".selector" ).page({
  corners: false
});

Get or set the corners option, after initialization:

1
2
3
4
5
 
// Getter
var corners = $( ".selector" ).page( "option", "corners" );
 
// Setter
$( ".selector" ).page( "option", "corners", false );

defaults 

Type: 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 page with the defaults option specified:

1
2
3
 
$( ".selector" ).page({
  defaults: true
});

Get or set the defaults option, after initialization:

1
2
3
4
5
 
// Getter
var defaults = $( ".selector" ).page( "option", "defaults" );
 
// Setter
$( ".selector" ).page( "option", "defaults", true );

degradeInputs 

Type:
Default:

Note:This option is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Use $.mobile.degradeInputs instead.

(version deprecated: 1.4.0)

dialog 

Type: Boolean
Default: false
This option is provided by the 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:

1
2
3
 
$( ".selector" ).page({
  dialog: true
});

Get or set the dialog option, after initialization:

1
2
3
4
5
 
// Getter
var dialog = $( ".selector" ).page( "option", "dialog" );
 
// Setter
$( ".selector" ).page( "option", "dialog", true );

disabled 

Type: Boolean
Default: false
Disables the page if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the page with the disabled option specified:

1
2
3
 
$( ".selector" ).page({
  disabled: true
});

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).page( "option", "disabled" );
 
// Setter
$( ".selector" ).page( "option", "disabled", true );

domCache 

Type: Boolean
Default: 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:

1
2
3
 
$( ".selector" ).page({
  domCache: true
});

Get or set the domCache option, after initialization:

1
2
3
4
5
 
// Getter
var domCache = $( ".selector" ).page( "option", "domCache" );
 
// Setter
$( ".selector" ).page( "option", "domCache", true );

initSelector 

Type: Selector
Default: See below

The default initSelector for the page widget is:

1
 
":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:

1
2
3
 
$( 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)

keepNative 

Type: Selector
Default: 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.

(version deprecated: 1.4.0)
Code examples:

Initialize the page with the keepNative option specified:

1
2
3
 
$( ".selector" ).page({
  keepNative: ".do-not-enhance"
});

Get or set the keepNative option, after initialization:

1
2
3
4
5
 
// Getter
var keepNative = $( ".selector" ).page( "option", "keepNative" );
 
// Setter
$( ".selector" ).page( "option", "keepNative", ".do-not-enhance" );

keepNativeDefault 

Type: Selector
Default: ":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.

(version deprecated: 1.4.0)
Code examples:

Initialize the page with the keepNativeDefault option specified:

1
2
3
 
$( ".selector" ).page({
  keepNativeDefault: ".do-not-enhance"
});

Get or set the keepNativeDefault option, after initialization:

1
2
3
4
5
 
// Getter
var keepNativeDefault = $( ".selector" ).page( "option", "keepNativeDefault" );
 
// Setter
$( ".selector" ).page( "option", "keepNativeDefault", ".do-not-enhance" );

overlayTheme 

Type: String
Default: "a"
This option is provided by the 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:

1
2
3
 
$( ".selector" ).page({
  overlayTheme: "b"
});

Get or set the overlayTheme option, after initialization:

1
2
3
4
5
 
// Getter
var overlayTheme = $( ".selector" ).page( "option", "overlayTheme" );
 
// Setter
$( ".selector" ).page( "option", "overlayTheme", "b" );

theme 

Type: String
Default: "a"
Sets the color scheme (swatch) for 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-theme="b".

Code examples:

Initialize the page with the theme option specified:

1
2
3
 
$( ".selector" ).page({
  theme: "b"
});

Get or set the theme option, after initialization:

1
2
3
4
5
 
// Getter
var theme = $( ".selector" ).page( "option", "theme" );
 
// Setter
$( ".selector" ).page( "option", "theme", "b" );

Methods

bindRemove( callback )Returns: jQuery (plugin only)

  • callback
    Type: 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.
Code examples:

Invoke the method:

1
 
$( ".selector" ).page( "bindRemove", function() { alert( 'Page hidden' ); } );

keepNativeSelector()Returns: Selector

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.
Code examples:

Invoke the keepNativeSelector method:

1
 
$( ".selector" ).page( "keepNativeSelector" );

removeContainerBackground()Returns: jQuery (plugin only)

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.
Code examples:

Invoke the removeContainerBackground method:

1
 
$( ".selector" ).page( "removeContainerBackground" );

setContainerBackground( theme )Returns: jQuery (plugin only)

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)
Code examples:

Invoke the setContainerBackground method:

1
 
$( ".selector" ).page( "setContainerBackground", "b" );

Events

beforecreate( event )Type: pagebeforecreate

Triggered before a page is created. If one of the handlers returns false, the page is not created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the page with the beforecreate callback specified:

1
2
3
 
$( ".selector" ).page({
  beforecreate: function( event, ui ) {}
});

Bind an event listener to the pagebeforecreate event:

1
 
$( ".selector" ).on( "pagebeforecreate", function( event, ui ) {} );

create( event )Type: pagecreate

Triggered after a page has been created and enhancements to the page have been made.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the page with the create callback specified:

1
2
3
 
$( ".selector" ).page({
  create: function( event, ui ) {}
});

Bind an event listener to the pagecreate event:

1
 
$( ".selector" ).on( "pagecreate", function( event, ui ) {} );

Example:

A basic example of a page.

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
 
<!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.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.css">
  <script src="//code.jquery.com/jquery-3.2.1.min.js"></script>
  <script src="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.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>

Demo: