Toolbar Widgetversion added: 1.4
Description: Adds toolbars to the top and/or bottom of the page.
Toolbars
Headers and footers are elements that precede resp. succeed the page content. The toolbar widget allows you to create headers and footers.
Headers
The header bar serves as the page title, is usually the first element inside each mobile page, and typically contains a page title and up to two buttons.
Header structure
The header is a toolbar at the top of the page that usually contains the page title text and optional buttons positioned to the left and/or right of the title for navigation or actions. Headers can optionally be positioned as fixed so they remain at the top of the screen at all times instead of scrolling with the page.
The title text is normally an H1 heading element but it's possible to use any heading level (H1-H6) to allow for semantic flexibility. For example, a page containing multiple mobile "pages" may use a H1 element on the home "page" and a H2 element on the secondary pages. All heading levels are styled identically by default to maintain visual consistency.
1
2
3
|
|
Default header features
The header toolbar inherits its theme swatch from the page by default but you can easily set the theme swatch color by adding the data-theme
attribute to the header. For example, data-theme="b"
. When you use external headers you must set a theme, because there is no parent page from which it can inherit a theme.
Adding buttons
Note: The behavior whereby anchor elements are automatically enhanced as buttons is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must add button classes if you wish to style them as buttons.
In the standard header configuration, there are slots for buttons on either side of the text heading. Each button is typically an a
(anchor) element or a button
element that has the attribute data-role="button"
set. To save space, buttons in toolbar widgets are set to inline styling so the button is only as wide as the text and icons it contains.
Default button positioning
Note: The behavior whereby the first two buttons automatically get the ui-btn-left
and ui-btn-right
classes is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must add those classes in your markup if you wish to position the buttons left and/or right.
The toolbar plugin looks for immediate children of the header container, and automatically sets the first link in the left button slot and the second link in the right. In this example, the 'Cancel' button will appear in the left slot and 'Save' will appear in the right slot based on their sequence in the source order.
1
2
3
4
5
|
|
Making buttons visually stand out
Buttons automatically adopt the swatch color of the bar they sit in, so a link in a header bar with the "a" color will also be styled as "a" colored buttons. It's simple to make a button visually stand out. Here, we add the data-theme
attribute and set the color swatch for the button to "b" to make the "Save" button stand out.
1
2
3
4
5
|
|
Controlling button position with classes
The button position can also be controlled by adding classes to the button anchors, rather than relying on source order. This is especially useful if you only want a button in the right slot. To specify the button position, add the class of ui-btn-left
or ui-btn-right
to the anchor.
1
2
3
4
|
|
Adding buttons to toolbar widgets without heading
The heading in the header bar has some margin that will give the bar its height. If you choose not to use a heading, you will need to add an element with class="ui-title"
so that the bar can get the height and display correctly.
1
2
3
4
|
|
Adding Back buttons
Note: The options addBackBtn
, backBtnTheme
, and backBtnText
have moved from the page widget to the toolbar widget as of jQuery Mobile 1.4.0.
jQuery Mobile has a feature to automatically create and append "back" buttons to any header, though it is disabled by default. This is primarily useful in chromeless installed applications, such as those running in a native app webview. The framework automatically generates a "back" button on a header when the toolbar plugin's addBackBtn
option is true. This can also be set via markup if the header div has a data-add-back-btn="true"
attribute.
If you use the attribute data-rel="back"
on an anchor, any clicks on that anchor will mimic the back button, going back one history entry and ignoring the anchor's default href. This is particularly useful when linking back to a named page, such as a link that says "home", or when generating "back" buttons with JavaScript, such as a button to close a dialog. When using this feature in your source markup, be sure to provide a meaningful href that actually points to the URL of the referring page. This will allow the feature to work for users in C-Grade browsers.
If you just want a reverse transition without actually going back in history, you should use the data-direction="reverse"
attribute.
Customizing the back button text
If you'd like to configure the back button text, you can either use the data-back-btn-text="previous"
attribute on your toolbar element, or set it programmatically via the toolbar plugin's options: $.mobile.toolbar.prototype.options.backBtnText = "previous";
Default back button style
If you'd like to configure the back button role-theme, you can use: $.mobile.toolbar.prototype.options.backBtnTheme = "a";
If you're doing this programmatically, set this option inside the mobileinit event handler.
Custom header configurations
If you need to create a header that doesn't follow the default configuration, simply wrap your custom styled markup in any container, such as div
. The plugin won't apply the automatic button logic to the wrapped content inside the header container so you can write custom styles for laying out the content in your header.
It's also possible to create custom bars without using the header data-role at all. For example, start with any container and add the ui-bar
class to apply standard bar padding and add the ui-bar-b
class to assign the bar swatch styles from your theme. (The "b" can be any swatch letter.)
1
2
3
|
|
Note that .ui-bar
should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap its contents in an element and apply the padding to that element instead.
By writing some simple styles, it's easy to build message bars like this:
Footers
The footer bar is usually the last element inside each mobile page, and tends to be more freeform than the header in terms of content and functionality, but typically contains a combination of text and buttons.Footer bar structure
The footer
bar has the same basic structure as the header except it uses the data-role
attribute value of footer
.
1
2
3
|
|
The footer toolbar inherits its theme swatch from the page by default but you can easily set the theme swatch color by adding the data-theme
attribute to the header. For example, data-theme="b"
. When you use external headers you must set a theme, because there is no parent page from which it can inherit a theme.
The page footer is very similar to the header in terms of options and configuration. The primary difference is that the footer is designed to be less structured than the header to allow more flexibility, so the framework doesn't automatically reserve slots for buttons to the left or right as it does in headers.
Since footers do not have the same prescriptive markup conventions as headers, we recommend using layout grids or writing custom styles to achieve the design you want.
Adding buttons
Note: The behavior whereby anchor elements are automatically enhanced as buttons is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must set the attribute data-role="button"
on those anchors you wish the framework to enhance as buttons.
Any link or valid button markup with a data-role="button"
attribute added to the footer will automatically be turned into a button. To save space, buttons in toolbar widgets are automatically set to inline styling so the button is only as wide as the text and icons it contains.
By default, toolbar widgets don't have any padding to accommodate nav bars and other widgets. To include padding on the bar, add a class="ui-bar"
to the footer.
1
2
3
4
5
|
|
This creates this toolbar with buttons sitting in a row
Note that .ui-bar
should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap the contents of the toolbar widget in an element and apply the padding to that element.
To group buttons together into a button set, wrap the links in a wrapper with data-role="controlgroup"
and data-type="horizontal"
attributes.
1
|
|
This creates a grouped set of buttons:
Adding form elements
Form elements and other content can also be added to toolbars. Here is an example of a select menu inside a footer bar. We recommend using mini-sized form elements in toolbars by adding the data-mini="true"
attribute:
Fixed & Persistent footers
In situations where the footer is a global navigation element, you may want it to appear fixed so it doesn't scroll out of view. It's also possible to make a fixed toolbar persistent so it appears to not move between page transitions. This can be accomplished by using the persistent footer feature included in jQuery Mobile.
To make a footer persistent between transitions, add the data-id
attribute to the footer of all relevant pages and use the same id
value for each. For example, by adding data-id="myfooter"
to the current page and the target page, the framework will keep the footer anchors in the same spot during the page animation. This effect will only work correctly if the header and footer toolbars are set to data-position="fixed"
so they are in view during the transition.
Fixed toolbars
In browsers that support CSS position: fixed
(most desktop browsers, iOS5+, Android 2.2+, BlackBerry 6, and others), toolbar widgets that use the "fixedtoolbar" plugin will be fixed to the top or bottom of the viewport, while the page content scrolls freely in between. In browsers that don't support fixed positioning, the toolbars will remain positioned in flow, at the top or bottom of the page.
To enable this behavior on a header or footer, add the data-position="fixed"
attribute to a jQuery Mobile toolbar element.
Fixed header markup example:
1
2
3
|
|
Fixed footer markup example:
1
2
3
|
|
Note: When you dynamically inject a fixed toolbar into the active page, you must afterwards call $.mobile.resetActivePageHeight();
to ensure that the page height remains correct. An example illustrates this.
Fullscreen Toolbars
Fullscreen fixed toolbars sit on top of the content at all times when they are visible, and unlike regular fixed toolbars, fullscreen toolbars do not fall back to static positioning when toggled. Instead they disappear from the screen entirely. Fullscreen toolbars are ideal for more immersive interfaces, like a photo viewer that is meant to fill the entire screen with the photo itself and no distractions.
To enable this option on a fixed header or footer, add the data-fullscreen
attribute to the element.
1
2
3
|
|
Forms in toolbars
While all form elements are now tested to work correctly within static toolbars as of jQuery Mobile 1.1, we recommend extensive testing when using form elements within fixed toolbars or within any position: fixed
elements. This can potentially trigger a number of unpredictable issues in various mobile browsers, Android 2.2/2.3 in particular (detailed in Known issues in Android 2.2/2.3, below).
Changes in jQuery Mobile 1.1
Prior to version 1.1, jQuery Mobile used dynamically re-positioned toolbars for the fixed header effect because very few mobile browsers supported the position:fixed
CSS property, and simulating fixed support through the use of "fake" JavaScript overflow-scrolling behavior would have reduced our browser support reach, in addition to feeling unnatural on certain platforms. This behavior was not ideal, and jQuery Mobile 1.1 took a new approach to fixed toolbars that allows much broader support. The framework now offers true fixed toolbars on many popular platforms, while gracefully degrading non-supporting platforms to static positioning.
Polyfilling older platforms
The fixed toolbar plugin degrades gracefully on platforms that do not support CSS position:fixed
properly, such as iOS4.3. If you still need to support fixed toolbars on that platform (with the show/hide behavior) included in previous releases, Filament Group has developed a polyfill that you can use.
- Github code repository with CSS, and JavaScript required for the fixed toolbars polyfill
- Preview URL using the code in the repo above
Just include the CSS and JS files after your references to jQuery Mobile and Fixed toolbars will work similarly to jQuery Mobile 1.0 on iOS4.3, with the inclusion of the new API for the 1.1 fixedtoolbar plugin.
If you have any improvements to suggest, fork the gist on github and let us know!
Known issue with form controls inside fixed toolbars, and programmatic scroll
An obscure issue exists in iOS5 and some Android platforms where form controls placed inside fixed-positioned containers can lose their hit area when the window is programatically scrolled (using window.scrollTo
for example). This is not an issue specific to jQuery Mobile, but because of it, we recommend not programatically scrolling a document when using form controls inside jQuery Mobile fixed toolbars. This ticket from the Device Bugs project tracker explains this problem in more detail.
Known issues in Android 2.2/2.3
Android 2.2/2.3's implementation of position: fixed;
can, in conjunction with seemingly unrelated styles and markup patterns, cause a number of strange issues, particularly in the case of position: absolute
elements inside of position: fixed
elements. While we've done our best to work around a number of these unique bugs within the scope of the library, custom styles may cause a number of issues.
- Form elements elsewhere on the page - select menus in particular - can fail to respond to user interaction when an empty absolute positioned element is placed within a fixed position element. In rare cases—and specific to Android 2.2—this can cause entire pages to fail to respond to user interaction. This can seemingly be solved by adding any character to the absolute positioned element, including a non-breaking space, and in some cases even whitespace.
- The above-described issue can also be triggered by an absolute positioned image inside of a fixed position element, but only when that image is using something other than its inherent dimensions. If a height or width is specified on the image using CSS, or the image src is invalid (thus having no inherent height and width), this issue can occur. If an image that is inherently, say, 50x50 pixels is placed in a fixed element and left at its inherent dimensions, this issue does not seem to occur.
- When a
position: fixed
element appears anywhere on a page, most 2D CSS transforms will fail. Oddly, onlytranslate
transforms seem unaffected by this. Even more oddly, this issue is solved by setting a CSSopacity
of .9 or below on the parent of the fixed element. - Combinations of
position: fixed
and overflow properties are best avoided, as both have been known to cause unpredictable issues in older versions of Android OS. - Any element that triggers the on-screen keyboard, when placed inside a
position: fixed
element, will fail to respond to user input when using anything other than the default keyboard. This includes Swype, XT9 or, it seems, any input method apart from the standard non-predictive keyboard.
While we will continue to try to find ways to mitigate these bugs as best we can, we currently advise against implementing fixed toolbars containing complicated user styles and form elements without extensive testing in all versions of Android's native browser.
No longer supported: touchOverflowEnabled
Prior to jQuery Mobile 1.1, true fixed toolbar support was contingent on native browser support for the CSS property overflow-scrolling: touch
, which is currently only supported in iOS5. As of version 1.1, jQuery Mobile no longer uses this CSS property at all. We've removed all internal usage of this property in the framework, but we've left it defined globally on the $.mobile object to reduce the risk that its removal will cause trouble with existing applications. This property is flagged for removal, so please update your code to no longer use it. The support test for this property, however, remains defined under $.support
and we have no plans to remove that test at this time.
Options
addBackBtn
false
This option only affects header toolbar widgets.
This option is also exposed as a data attribute: data-add-back-btn="true"
.
Initialize the toolbar with the addBackBtn
option specified:
1
2
3
|
|
Get or set the addBackBtn
option, after initialization:
1
2
3
4
5
|
|
backBtnText
"Back"
This option only affects header toolbar widgets.
This option is also exposed as a data attribute: data-back-btn-text="Previous"
.
Initialize the toolbar with the backBtnText
option specified:
1
2
3
|
|
Get or set the backBtnText
option, after initialization:
1
2
3
4
5
|
|
backBtnTheme
null, inherited from parent
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-back-btn-theme="b"
.
Initialize the toolbar with the backBtnTheme
option specified:
1
2
3
|
|
Get or set the backBtnTheme
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 toolbar with the defaults
option specified:
1
2
3
|
|
Get or set the defaults
option, after initialization:
1
2
3
4
5
|
|
disablePageZoom
true
fixedToolbar
extension.
Sets whether to disable page zoom whenever the page containing the fixed toolbar is shown.
This option is also exposed as a data attribute: data-disable-page-zoom="false"
.
Initialize the toolbar with the disablePageZoom
option specified:
1
2
3
|
|
Get or set the disablePageZoom
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 toolbar with the disabled
option specified:
1
2
3
|
|
Get or set the disabled
option, after initialization:
1
2
3
4
5
|
|
fullscreen
false
fixedToolbar
extension.
Sets whether the toolbar should be hidden entirely when the page is tapped.
This option is also exposed as a data attribute: data-fullscreen="true"
.
Initialize the toolbar with the fullscreen
option specified:
1
2
3
|
|
Get or set the fullscreen
option, after initialization:
1
2
3
4
5
|
|
hideDuringFocus
"input, textarea, select"
fixedToolbar
extension.
The value of this option is a CSS selector for those elements that, when focused, should cause the fixed toolbar to be hidden and conversely, to be shown upon loss of focus.
This option is also exposed as a data attribute: data-hide-during-focus="button"
.
Initialize the toolbar with the hideDuringFocus
option specified:
1
2
3
|
|
Get or set the hideDuringFocus
option, after initialization:
1
2
3
4
5
|
|
position
null
fixedToolbar
extension.
Causes the toolbar to float above the content via CSS position: fixed
when set to "fixed".
This option is also exposed as a data attribute: data-position="fixed"
.
Initialize the toolbar with the position
option specified:
1
2
3
|
|
Get or set the position
option, after initialization:
1
2
3
4
5
|
|
supportBlacklist
default blacklist
fixedToolbar
extension.
The value of this option is a function that will return true
on platforms where toolbar widgets should not be displayed as fixed.
The default value of this option is a function that returns true
whenever the value of $.support.fixedPosition
is false
.
tapToggle
true
fixedToolbar
extension.
Sets whether the fixed toolbar's visibility can be toggled by tapping on the page.
This option is also exposed as a data attribute: data-tap-toggle="false"
.
Initialize the toolbar with the tapToggle
option specified:
1
2
3
|
|
Get or set the tapToggle
option, after initialization:
1
2
3
4
5
|
|
tapToggleBlacklist
"a, button, input, select, textarea, .ui-header-fixed, .ui-footer-fixed, .ui-flipswitch, .ui-popup, .ui-panel, .ui-panel-dismiss-open"
fixedToolbar
extension.
When the user taps on the page and the tapToggle
option is set on the fixed toolbar widget, the element on which the user has tapped is examined before the visibility of the toolbar is toggled. If the element on which the user has tapped matches the selector provided as the value of this option, then the toolbar is not toggled.
This option is also exposed as a data attribute: data-tap-toggle-blacklist=".do-not-toggle-fixed-toolbar"
.
Initialize the toolbar with the tapToggleBlacklist
option specified:
1
2
3
|
|
Get or set the tapToggleBlacklist
option, after initialization:
1
2
3
4
5
|
|
theme
null, inherited from parent
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b"
.
Initialize the toolbar with the theme
option specified:
1
2
3
|
|
Get or set the theme
option, after initialization:
1
2
3
4
5
|
|
trackPersistentToolbars
true
fixedToolbar
extension.
Whether to persist the toolbar across pages.
This option is also exposed as a data attribute: data-track-persistent-toolbars="false"
.
Initialize the toolbar with the trackPersistentToolbars
option specified:
1
2
3
|
|
Get or set the trackPersistentToolbars
option, after initialization:
1
2
3
4
5
|
|
transition
"slide"
fixedToolbar
extension.
The transition to apply when showing/hiding the fixed toolbar.
The following values are recognized:
"none" | The fixed toolbar appears and disappears abruptly, without any transition. |
"slide" | The fixed |
"fade" | The fixed |
Initialize the toolbar with the transition
option specified:
1
2
3
|
|
Get or set the transition
option, after initialization:
1
2
3
4
5
|
|
updatePagePadding
true
fixedToolbar
extension.
Whether to set the page content div's top and bottom padding to the height of the toolbar.
This option is also exposed as a data attribute: data-update-page-padding="false"
.
Initialize the toolbar with the updatePagePadding
option specified:
1
2
3
|
|
Get or set the updatePagePadding
option, after initialization:
1
2
3
4
5
|
|
visibleOnPageShow
true
fixedToolbar
extension.
Whether the toolbar is shown along with the page.
This option is also exposed as a data attribute: data-visible-on-page-show="false"
.
Initialize the toolbar with the visibleOnPageShow
option specified:
1
2
3
|
|
Get or set the visibleOnPageShow
option, after initialization:
1
2
3
4
5
|
|
Methods
destroy()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the destroy method:
1
|
|
disable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the disable method:
1
|
|
enable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the enable method:
1
|
|
hide()Returns: jQuery (plugin only)
fixedToolbar
extension.
Hides the toolbar.
- This method does not accept any arguments.
Invoke the hide method:
1
|
|
option( optionName )Returns: Object
optionName
.-
optionNameType: StringThe name of the option to get.
Invoke the method:
1
|
|
option()Returns: PlainObject
- This signature does not accept any arguments.
Invoke the method:
1
|
|
option( optionName, value )Returns: jQuery (plugin only)
optionName
.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
|
option( options )Returns: jQuery (plugin only)
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
|
refresh()Returns: jQuery (plugin only)
If you manipulate a toolbar via JavaScript, you must call the refresh
method on it to update the visual styling.
- This method does not accept any arguments.
Invoke the refresh method:
1
|
|
show()Returns: jQuery (plugin only)
fixedToolbar
extension.
Shows the toolbar.
- This method does not accept any arguments.
Invoke the show method:
1
|
|
toggle()Returns: jQuery (plugin only)
fixedToolbar
extension.
Calls either the show or the hide method, depending on whether the toolbar is visible.
- This method does not accept any arguments.
Invoke the toggle method:
1
|
|
updatePagePadding()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the updatePagePadding method:
1
|
|
Events
create( event, ui )Type: toolbarcreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the toolbar with the create callback specified:
1
2
3
|
|
Bind an event listener to the toolbarcreate event:
1
|
|
Examples:
A basic example of a header
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
|
Demo:
A basic example of a page with fixed toolbars.
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
29
30
31
32
33
34
35
|
|
Demo:
Injecting a fixed toolbar
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
29
30
31
32
33
|
|