Titanium.UI.DashboardView

viewiPhoneiPadmacOSsince 1.2

A dashboard view is an iOS Springboard-like view of Titanium.UI.DashboardItem items that may be deleted and reordered by the user using its built-in edit mode.

The DashboardView is created using the Titanium.UI.createDashboardView method or <DashboardView> Alloy element.

Dashboard view's edit mode may be activated by a longpress of a Titanium.UI.DashboardItem item, unless this behavior has been disabled by the editable property. As a dashboard view does not inherently provide a way to exit edit mode, this must be explicitly defined.

When edit mode has been activated, the item icons wobble by default to act as a visual cue. This behavior may be disabled using the wobble property.

If a dashboard contains more than 9 items, it will be paged into screens in a 3 x 3 formation using its built-in scrollable view. A paging control is added to the bottom of the view to indicate the active page.

Note that a dashboard is only intended to be used in PORTRAIT orientation mode.

Examples

Dashboard Demo

Create a toolbar with an edit/done button and a dashboard of items on a single screen. Set the badge value for some items, and allow them to be reset with a click. Enter edit mode with a longpress of a dashboard item (default behavior). Toggle edit mode with a click to the toolbar button.

Copy your image files to the local project /images/dashboard directory.

var win = Ti.UI.createWindow({
    backgroundColor: '#13386c'
});

var button = Ti.UI.createButton({
    title: 'Edit',
    style: Ti.UI.BUTTON_STYLE_OPTION_POSITIVE,
});

var toolbar = Ti.UI.iOS.createToolbar({
    items: [button],
    top: 0
});
win.add(toolbar);

var label = Ti.UI.createLabel({
  color: 'white',
  font: { fontSize: 14 },
  text: 'Click an item to reset badge\nPress and hold an item to enable edit mode',
  textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER,
  top: 55,
  height: 40,
  width: 300
});
win.add(label);

var dashboardData = [];
var itemData = [
  { name: 'account', badge: 10 },
  { name: 'cases', badge: 2 },
  { name: 'calls', badge: 2 },
  { name: 'contacts', badge: 5},
  { name: 'emps' }, 
  { name: 'leads' },
  { name: 'meetings', badge: 3 },
  { name: 'opps',  badge:  126 }, // badge will be displayed as "99+"
  { name: 'tasks' }
];

for (var i = 0; i < itemData.length; i++) {
  var item = Ti.UI.createDashboardItem({
    badge: itemData[i].badge,
    image: '/images/dashboard/' + itemData[i].name + '_off.png',
    selectedImage: '/images/dashboard/' + itemData[i].name + '_on.png',
    label: itemData[i].name
  });
  dashboardData.push(item);
}

var dashboard = Ti.UI.createDashboardView({
  data: dashboardData,
  wobble: true,
  top: 100
});
win.add(dashboard);

var isEditable = false;

button.addEventListener('click', function(e) {
  if (isEditable) {
    dashboard.stopEditing();
  } else {
    dashboard.startEditing();
  }
});

dashboard.addEventListener('edit', function(e) {
  button.title = 'Done';
  button.style = Ti.UI.BUTTON_STYLE_OPTION_POSITIVE;
  isEditable = true;
});

dashboard.addEventListener('commit', function(e) {
  button.title = 'Edit';
  button.style = Ti.UI.BUTTON_STYLE_OPTION_NEUTRAL;
  isEditable = false;
});

dashboard.addEventListener('click', function(e) {
  e.item.badge = 0;
});

win.open();

Alloy XML Markup

Previous example as an Alloy view.

dashboard.xml:

<Alloy>
    <Window id="win" backgroundColor="#13386c">
        <Toolbar id="toolbar" top="0">
            <Items>
                <Button id="button" onClick="changeMode">Edit</Button>
            </Items>
        </Toolbar>
        <Label id="label" color="white" top="55" height="40" width="300">
            Click an item to reset badge\nPress and hold an item to enable edit mode
        </Label>

        <DashboardView id="dashboard" top="100" wobble="true"
            onClick="resetBadge" onEdit="handleEdit" onCommit="handleCommit">

            <DashboardItem image="account_off.png" selectedImage="account_on.png" badge="10" label="account"/>
            <DashboardItem image="calls_off.png" selectedImage="calls_on.png" badge="110" label="calls"/>
            <DashboardItem image="cases_off.png" selectedImage="cases_on.png" label="cases"/>
            <DashboardItem image="contacts_off.png" selectedImage="contacts_on.png" badge="23" label="contacts"/>
            <DashboardItem image="emps_off.png" selectedImage="emps_on.png" label="employees"/>
            <DashboardItem image="leads_off.png" selectedImage="leads_on.png" badge="1" label="leads"/>
            <DashboardItem image="meetings_off.png" selectedImage="meetings_on.png" badge="5" label="meetings"/>
            <DashboardItem image="opps_off.png" selectedImage="opps_on.png" label="opps"/>
            <DashboardItem image="tasks_off.png" selectedImage="tasks_on.png" label="tasks"/>

        </DashboardView>

    </Window>
</Alloy>

dashboard.js:

var isEditable = false;

function changeMode(e) {
  if (isEditable) {
    $.dashboard.stopEditing();
  } else {
    $.dashboard.startEditing();
  }
}

function handleEdit(e) {
  $.button.title = 'Done';
  $.button.style = Ti.UI.BUTTON_STYLE_OPTION_POSITIVE;
  isEditable = true;
}

function handleCommit(e) {
  $.button.title = 'Edit';
  $.button.style = Ti.UI.BUTTON_STYLE_OPTION_NEUTRAL;
  isEditable = false;
}

function resetBadge(e) {
  e.item.badge = 0;
}

Properties 51

accessibilityHidden

Booleansince 3.0.0

Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

Parameters	Type	Description
animation	Titanium.UI.Animation \| Dictionary<Titanium.UI.Animation>	Either a dictionary of animation properties or an Animation object.
callback?	Callback<Object>	Function to be invoked upon completion of the animation.

Parameters	Type	Description
point	Point	A point in this view's coordinate system. If this argument is missing an `x` or `y` property, or the properties can not be converted into numbers, an exception will be raised.
destinationView	Titanium.UI.View	View that specifies the destination coordinate system to convert to. If this argument is not a view, an exception will be raised.

Parameters	Type	Description
callback?	Callback<Titanium.Blob>	Function to be invoked upon completion. If non-null, this method will be performed asynchronously. If null, it will be performed immediately.
honorScaleFactor?	Boolean	Determines whether the image is scaled based on scale factor of main screen. (iOS only) When set to true, image is scale factor is honored. When set to false, the image in the blob has the same dimensions for retina and non-retina devices.

Event properties	Type	Description
item	Object	Item that was clicked.
location	Point	Coordinates x and y of the event from the parent view's coordinate system.

Event properties	Type	Description
x	Number	X coordinate of the event from the `source` view's coordinate system.
y	Number	Y coordinate of the event from the `source` view's coordinate system.
obscured	Boolean	Returns `true` if the double click passed through an overlapping window belonging to another app. This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Event properties	Type	Description
item	Titanium.UI.DashboardItem	Item that was moved.
items	Array<Titanium.UI.DashboardItem>	List of items to be committed, possibly in new order, when edit mode ends.

Event properties	Type	Description
scale	Number	The scale factor relative to the points of the two touches in screen coordinates.
velocity	Number	The velocity of the pinch in scale factor per second.
time	Number	The event time of the current event being processed.
timeDelta	Number	The time difference in milliseconds between the previous accepted scaling event and the current scaling event.
currentSpan	Number	The average distance between each of the pointers forming the gesture in progress through the focal point.
currentSpanX	Number	The average X distance between each of the pointers forming the gesture in progress through the focal point.
currentSpanY	Number	The average Y distance between each of the pointers forming the gesture in progress through the focal point.
previousSpan	Number	The previous average distance between each of the pointers forming the gesture in progress through the focal point.
previousSpanX	Number	The previous average X distance between each of the pointers forming the gesture in progress through the focal point.
previousSpanY	Number	The previous average Y distance between each of the pointers forming the gesture in progress through the focal point.
focusX	Number	The X coordinate of the current gesture's focal point.
focusY	Number	The Y coordinate of the current gesture's focal point.
inProgress	Boolean	Returns `true` if a scale gesture is in progress, `false` otherwise.

Event properties	Type	Description
direction	String	Direction of the swipe--either 'left', 'right', 'up', or 'down'.
x	Number	X coordinate of the event's endpoint from the `source` view's coordinate system.
y	Number	Y coordinate of the event's endpoint from the `source` view's coordinate system.
obscured	Boolean	Returns `true` if the swipe passed through an overlapping window belonging to another app. This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Examples

Dashboard Demo

Alloy XML Markup

Properties 51

Linear and Radial Gradients

Methods 14

Events 18