Documentation

JQMNavbar

A JQMNavbar object displays a jQuery Mobile navigation bar.

By setting the object's properties, either at design-time in Handheld Designer, or at run-time in code, you can:

  • Access the list's existing items with the items array property.
  • Add a new item with the appendItem() method.
  • Define an event handler to be called when an item is tapped with the onClick property.

Example:

// create a simple navbar:
var navbar = new JQMNavbar();
navbar.appendItem("Item #1");
navbar.appendItem("Item #2");
navbar.appendItem("Item #3");

// assign the navbar to a JQMHeaderToolbar
header1.navbar = navbar;

For more detail, view the full object documentation on HandheldDesigner.com.

Object Properties & Methods

 appendItemAdds a new item to the end of the navbar.
 heightThe height of the object, measured in pixels.
 iconposDefines the position of each item's icon.
 idThe object's unique identifier. Also used as the variable name in code.
 insertItemInserts a new item into the navbar.
 itemsAn array of all items in the navbar.
 leftThe location of the left of the object from the left edge of the page, measured in pixels.
 onClickEvent that occurs when a navbar item is tapped/clicked.
 removeAllItemsRemoves all items from the navbar.
 topThe location of the top of the object, as measured from the top of the page, in pixels.
 userdataAn object for storing user data.
 widthThe width of the object, measured in pixels.
 zIndexThe stack order of the object. Objects with higher numbers appear in front of objects with lower numbers.

appendItem

MethodFirst available in version 1.2.0

Adds a new item to the end of the navbar.

Usage:

navbar.appendItem(item);

Arguments:

item Either a String specifying the label of the new item, or a JavaScript object containing the properties to be set on the new item. (optional)

Returns the new JQMNavbarItem object.

Example:

var item = navbar.appendItem();
item.label = "The Item";
item.onClick = someFunction;

As a convenience, you can set the label of the new item by passing it to the appendItem method:

var item = navbar.appendItem("The Item");
item.onClick = someFunction;

Or, set multiple properties of the new item by passing a JavaScript object:

navbar.appendItem({
	label: "The Item",
	icon: "arrow-l",
	onClick: someFunction
});

height

PropertyFirst available in version 1.2.0

The height of the object, measured in pixels.

Example:

// get the height of object1
var h = object1.height;

// set the height of object1
object1.height = 64;

iconpos

PropertyFirst available in version 1.2.0

Defines the position of each item's icon. Note that you cannot set the position individually on each item; there is a single iconpos on the JQMNavbar that applies to all items in the navbar.

Can be one of the following values:

left (or blank)Left side of item
rightRight side of item
topTop of item
bottomBottom of item

Example:

// place the icon on the right
navbar.iconpos = "right";

id

PropertyFirst available in version 1.2.0

The object's unique identifier. Also used as the variable name in code.

Example:

// get height of object with the id "object1".
var h = object1.height;

insertItem

MethodFirst available in version 1.2.0

Inserts a new item into the navbar before an existing item.

Usage:

navbar.insertItem(before, item);

Arguments:

before Index (number, zero-based) of the item before which the new item will be inserted. (required) item Either a String specifying the label of the new item, or a JavaScript object containing the properties to be set on the new item. (optional)

Returns the new JQMNavbarItem object.

Example:

// add a new item to the beginning of the navbar
var item = navbar.insertItem(0);
item.label = "The Item";
item.onClick = someFunction;

As a convenience, you can set the label of the new item by passing it as the second argument to the insertItem method:

var item = navbar.insertItem(0, "The Item");
item.onClick = someFunction;

Or, set multiple properties of the new item by passing a JavaScript object:

navbar.insertItem(0, {
	label: "The Item",
	icon: "arrow-l",
	onClick: someFunction
});

items

PropertyFirst available in version 1.2.0

An array of JQMNavbarItem objects representing the items in the navbar.

Example:

// set the second item to be "active"
navbar.items[1].active = true;

left

PropertyFirst available in version 1.2.0

The location of the left of the object from the left edge of the page, measured in pixels.

Example:

// get the left location of object1
var x = object1.left;

// set the left location of object1
object1.left = 64;

onClick

EventFirst available in version 1.2.0

Event that occurs when a navbar item is tapped/clicked. Note that this event is only called if no onClick event handler is defined for the individual item tapped. Also note that in the context of the event handler, the this variable refers to the JQMNavbarItem, and not the navbar itself.

The property can be set to reference an existing function:

navbar.onClick = someExistingFunction;

Or, you can define an anonymous function containing the code to be executed by the event:

navbar.onClick = function(event) {
	console.log("The event was triggered");
};

removeAllItems

MethodFirst available in version 1.2.0

Removes all items from the navbar.

Usage:

navbar.removeAllItems();

Example:

navbar.removeAllItems();

top

PropertyFirst available in version 1.2.0

The location of the top of the object, as measured from the top of the page, in pixels.

Example:

// get the top location of object1
var y = object1.top;

// set the top location of object1
object1.top = 64;

userdata

PropertyFirst available in version 1.2.0

An JavaScript object for storing user data. You can use this property to store data for later use. (For example, to share data between event handlers.)

Example:

// track the number of times a button is clicked:
function button1_onClick(event) {
	if(button1.userdata.timesClicked === undefined)
	{
		button1.userdata.timesClicked = 0;
	}
	else
	{
		button1.userdata.timesClicked++;
	}
}

width

PropertyFirst available in version 1.2.0

The width of the object, measured in pixels.

Example:

// get the width of object1
var w = object1.width;

// set the width of object1
object1.width = 64;

zIndex

PropertyFirst available in version 1.2.0

The stack order of the object. Objects with higher numbers appear in front of objects with lower numbers.

Example:

// "raise" the object
var z = object1.zIndex;
z += 10;

object1.zIndex = z;

Copyright © 2010-2017, Handheld Designer, LLC, All Rights Reserved.
Made by hand in New England, USA.