Fixedtoolbar Widget

Categories: Widgets

Fixedtoolbar Widgetversion added: 1.0

Description: Creates a fixedtoolbar

QuickNavExamples

Options

Methods

Events

In browsers that support CSS position: fixed (most desktop browsers, iOS5+, Android 2.2+, BlackBerry 6, and others), toolbars 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 header or footer element.

Fixed header markup example:

1
2
3
 
<div data-role="header" data-position="fixed">
  <h1>Fixed Header</h1>
</div>

Fixed footer markup example:

1
2
3
 
<div data-role="footer" data-position="fixed">
  <h1>Fixed Footer</h1>
</div>

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
 
<div data-role="header" data-position="fixed" data-fullscreen="true">
  <h1>Fixed Header!</h1>
</div>

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 in 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.

Just include the CSS and JS files after your references to jQuery Mobile and Fixed toolbars will work similarly to jQuery Mobile 1.0 in 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, only translate transforms seem unaffected by this. Even more oddly, this issue is solved by setting a CSS opacity 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

disablePageZoomType: Boolean

Default: true
This determines whether user-scaling should be disabled on pages that contain fixed toolbars.

This option is also exposed as a data attribute: data-disable-page-zoom="false".

Code examples:

Initialize the fixedtoolbar with the disablePageZoom option specified:

1
 
$( ".selector" ).fixedtoolbar({ disablePageZoom: false });

Get or set the disablePageZoom option, after initialization:

1
2
3
4
5
 
// getter
var disablePageZoom = $( ".selector" ).fixedtoolbar( "option", "disablePageZoom" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "disablePageZoom", false );

fullscreenType: Boolean

Default: false
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.

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

Note: While the data attribute syntax for this option has not changed, it is now only supported on the toolbar element itself, and not the page element.
Code examples:

Initialize the fixedtoolbar with the fullscreen option specified:

1
 
$( ".selector" ).fixedtoolbar({ fullscreen: true });

Get or set the fullscreen option, after initialization:

1
2
3
4
5
 
// getter
var fullscreen = $( ".selector" ).fixedtoolbar( "option", "fullscreen" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "fullscreen", true );

hideDuringFocusType: String

Default: "input, select, textarea"
A list of jQuery selectors that should cause the toolbars to hide while focused, except if they are in a fixed toolbar.
Code examples:

Initialize the fixedtoolbar with the hideDuringFocus option specified:

1
 
$( ".selector" ).fixedtoolbar({ hideDuringFocus: "input, select, textarea" });

Get or set the hideDuringFocus option, after initialization:

1
2
3
4
5
 
// getter
var hideDuringFocus = $( ".selector" ).fixedtoolbar( "option", "hideDuringFocus" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "hideDuringFocus", "input, select, textarea" );

initSelectorType: CSS selector string

Default: ":jqmData(position='fixed')"
This is used to define the selectors (element types, data roles, etc.) that will automatically be initialized as fixed toolbars. To change which elements are initialized, bind this option to the mobileinit event:
1
2
3
 
$( document ).on( "mobileinit", function() {
  $.mobile.fixedtoolbar.prototype.options.initSelector = ".myselector";
});

supportBlacklistType: Function()

Default: function that returns a boolean value
CSS position: fixed support is very difficult to test; in fact, at the time of version 1.1 release, there was no known way to reasonably test for fixed support without turning up false positives or negatives in certain popular browsers. This option is a function that attempts to opt-out some popular platforms that are known to be troublesome with position: fixed . Often, these platforms support position: fixed partially, which can be worse than not supporting it at all. If overriding this option with your own blacklist logic, you simply need to provide a function that returns a true or false result when called upon initialization. You must set it on mobileinit, so that it applies when the plugin is initially created.
1
2
3
4
5
6
7
 
$( document ).on( "mobileinit", function() {
  $.mobile.fixedtoolbar.prototype.options.supportBlacklist = function() {
    var result;
    // logic to determine whether result should be true or false
    return result;
  };
})
Code examples:

Initialize the fixedtoolbar with the supportBlacklist option specified:

1
 
$( ".selector" ).fixedtoolbar({ supportBlacklist: "arrow-d" });

Get or set the supportBlacklist option, after initialization:

1
2
3
4
5
 
// getter
var supportBlacklist = $( ".selector" ).fixedtoolbar( "option", "supportBlacklist" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "supportBlacklist", "arrow-d" );

tapToggleType: Boolean

Default: true
Enable or disable the user's ability to toggle toolbar visibility with a tap on the screen (or a click, for mouse users).

This option is also exposed as a data attribute: data-tap-toggle="false".

Note: This behavior was formerly configurable as follows, but as of version 1.1 this syntax is no longer supported:
$.mobile.fixedToolbars.setTouchToggleEnabled(false);
Code examples:

Initialize the fixedtoolbar with the tapToggle option specified:

1
 
$( ".selector" ).fixedtoolbar({ tapToggle: false });

Get or set the tapToggle option, after initialization:

1
2
3
4
5
 
// getter
var tapToggle = $( ".selector" ).fixedtoolbar( "option", "tapToggle" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "tapToggle", false );

tapToggleBlacklistType: String

Default: "a, button, input, select, textarea, .ui-header-fixed, .ui-footer-fixed"
A list of jQuery selectors that, when tapped, will not cause the toolbars to be toggled.
Code examples:

Initialize the fixedtoolbar with the tapToggleBlacklist option specified:

1
 
$( ".selector" ).fixedtoolbar({ tapToggleBlacklist: "a, button, input, select, textarea, .ui-header-fixed, .ui-footer-fixed" });

Get or set the tapToggleBlacklist option, after initialization:

1
2
3
4
5
 
// getter
var tapToggleBlacklist = $( ".selector" ).fixedtoolbar( "option", "tapToggleBlacklist" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "tapToggleBlacklist", "a, button, input, select, textarea, .ui-header-fixed, .ui-footer-fixed" );

transitionType: String

Default: slide (which ends up using slideup and slidedown)
The transition that should be used for showing and hiding a fixed toolbar. Possible values are "none", "fade", and "slide" (or you can write a CSS transition of your own and use that too).

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

Code examples:

Initialize the fixedtoolbar with the transition option specified:

1
 
$( ".selector" ).fixedtoolbar({ transition: fade });

Get or set the transition option, after initialization:

1
2
3
4
5
 
// getter
var transition = $( ".selector" ).fixedtoolbar( "option", "transition" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "transition", fade );

updatePagePaddingType: Boolean

Default: true
Since toolbars can vary in height depending on the content they contain, this option automatically updates the padding on the page element to ensure that fixed toolbars have adequate space in the document when they are statically positioned, and when scrolled to the top or bottom of the page. When enabled, the padding updates during many operations, such as pageshow, during page transitions, and on resize and orientationchange. As an optimization, we would recommend that you consider disabling this option and adding a rule to your CSS to set the padding of the page div to match the EM height of your toolbars, such as .ui-page-header-fixed { padding-top: 4.5em; }.

This option is also exposed as a data attribute: data-update-page-padding="false".

Code examples:

Initialize the fixedtoolbar with the updatePagePadding option specified:

1
 
$( ".selector" ).fixedtoolbar({ updatePagePadding: false });

Get or set the updatePagePadding option, after initialization:

1
2
3
4
5
 
// getter
var updatePagePadding = $( ".selector" ).fixedtoolbar( "option", "updatePagePadding" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "updatePagePadding", false );

visibleOnPageShowType: Boolean

Default: true
This determines whether the toolbar is visible or not when its parent page is shown.

This option is also exposed as a data attribute: data-visible-on-page-show="false".

Code examples:

Initialize the fixedtoolbar with the visibleOnPageShow option specified:

1
 
$( ".selector" ).fixedtoolbar({ visibleOnPageShow: false });

Get or set the visibleOnPageShow option, after initialization:

1
2
3
4
5
 
// getter
var visibleOnPageShow = $( ".selector" ).fixedtoolbar( "option", "visibleOnPageShow" );
 
// setter
$( ".selector" ).fixedtoolbar( "option", "visibleOnPageShow", false );

Methods

destroy()Returns: jQuery (plugin only)

destroy at fixedtoolbar (restore the element to its initial state)
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).fixedtoolbar( "destroy" );

hide()Returns: jQuery (plugin only)

hide the toolbar (if it's not a fullscreen toolbar, it'll toggle back to static positioning, which may or may not be hidden from view depending on scroll)
  • This method does not accept any arguments.
Code examples:

Invoke the hide method:

1
 
$( ".selector" ).fixedtoolbar( "hide" );

show()Returns: jQuery (plugin only)

show the toolbar

Note: Prior to version 1.1, the following syntax was used to show the toolbars, but it is no longer supported:
$.mobile.fixedToolbars.show(true);

  • This method does not accept any arguments.
Code examples:

Invoke the show method:

1
 
$( ".selector" ).fixedtoolbar( "show" );

toggle()Returns: jQuery (plugin only)

calls either the show or the hide method, depending on whether the toolbar is visible.
  • This method does not accept any arguments.
Code examples:

Invoke the toggle method:

1
 
$( ".selector" ).fixedtoolbar( "toggle" );

updatePagePadding()Returns: jQuery (plugin only)

update the padding (either top or bottom, depending on if the toolbar is a header or a footer) of the page element parent of the toolbar to match the height of the toolbar.

There is also an updatelayout event that can be used to trigger the toolbars to re-position. Developers who are building dynamic applications that inject content into the current page can also manually trigger this updatelayout event to ensure components on the page update in response to the new content that was just added. This event is used internally in the collapsible and listview filter plugins and is powerful because it's not toolbar-specific -- any widget can be built to listen for the updatelayout event to update the widget in response.

  • This method does not accept any arguments.
Code examples:

Invoke the updatePagePadding method:

1
 
$( ".selector" ).fixedtoolbar( "updatePagePadding" );

Events

create( event, ui )Type: fixedtoolbarcreate

Triggered when a fixed toolbar is created

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

Code examples:

Initialize the fixedtoolbar with the create callback specified:

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

Bind an event listener to the fixedtoolbarcreate event:

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

Example:

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
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>fixedtoolbar 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" data-position="fixed" data-theme="a">
    <h1>Fixed Header</h1>
  </div>
  <div data-role="content" >
    <p>This page demonstrates the "fixed" toolbar mode. </p>
    <br /><br />
    <p>To enable this toolbar feature type, you apply the <code>data-position="fixed"</code> attribute to both the header and footer <code>div</code> elements.</p>
    <br /><br />
    <p>And we're adding more text here so that you can really see the fixed toobars in action.</p>
    <br /><br />
    <p>If you tap the screen while in the middle of the page (i.e. neither at the top nor the bottom of the page, the visibility of the toolbars will toggle</p>
    <p></p>
  </div>
    <div data-role="footer" data-theme="a" data-position="fixed">
    <h1>Fixed Footer</h1>
  </div>
</div>
 
</body>
</html>

Demo: