Toolbars

Contact Us or call 1-877-932-8228
Toolbars

Toolbars

Many jQuery Mobile pages will show a header and footer toolbar, at top and bottom, respectively. The header bar typically shows the page title and, often, a navigation bar; the header bar on some interior pages may show a "back" button. The footer bar is usually the last element on a page.

Header Toolbars

All of the jQuery Mobile pages we've seen so far have had a header toolbar - it would be nice if, on interior pages, we included a "back" button for the user to easily return to the previous page. Adding a "back" button is pretty easy: insert data-add-back-btn="true" to the data-role="page" div. We can also easily add one or two buttons to the header toolbar. Add buttons as children of the data-role="header" element and use appropriate classes to align the buttons to the left or the right of the title (ui-btn-left or ui-btn-right) and to set the buttons as inline and mini. (Note that versions of jQuery Mobile prior to 1.4 positioned the first included button left and the second one right, with all buttons included in the headers styled as "mini" and "inline"; this behavior has been deprecated as of version 1.4.)

headerbars

The left screenshot shows a page with a header with attribute data-add-back-btn="true". The right screenshot shows a header with two buttons, links to "Home" and "Page 1".

Open WidgetsUI/Demos/toolbars/index.html in a mobile browser and in a file editor to view the code, to view this example.

The div with id page1 has attribute data-add-back-btn="true" - this adds the back button to Page 1.

<div data-role="page" id="page1" data-add-back-btn="true">

Page 2's page div doesn't have attribute data-add-back-btn="true"; instead, we add the buttons "manually" to the header:

<div data-role="header">
	<a href="#home" class="ui-btn-left ui-btn ui-btn-inline ui-mini ui-corner-all ui-btn-icon-left ui-icon-home">Home</a>
	<h2>N&amp;B: Page 2</h2>
	<a href="#page1" class="ui-btn-right ui-btn ui-btn-inline ui-mini ui-corner-all ui-btn-icon-left ui-icon-grid">Page 1</a>
</div>

Footer Toolbar

Footer toolbars work pretty much the same as headers and are a logical place to put contact information, navigation elements, or other show-on-every-page content. Check out WidgetsUI/Demos/toolbars/footer.html - we've added several buttons, with the appropriate classes, to each of the interior pages (#page1 and #page2). Wrapping the buttons in a div with attributes data-role="controlgroup" and data-type="horizontal" displays the buttons with no separation. We add a bit of padding to the footer, around the buttons, on page 2 with class="ui-bar".

Unlike in headers, as we saw above, the classes ui-btn-left and ui-btn-right do not work to position buttons in footers, because they do not account for the possible presence of text, navbars, and and other elements often present in footers. If needed, you can use custom CSS to position the buttons.

footerbars

<div data-role="footer">
	<a href="#home" class="ui-btn ui-corner-all ui-btn-inline ui-mini ui-btn-icon-left ui-icon-home">Home</a>
	<a href="#page2" class="ui-btn ui-corner-all ui-btn-inline ui-mini ui-btn-icon-left ui-icon-arrow-r">Page 2</a>
</div>

Page 1's footer, shown above, has links to the Home page and to Page 2; we've chosen appropriate icons with the data-icon attribute.

<div data-role="footer" class="ui-bar">
	<div data-role="controlgroup" data-type="horizontal">
		<a href="#home" class="ui-btn ui-corner-all ui-btn-inline ui-mini ui-btn-icon-left ui-icon-home">Home</a>
		<a href="#page1" class="ui-btn ui-corner-all ui-btn-inline ui-mini ui-btn-icon-left ui-icon-arrow-r">Page 1</a>
	</div>
</div>

Adding a div with attributes data-role="controlgroup" and data-type="horizontal" around the buttons in the footer creates a grouped set of button on Page 2. Note that we also add class ui-bar to the footer to give extra padding around the buttons.

Navbars

jQuery Mobile offers a basic navbar widget that will show up to five items horizontally across the page; adding more than five items will cause the navbar to wrap to multiple lines, with the items displayed two-to-a-row. Navbars are typically (though need not be) added to headers or footers.

Navbars are coded as unordered lists of links wrapped in a container element (typically a div) with a data-role="navbar" attribute. Set one of the links to the active (selected) state by adding class="ui-btn-active" to the a tag.

Open WidgetsUI/Demos/toolbars/navbars.html in a mobile browser and in a file editor to view the code. We add a navbar to the header of the home page, and to the footer of each of the two interior pages:

navbars

Each navbar is an unordered list of links, wrapped in a div with attribute data-role="navbar". jQuery Mobile automatically splits each navbar link into one-third of the width of the page. We use class="ui-btn-active ui-state-persist" on the on-state nav item appropriately for each page; the ui-state-persist class specifies that the "active" state of the button should persist if the user were to refresh the page.

<div data-role="navbar">
	<ul>
		<li><a href="#home">Home</a></li>
		<li><a href="#page1" class="ui-btn-active ui-state-persist">Page 1</a></li>
		<li><a href="#page2">Page 2</a></li>
	</ul>
</div>

Toolbar Positioning

jQuery Mobile offers several options for the positioning of toolbars. By default, toolbars use the "inline" positioning mode: headers and footer sit in the flow of the document - header at top, content below it, and footer at bottom.

jQuery Mobile also offers several other toolbar positioning modes. Adding attribute data-position="fixed" to the toolbar fixes the header (at the top) or footer (at the bottom) on the page. The toolbar stays fixed while the content scrolls. Tapping the content toggles the visibility of the fixed toolbars. Open WidgetsUI/Demos/toolbars/fixed-standard.html to see this "fixed" mode in action.

Note that this only works in browsers that support CSS position: fixed (most desktop browsers, iOS5+, Android 2.2+, and others). For browsers that don't support fixed positioning, the toolbars will remain positioned in flow, at the top or bottom of the page.

Add data-position="fixed" and data-fullscreen="true" attributes to a toolbar for "fullscreen" positioning. Similar to "fixed" mode, "fullscreen" positioned toolbars sit on top of existing content, with a slight transparency. Open WidgetsUI/Demos/toolbars/fixed-fullscreen.html to see "fullscreen" positioned toolbars.

The following screenshots show fixed toolbars on the left and fixed fullscreen toolbars on the right. Note that you can see some of the content behind the toolbars in the fullscreen example; the fixed-fullscreen toolbars hide when the user taps the screen.

toolbar positioning

Next