# Titanium.UI.DashboardView

> A dashboard view is an iOS Springboard-like view of [Titanium.UI.DashboardItem](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardItem.md) items that may be deleted and reordered by the user using its built-in edit mode.

- Source: https://titaniumsdk.com/docs/sdk/13.4.0/Titanium.UI.DashboardView
- Titanium SDK version: 13.4.0
- Kind: view
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 1.2
- Extends: Titanium.UI.View
- Inheritance: Titanium.UI.View > Titanium.Proxy

The DashboardView is created using the [Titanium.UI.createDashboardView](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createDashboardView) method or **`<DashboardView>`** 
Alloy element.

Dashboard view's edit mode may be activated by a longpress of a [Titanium.UI.DashboardItem](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardItem.md) item, 
unless this behavior has been disabled by the [editable](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardView.md#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](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardView.md#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](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#PORTRAIT) 
orientation mode.

## Example: 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.

``` js
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();
```

## Example: Alloy XML Markup

Previous example as an Alloy view.

dashboard.xml:
``` 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:
``` 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

### columnCount

- Type: Number
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.0
- Default: `3`

The number of columns of items in the view.

### data

- Type: Array<Titanium.UI.DashboardItem>
- Platforms: iPhone, iPad, macOS

Items to display in this view.

### editable

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `true`

Determines whether edit mode is activated by a longpress of an item.

Set to `false` to prevent a longpress from activating edit mode.

### rowCount

- Type: Number
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.0
- Default: `3`

The number of rows of items in the view.

### wobble

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `true`

Determines whether the wobble visual editing cue is enabled in edit mode.

Set to `false` to disable wobble effect.

Must be defined before edit mode is activated in order to take effect.

## Methods

### startEditing

- Platforms: iPhone, iPad, macOS

Enable edit mode.

This method causes the [Titanium.UI.DashboardView.edit](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardView.md#edit) event to fire.

### stopEditing

- Platforms: iPhone, iPad, macOS

Disable edit mode.

This method causes the [Titanium.UI.DashboardView.commit](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardView.md#commit) event to fire.

## Events

### click

- Platforms: iPhone, iPad, macOS

Event properties:

- `item` (Object): Item that was clicked.
- `location` (Point): Coordinates x and y of the event from the parent view's coordinate system.

### commit

- Platforms: iPhone, iPad, macOS

Fired when edit mode ends.

This event is invoked by the [Titanium.UI.DashboardView.stopEditing](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardView.md#stopEditing) method.

### delete

- Platforms: iPhone, iPad, macOS

Fired when an item is deleted in edit mode.

Event properties:

- `item` (Titanium.UI.DashboardItem): Item that was deleted.

### dragend

- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0

Fired when an item finishes being dragged in edit mode.

Event properties:

- `item` (Titanium.UI.DashboardItem): Item that was dragged.

### dragstart

- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0

Fired when an item starts being dragged in edit mode.

Event properties:

- `item` (Titanium.UI.DashboardItem): Item that was dragged.

### edit

- Platforms: iPhone, iPad, macOS

Fired when edit mode starts.

This event is invoked by a longpress of a [Titanium.UI.DashboardItem](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardItem.md) item or the 
[Titanium.UI.DashboardView.startEditing](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardView.md#startEditing) method.

### move

- Platforms: iPhone, iPad, macOS

Fired when an item is moved in edit mode.

Event properties:

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

### pagechanged

- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0

Fired when the current page of the dashboard view changes.

Event properties:

- `pageNo` (Number): The current page number.

## Inherited members

68 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.4.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/13.4.0/Titanium.UI.View.md): `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundGradient`, `backgroundImage`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `children`, `clearMotionEffects`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `getViewById`, `height`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keypressed`, `layout`, `left`, `longpress`, `opacity`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotate`, `rotation`, `show`, `singletap`, `size`, `swipe`, `tintColor`, `toImage`, `tooltip`, `top`, `touchEnabled`, `transform`, `twofingertap`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.