Page Widget

Categories: Widgets

Page Widgetversion added: 1.0

Description: Primary unit of content.

QuickNavExamples

Options

Methods

Events

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.

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.

Options

domCacheType: 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
 
$( ".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 );

keepNativeDefaultType: String

Default: :jqmData(role='none'), :jqmData(role='nojs')

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:

1
 
$( ".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" );

themeType: String

Default: c

Sets the swatch that will be used to draw the page.

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

Code examples:

Initialize the page with the theme option specified:

1
 
$( ".selector" ).page({ theme: "a" });

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", "a" );

Methods

keepNativeSelector()Returns: jQuery (plugin only)

Returns the selector used to filter elements which are not to be enhanced.
  • This method does not accept any arguments.
Code examples:

Invoke the keepNativeSelector method:

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

removeContainerBackground()Returns: jQuery (plugin only)

Removes the background swatch from the page widget's container (usually the body).
  • This method does not accept any arguments.
Code examples:

Invoke the removeContainerBackground method:

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

setContainerBackground( theme )Returns: jQuery (plugin only)

Sets a new background swatch for the page widget's container (usually the body).
Code examples:

Invoke the setContainerBackground method:

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

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. jQuery Mobile will use this event to apply its enhancements to the page.

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="http://code.jquery.com/mobile/1.3.2/jquery.mobile-1.3.2.min.css">
  <script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>
  <script src="http://code.jquery.com/mobile/1.3.2/jquery.mobile-1.3.2.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div data-role="header">
    <h1>Page header (optional): Example page</h1>
  </div>
  <div data-role="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: