Page Widgetversion added: 1.0
Description: Primary unit of content.
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
|
|
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
|
|
You can also simply go back:
1
|
|
Options
closeBtn
"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
.
Initialize the page with the closeBtn
option specified:
1
2
3
|
|
Get or set the closeBtn
option, after initialization:
1
2
3
4
5
|
|
closeBtnText
"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"
.
Initialize the page with the closeBtnText
option specified:
1
2
3
|
|
Get or set the closeBtnText
option, after initialization:
1
2
3
4
5
|
|
contentTheme
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"
.
Initialize the page with the contentTheme
option specified:
1
2
3
|
|
Get or set the contentTheme
option, after initialization:
1
2
3
4
5
|
|
corners
true
dialog
extension.
Sets whether to draw the dialog with rounded corners.
This option is also exposed as a data attribute: data-corners="false"
.
Initialize the page with the corners
option specified:
1
2
3
|
|
Get or set the corners
option, after initialization:
1
2
3
4
5
|
|
defaults
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"
.
Initialize the page with the defaults
option specified:
1
2
3
|
|
Get or set the defaults
option, after initialization:
1
2
3
4
5
|
|
degradeInputs
Note:This option is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Use $.mobile.degradeInputs
instead.
dialog
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"
.
Initialize the page with the dialog
option specified:
1
2
3
|
|
Get or set the dialog
option, after initialization:
1
2
3
4
5
|
|
disabled
false
true
.
This option is also exposed as a data attribute: data-disabled="true"
.
Initialize the page with the disabled
option specified:
1
2
3
|
|
Get or set the disabled
option, after initialization:
1
2
3
4
5
|
|
domCache
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"
.
Initialize the page with the domCache
option specified:
1
2
3
|
|
Get or set the domCache
option, after initialization:
1
2
3
4
5
|
|
initSelector
See below
The default initSelector
for the page widget is:
1
|
|
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
|
|
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
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
.
Initialize the page with the keepNative
option specified:
1
2
3
|
|
Get or set the keepNative
option, after initialization:
1
2
3
4
5
|
|
keepNativeDefault
":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
.
Initialize the page with the keepNativeDefault
option specified:
1
2
3
|
|
Get or set the keepNativeDefault
option, after initialization:
1
2
3
4
5
|
|
overlayTheme
"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"
.
Initialize the page with the overlayTheme
option specified:
1
2
3
|
|
Get or set the overlayTheme
option, after initialization:
1
2
3
4
5
|
|
theme
"a"
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b"
.
Initialize the page with the theme
option specified:
1
2
3
|
|
Get or set the theme
option, after initialization:
1
2
3
4
5
|
|
Methods
bindRemove( callback )Returns: jQuery (plugin only)
-
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:
1
|
|
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.
Invoke the keepNativeSelector method:
1
|
|
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.
Invoke the removeContainerBackground method:
1
|
|
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)-
themeType: String
Invoke the setContainerBackground method:
1
|
|
Events
beforecreate( event )Type: 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:
1
2
3
|
|
Bind an event listener to the pagebeforecreate event:
1
|
|
create( event )Type: 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:
1
2
3
|
|
Bind an event listener to the pagecreate event:
1
|
|
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
|
|