# Titanium.UI.ListItem
A list item is an individual item in a list section.
# Overview
A list item is a combination of a ListDataItem and ItemTemplate. The list data item represents the actual data, while the item template represents the style elements of the item.
You should not create ListItem
objects with a JavaScript factory method, as you do other Titanium proxies.
Instead, you should pass a ListDataItem array to the setItems
method of a ListSection
. The list data items
contain the data you want to display in the list.
Alloy applications can use <ListItem>
elements to create ListItem
objects. <ListItem>
elements
must be nested inside a <ListSection>
element, which itself is nested in a <ListView>
element,
as shown below:
<Alloy>
<ListView id="list">
<ListSection id="accounts">
<ListItem image="images/checking_account.png" title="Checking"/>
<ListItem image="images/saving_account.png" title="Savings"/>
</ListSection>
</ListView>
</Alloy>
By default, only the title
, image
and accessoryType
keys of the list data item's
properties
dictionary are displayed if an item template is not defined. See "Default List Items"
under "Examples" section for an example of using the default template.
# Item Templates
To customize the style of a list item, use an item template to create your view structure.
Add key-value pairs of view properties and their values to the properties
dictionary of the
item template to set view properties of the list item.
Note: If possible, do not use Ti.UI.SIZE
or non-static dimensions to set the
dimensions of view elements in list items. Instead, try to use static dimensions. Scrolling in
the list view may be jerky if you use non-static dimensions.
Add key-value pairs of event names and their callback functions (or array of callback functions
for multiple callback bindings) to the events
dictionary of the item template to bind callbacks
to events, which are bubbled from the subcomponents of the item.
Add additional views, such as labels or image views, to the childTemplates
array of the item
template. The child templates are item templates with two extra properties:
- Set the
type
property to a Titanium view class, such asTi.UI.Label
orTi.UI.ImageView
, to use that view in your template. - Set the
bindId
to bind the template to a custom property in the list data item. The custom properties in the list data item contain key-value pairs of view properties and their values.
A list template supports the following view classes:
- Titanium.UI.ActivityIndicator
- Titanium.UI.Button
- Titanium.UI.ButtonBar
- Titanium.UI.ImageView
- Titanium.UI.Label
- Titanium.UI.MaskedImage
- Titanium.UI.ProgressBar
- Titanium.UI.Picker
- Titanium.UI.ScrollableView
- Titanium.UI.Slider
- Titanium.UI.Switch
- Titanium.UI.TextArea
- Titanium.UI.TextField
- Titanium.UI.iOS.BlurView
- Titanium.UI.iOS.LivePhotoView
- Titanium.UI.iOS.Stepper
- Titanium.UI.iOS.TabbedBar
For example, suppose you have a list data item defined as {foo:{text: 'foobar'}}
and an item
template defined as {childTemplates: [{type: 'Ti.UI.Label', bindId: 'foo'}]}
. The foo
property in the list data item binds to the label in the template, which sets the text
property of the label in the template to the text
property in the list data item.
To bind the list data item to an item template, use the Titanium.UI.ListView.templates
property to map the template to a style name, then use the style name to either set the
Titanium.UI.ListView.defaultItemTemplate property to globally set the style for all items or set the
template
property of the list data item to override or individually set the style.
On iOS, you can specify one of the template constants for the ListDataItem.template property or Titanium.UI.ListView.defaultItemTemplate property: Titanium.UI.LIST_ITEM_TEMPLATE_CONTACTS, Titanium.UI.LIST_ITEM_TEMPLATE_SETTINGS or Titanium.UI.LIST_ITEM_TEMPLATE_SUBTITLE.
# Eventing
Unlike other views, you cannot use the addEventListener
method to bind callbacks to events for a
ListItem.
Use list view's Titanium.UI.ListView.itemclick event to monitor click events on
items in the list view. Do not rely on the source
property to determine which item fired the
event. Either use the sectionIndex
and itemIndex
, or the itemId
to determine the list item
that generated the event and use the bindId
to check which child control fired the event.
See "Default List Item" under "Examples" section for an example of using the itemclick
event.
To monitor events that bubble to the ListItem
or to monitor events of the view subcomponents,
bind them to the item by using the events
dictionary of the item template or the child view
templates respectively. Add the bindings as key-value pairs, where the key is the event name
and the value is the callback (or array of callbacks for multiple bindings). See "List Items
with an Item Template" under "Examples" section for an example of binding a click
event to an
item using an item template.
# Examples
# Default List Items
Creates a list without using an item template. Monitors the itemclick
event to check and
uncheck tasks.
var win = Ti.UI.createWindow({backgroundColor: 'white'});
var listView = Ti.UI.createListView();
var tasks = [
{id: 'trash', name: 'Take Out the Trash', icon: 'trash.png'},
{id: 'dishes', name: 'Do the Dishes', icon: 'dishes.png'},
{id: 'doggie', name: 'Walk the Dog', icon: 'doggie.png'}
];
var data = [];
for (var i = 0; i < tasks.length; i++) {
data.push({
properties: {
itemId: tasks[i].id,
title: tasks[i].name,
image: tasks[i].icon,
accessoryType: Ti.UI.LIST_ACCESSORY_TYPE_NONE,
color: 'black'
}
});
}
var section = Ti.UI.createListSection();
section.items = data;
listView.sections = [section];
listView.addEventListener('itemclick', function(e) {
var item = section.getItemAt(e.itemIndex);
if (item.properties.accessoryType == Ti.UI.LIST_ACCESSORY_TYPE_NONE) {
item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_CHECKMARK;
item.properties.color = 'red';
} else {
item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_NONE;
item.properties.color = 'black';
}
section.updateItemAt(e.itemIndex, item);
});
win.add(listView);
win.open();
# Default List Items (Alloy version)
Alloy version of previous example. For additional Alloy examples of using ListView
, see Titanium.UI.ListView.
index.xml
<!-- views/index.xml -->
<Alloy>
<Window class="container" title="Some things">
<ListView id="listView">
<ListSection id="section">
<ListItem image="images/trash.jpg" title="Take Out the Trash"/>
<ListItem image="images/dishes.png" title="Do the Dishes"/>
<ListItem image="images/doge.png" title="Walk the Dog"/>
</ListSection>
</ListView>
</Window>
</Alloy>
index.js
// controllers/index.js
$.listView.addEventListener('itemclick', function(e) {
var item = $.section.getItemAt(e.itemIndex);
if (item.properties.accessoryType == Ti.UI.LIST_ACCESSORY_TYPE_NONE) {
item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_CHECKMARK;
item.properties.color = 'red';
} else {
item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_NONE;
item.properties.color = 'black';
}
$.section.updateItemAt(e.itemIndex, item);
});
# List Items with an Item Template
Previous example modified to use an item template. The template defines a small icon on the far left, a title label to the right of the icon and a subtitle below the title label in smaller text.
Monitors the click
event of the item rather than the itemclick
event of the list view.
var win = Ti.UI.createWindow({backgroundColor: 'white'});
var plainTemplate = {
childTemplates: [
{ // Image justified left
type: 'Ti.UI.ImageView', // Use an image view for the image
bindId: 'pic', // Maps to a custom pic property of the item data
properties: { // Sets the image view properties
width: '50dp', height: '50dp', left: 0
}
},
{ // Title
type: 'Ti.UI.Label', // Use a label for the title
bindId: 'title', // Maps to a custom title property of the item data
properties: { // Sets the label properties
color: 'black',
font: { fontFamily:'Arial', fontSize: '20dp', fontWeight:'bold' },
left: '60dp', top: 0,
},
},
{ // Subtitle
type: 'Ti.UI.Label', // Use a label for the subtitle
bindId: 'subtitle', // Maps to a custom subtitle property of the item data
properties: { // Sets the label properties
color: 'gray',
font: { fontFamily:'Arial', fontSize: '14dp' },
left: '60dp', top: '25dp',
}
}
],
// Binds a callback to the click event, which catches events bubbled by the view subcomponents.
events: {click: toggleCheck }
};
// The following JSON API calls copy the plainTemplate object minus functions.
// This method of copying an object is simple but not quick.
// If performance is a factor, create your own method to copy an object.
var redTemplate = JSON.parse(JSON.stringify(plainTemplate));
// Change the text color to red
redTemplate.childTemplates[1].properties.color = 'red';
redTemplate.childTemplates[2].properties.color = 'red';
// Rebind the click event callback
redTemplate.events.click = toggleCheck;
var listView = Ti.UI.createListView({
// Maps plainTemplate to 'uncheck' and redTemplate to 'check'
templates: { 'uncheck': plainTemplate, 'check': redTemplate },
// Use 'uncheck', that is, the plainTemplate created earlier for all items
// Can be overridden by the item's template property
defaultItemTemplate: 'uncheck'
});
var tasks = [
{id: 'trash', name: 'Take Out the Trash', person: 'Yakko', icon: 'trash.png'},
{id: 'dishes', name: 'Do the Dishes', person: 'Wakko', icon: 'dishes.png'},
{id: 'doggie', name: 'Walk the Dog', person: 'Dot', icon: 'doggie.png'}
];
var data = [];
for (var i = 0; i < tasks.length; i++) {
data.push({
// Maps to the title component in the template
// Sets the text property of the Label component
title : { text: tasks[i].name },
// Maps to the subtitle component in the template
// Sets the text property of the Label component
subtitle : { text : tasks[i].person },
// Maps to the pic component in the template
// Sets the image property of the ImageView component
pic : { image : tasks[i].icon },
// Sets the regular list data properties
properties : {
itemId: tasks[i].id,
accessoryType: Ti.UI.LIST_ACCESSORY_TYPE_NONE,
}
});
}
var section = Ti.UI.createListSection();
section.items = data;
listView.sections = [section];
// Modified version of the `itemclick` event listener
// Changes the item template rather than the list item's color property
function toggleCheck(e) {
var item = section.getItemAt(e.itemIndex);
if (item.properties.accessoryType == Ti.UI.LIST_ACCESSORY_TYPE_NONE) {
item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_CHECKMARK;
item.template = 'check';
} else {
item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_NONE;
item.template = 'uncheck';
}
section.updateItemAt(e.itemIndex, item);
}
win.add(listView);
win.open();
# Properties
# accessoryType
Sets an accessory on the right side of an item.
Default: Titanium.UI.LIST_ACCESSORY_TYPE_NONE
# backgroundColor
Background color of the view, as a color name or hex triplet.
For information about color values, see the "Colors" section of Titanium.UI.
Default: Transparent
# backgroundGradient
Background gradient to render when the item is not selected.
# backgroundImage
Background image to render when the item is not selected.
Must be a local resource.
# backgroundSelectedColor
Background color of the view, as a color name or hex triplet when item is selected.
On Android, clicking on ListItem's sub-views will not trigger this unless these views have 'touchEnabled' set to false. For information about color values, see the "Colors" section of Titanium.UI.
Default: transparent
# backgroundSelectedGradient
Background gradient to render when the item is selected.
# backgroundSelectedImage
Background image to render when the item is selected.
Must be a local resource. On Android, clicking on ListItem's sub-views will not trigger this unless these views have 'touchEnabled' set to false.
# canEdit
Specifies if the item can be deleted by a user initiated action.
For more information see the "Editing Support" section of Titanium.UI.ListView.
Default: false
# canInsert
Specifies if the item can be inserted by a user initiated action.
For more information see the "Editing Support" section of Titanium.UI.ListView.
Default: false
# canMove
Specifies if the item can be reordered within the list view by a user initiated action.
For more information see the "Editing Support" section of Titanium.UI.ListView.
Default: false
# color
Default text color of the item when not selected, as a color name or hex triplet.
For information about color values, see the "Colors" section of Titanium.UI.
On Android, selectedColor
is not supported, so the text is always displayed in this color.
Only applies to the built-in templates.
# editActions
Specifies custom action items to be shown when when a list item is edited.
For more information see the "Editing Support" section of Titanium.UI.ListView.
# font
Font to use for the item title.
Only applies to the built-in templates.
Default: System default font.
# height
Row height in platform-specific units.
On Android, the value can be either a float value or a dimension string, for example, '40dp'. By default, the minimum height is 30 dp on the Android platform.
On iOS, the value can only be an absolute value.
# image
Image to render in the image area of the item, specified as a local path or URL.
On iOS, the image is on the left, and on Android, the image is on the right.
On Android, this image only appears on the default template.
On iOS, only local images are supported.
On iOS, this image only appears if the ListDataItem template
property or ListView
defaultItemTemplate
property is either: LIST_ITEM_TEMPLATE_DEFAULT,
LIST_ITEM_TEMPLATE_SETTINGS or LIST_ITEM_TEMPLATE_SUBTITLE.
# searchableText
The text to match against when the Titanium.UI.ListView is performing a search.
Used in conjunction with searchView, searchText and caseInsensitiveSearch properties of ListView.
# selectedBackgroundColor DEPRECATED
DEPRECATED SINCE 10.0.0
This property has been deprecated in favor of backgroundSelectedColor.
Background color of the view, as a color name or hex triplet when item is selected.
On Android, clicking on ListItem's sub-views will not trigger this unless these views have 'touchEnabled' set to false. For information about color values, see the "Colors" section of Titanium.UI.
Default: transparent
# selectedBackgroundGradient DEPRECATED
DEPRECATED SINCE 10.0.0
This property has been deprecated in favor of backgroundSelectedGradient.
Background gradient to render when the item is selected.
# selectedBackgroundImage DEPRECATED
DEPRECATED SINCE 10.0.0
This property has been deprecated in favor of backgroundSelectedImage.
Background image to render when the item is selected.
Must be a local resource. On Android, clicking on ListItem's sub-views will not trigger this unless these views have 'touchEnabled' set to false.
# selectedColor
Color to use for the item title when the item is selected, as a color name or hex triplet.
This property is only used on iOS.
For information about color values, see the "Colors" section of Titanium.UI.
# selectedSubtitleColor
Color to use for the item subtitle when the item is selected, as a color name or hex triplet.
This property is only used on iOS and if the ListDataItem template
property or ListView
defaultItemTemplate
property is either: LIST_ITEM_TEMPLATE_SUBTITLE,
LIST_ITEM_TEMPLATE_CONTACTS or LIST_ITEM_TEMPLATE_SETTINGS.
For information about color values, see the "Colors" section of Titanium.UI.
# selectionStyle
Selection style constant to control the selection color.
Specify one of the constants from <Titanium.UI.SELECTION_STYLE_*>.
# subtitle
Subtitle to set in the text area of the item.
This subtitle only appears if the ListDataItem template
property or ListView
defaultItemTemplate
property is set to either: LIST_ITEM_TEMPLATE_CONTACTS,
LIST_ITEM_TEMPLATE_SETTINGS or LIST_ITEM_TEMPLATE_SUBTITLE.
# subtitleColor
Default text color of the subtitle, as a color name or hex triplet.
This property is only used on iOS and if the ListDataItem template
property or ListView
defaultItemTemplate
property is either: LIST_ITEM_TEMPLATE_SUBTITLE,
LIST_ITEM_TEMPLATE_CONTACTS or LIST_ITEM_TEMPLATE_SETTINGS.
# title
Title to set in the text area of the item.
This title only appears for the built-in templates.