Fixed toolbars

• Basics
• Options
• Methods
• Events

The fixedtoolbar plugin has the following options:

visibleOnPageShow 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"

$("[data-role=header]").fixedtoolbar({ visibleOnPageShow: false });

disablePageZoom 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"

$("[data-role=header]").fixedtoolbar({ disablePageZoom: false });

transition 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"

$("[data-role=header]").fixedtoolbar({ transition: "fade" });

fullscreen 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 page demonstrates toolbars that use the fullscreen option. This option is also exposed as a data attribute: data-fullscreen="true"

$("[data-role=header]").fixedtoolbar({ 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.

tapToggle 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="true"

$("[data-role=header]").fixedtoolbar({ tapToggle: true });

Note: This behavior was formerly configurable as follows, but as of version 1.1 this syntax is no longer supported:

	
$.mobile.fixedToolbars
   .setTouchToggleEnabled(false);

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

$("[data-role=header]").fixedtoolbar({ tapToggleBlacklist: "a, button, input, select, textarea, .ui-header-fixed, .ui-footer-fixed" });

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

$("[data-role=header]").fixedtoolbar({ hideDuringFocus: "input, select, textarea" });

updatePagePadding 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"

$("[data-role=header]").fixedtoolbar({ updatePagePadding: false });

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

$( document ).bind("mobileinit", function(){
  $.mobile.fixedtoolbar.prototype.options.supportBlacklist = function(){
    var result;
    // logic to determine whether result should be true or false
    return result;
  };
})

initSelector 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:

$( document ).bind( "mobileinit", function(){
	$.mobile.fixedtoolbar.prototype.options.initSelector = ".myselector";
});