1.11.4

News

Feb 16, 2013
Category: General
Posted by: admin
Another summary
Feb 16, 2013
Category: General
Posted by: admin
Another summary
Nov 4, 2011
Category: General
Posted by: admin
Summary here
CMS - 1.11.4 - Fernandina
 

Navigational elements

Default header features

The header toolbar is themed with the "a" swatch by default (black in the default theme) but you can easily set the theme swatch color.

Page title

Adding buttons

In the standard header configuration, there are slots for buttons on either side of the text heading. Each button is typically an anchor element, but any valid button markup will work. To save space, buttons in toolbars are set to inline styling so the button is only as wide as the text and icons it contains.

Default button positioning

The header 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.

			
<div data-role="header" data-position="inline">
	<a href="index.html" data-icon="delete">Cancel</a>
	<h1>Edit Contact</h1>
	<a href="index.html" data-icon="check">Save</a>
</div>
Cancel

Edit Contact

Save

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

			
<div data-role="header" data-position="inline">
	<a href="index.html" data-icon="delete">Cancel</a>
	<h1>Edit Contact</h1>
	<a href="index.html" data-icon="check" data-theme="b">Save</a>
</div>
Cancel

Edit Contact

Save

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.


<div data-role="header" data-position="inline" 
	<h1>Page Title</h1>
	<a href="index.html" data-icon="gear" class="ui-btn-right">Options</a>
</div>

Page Title

Options

Adding Back buttons

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 web view. The framework automatically generates a "back" button on a header when the page plugin's addBackBtn option is true. This can also be set via markup if the page 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. Also, please keep in mind that if you just want a reverse transition without actually going back in history, you should use the data-direction="reverse" attribute instead.

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 page element, or set it programmatically via the page plugin's options:
$.mobile.page.prototype.options.backBtnText = "previous";

Default back button style

If you'd like to configure the back button role-theme, you can use:
$.mobile.page.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 to create a header that doesn't follow the default configuration, simply wrap your custom styled markup in a container div inside the header container and the plugin won't apply the automatic button logic 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).


<div class="ui-bar ui-bar-b">
	<h3>I'm just a div with bar classes and a <a href="#" data-role="button">Button</a></h3>
</div>
			

This will produce this bar:

I'm just a div with bar classes and a Button

By writing some simple styles, it's easy to build little message bars like this:

This is an alert message with dismiss button.

And here's some additional text in a paragraph.

Footer bar structure

The footer bar has the same basic structure as the header except it uses the data-role attribute value of footer.

<div data-role="footer"> 
	<h4>Footer content</h4> 
</div> 

The footer toolbar will be be themed with the "a" swatch by default (black in the default theme) but you can easily set the theme swatch color.

Footer content

The page footer is very similar to the header in terms of options and configuration. The primary differences are that the footer is designed to be less structured than the header to allow for more flexibility, so the framework doesn't automatically place buttons to the left or right based on source order as it does in the header. Since footers do not have the same prescriptive markup contentions as headers, use layout grids or custom styles to achieve the design you want in a footer.

Adding buttons

Any link or valid button markup added to the footer will automatically be turned into a button. To save space, buttons in toolbars are automatically set to inline styling so the button is only as wide as the text and icons it contains.

By default, toolbars 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.


<div data-role="footer" class="ui-bar">
	<a href="index.html" data-role="button" data-icon="delete">Remove</a>
	<a href="index.html" data-role="button" data-icon="plus">Add</a>
	<a href="index.html" data-role="button" data-icon="arrow-u">Up</a>
	<a href="index.html" data-role="button" data-icon="arrow-d">Down</a>
</div>

This creates this toolbar with buttons sitting in a row

To group buttons together into a button set, wrap the links in a wrapper with data-role="controlgroup" and data-type="horizontal" attributes.

<div data-role="controlgroup" data-type="horizontal">

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:

Persistent footers

In situations where the footer is a global navigation element, you may want it to appear fixed in place between page transitions. This can be accomplished by using the persistent footer feature included in jQuery Mobile.

To make a footer stay in place 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. PLEASE NOTE: 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.

Simple navbar

jQuery Mobile has a very basic navbar widget that is useful for providing up to 5 buttons with optional icons in a bar, typically within a header or footer. There is also a persistent nav bar variation that works more like a tab bar that stays fixed as you navigate across pages.

A navbar is coded as an unordered list of links wrapped in a container element that has the data-role="navbar" attribute. To set one of links to the active (selected) state, add class="ui-btn-active" to the anchor. In this example, we have a two-button navbar in the footer with the "One" item set to active:


<div data-role="navbar">
	<ul>
		<li><a href="a.html" class="ui-btn-active">One</a></li>
		<li><a href="b.html">Two</a></li>
	</ul>
</div><!-- /navbar -->

The navbar items are set to divide the space evenly so in this case, each button is 1/2 the width of the browser window:

Adding a third item will automatically make each button 1/3 the width of the browser window:

Adding a fourth more item will automatically make each button 1/4 the width of the browser window:

The navbar maxes out with 5 items, each 1/5 the width of the browser window:

If more than 5 items are added, the navbar will simply wrap to multiple lines:

As a fallback, navbars with 1 item will simply render as 100%.

Navbars in headers

If you want to add a navbar to the top of the page, you can still have a page title and buttons. Just add the navbar container inside the header block, right after the title and buttons in the source order.

I'm a header

Options

Navbars in footers

If you want to add a navbar to the bottom of the page so it acts more like a tab bar, simply wrap the navbar in a container with a data-role="footer"


<div data-role="footer">		
	<div data-role="navbar">
		<ul>
			<li><a href="#">One</a></li>
			<li><a href="#">Two</a></li>
			<li><a href="#">Three</a></li>
		</ul>
	</div><!-- /navbar -->
</div><!-- /footer -->

Icons in navbars

Icons can be added to navbar items by adding the data-icon attribute specifying a standard mobile icon to each anchor. By default icons are added above the text (data-iconpos="top"). The following examples add icons to a navbar in a footer.

The icon position is set on the navbar container instead of for individual links within for visual consistency. For example, to place the icons below the labels, add the data-iconpos="bottom" attribute to navbar container.


<div data-role="navbar" data-iconpos="bottom">

This will result in a bottom icon alignment:

The icon position can be set to data-iconpos="left":

Or the icon position can be set to data-iconpos="right":

Using 3rd party icon sets

You can add any of the popular icon libraries like Glyphish to achieve the iOS style tab tab that has large icons stacked on top of text labels. All that is required is a bit of custom styles to link to the icons and position them in the navbar. Here is an example using Glyphish icons and custom styles (view page source for styles) in our navbar:

Icons by Joseph Wain / glyphish.com. Licensed under the Creative Commons Attribution 3.0 United States License.

Theming navbars

Navbars inherit the theme swatch from their parent container, just like buttons. If a navbar is placed in header or footer toolbar, it will inherit the default toolbar swatch (A) for bars unless you set this in the markup.

Here are a few examples of navbars in various container swatches automatically inheriting their parent's swatch letter. Note that in these examples, instead of using a data-theme attribute, we're manually adding the swatch classes to apply the body swatch (ui-body-a) and the class to add the standard body padding (ui-body), but the inheritance works the same way:

Swatch A

Swatch B

To set to the theme color for a navbar item, add the data-theme attribute to the individual links and specify a theme swatch. Note that applying a theme swatch at the navbar container is not supported.

Adding Icons to Buttons

The jQuery Mobile framework includes a selected set of icons most often needed for mobile apps. To minimize download size, jQuery Mobile includes a single white icon sprite, and automatically adds a semi-transparent black circle behind the icon to ensure that it has good contrast on any background color.

An icon can be added to a button by adding a data-icon attribute on the anchor specifying the icon to display. For example, the following markup:

<a href="index.html" data-role="button" data-icon="delete">Delete</a>

Creates this button with an icon:

Delete

Icon set

The following data-icon attributes can be referenced to create the icons shown below:

Left arrow - data-icon="arrow-l"

My button

Right arrow - data-icon="arrow-r"

My button

Up arrow - data-icon="arrow-u"

My button

Down arrow - data-icon="arrow-d"

My button

Delete - data-icon="delete"

My button

Plus - data-icon="plus"

My button

Minus - data-icon="minus"

My button

Check - data-icon="check"

My button

Gear - data-icon="gear"

My button

Refresh - data-icon="refresh"

My button

Forward - data-icon="forward"

My button

Back - data-icon="back"

My button

Grid - data-icon="grid"

My button

Star - data-icon="star"

My button

Alert - data-icon="alert"

My button

Info - data-icon="info"

My button

Home - data-icon="home"

My button

Search - data-icon="search"

My button

Icon positioning

By default, all icons in buttons are placed to the left of the button text.

Delete

This default may be overridden using the data-iconpos attribute to set the icon to the right, above (top) or below (bottom) the text. For example, the markup:

<a href="index.html" data-role="button" data-icon="delete" data-iconpos="right">Delete</a>

Creates this button with right-aligned icon:

Delete

Icons can also be positioned above the text by specifying data-iconpos="top"

Delete

Or icons can also be positioned below the text by specifying data-iconpos="bottom"

Delete

You can also create an icon-only button, by setting the data-iconpos attribute to notext. The button plugin will hide the text on-screen, but add it as a title attribute on the link to provide context for screen readers and devices that support tooltips. For example, replacing data-iconpos="right" on the previous example with data-iconpos="notext":

<a href="index.html" data-role="button" data-icon="delete" data-iconpos="notext">Delete</a>

Creates this icon-only button:

Delete

Custom Icons

To use custom icons, specify a data-icon value that has a unique name like myapp-email and the button plugin will generate a class by prefixing ui-icon- to the data-icon value and apply it to the button. You can then write a CSS rule that targets the ui-icon-myapp-email class to specify the icon background source. To maintain visual consistency, create a white icon 18x18 pixels saved as a PNG-8 with alpha transparency.

Icons and themes

The semi-transparent black circle behind the white icon ensures good contrast on any background color so it works well with the jQuery Mobile theming system. Here are examples of the same icons sitting on top of a range of different color swatches in out theme.

Swatch "A" themed buttons

Swatch "B" themed buttons

Swatch "C" themed buttons

Previous page: Pages & dialogs  Next page: Gallery with swipe function