Documentation

Class: ListView

ListView

The virtualized list view class.

In addition to ordinary Backbone View options, the constructor also takes

virtualized: whether or not the virtualization is enabled.

viewport: the option locate the scrollable viewport. It can be

  • Omitted, auto detect the closest ancestor of the $el with 'overflowY' style being 'auto' or 'scroll'. Use the window viewport if found none.
  • A string, use it as a selector to select an internal element as the viewport.
  • An HTMLElement or jQuery, use it as the viewport element.
  • The window, use the window viewport.

new ListView(options)

Parameters:
Name Type Description
options Object

The constructor options.

Properties
Name Type Argument Default Description
virtualized boolean <optional>
 true
viewport string | HTMLElement | jQuery | window <optional>

Members

defaultItemHeight :number

The default list item height.

Type:
  • number

indexFirst :number

The index of the first rendered item.

Type:
  • number

indexLast :number

The index after the last rendered item.

Type:
  • number

itemHeights :external:BinaryIndexedTree

The BinaryIndexedTree to get the heights and accumulated heights of items.

Type:

itemTemplate :ListView~cbItemTemplate

The template to render a list item.

Type:

length :number

The total count of the items.

Type:
  • number

listTemplate :ListView~cbListTemplate

The template to render the skeleton of the list view.

Type:

model :Object

The model object to render the skeleton of the list view.

Type:
  • Object

virtualized

Whether or not the list view is virtualized

Methods

elementAt(index)

Get the rendered DOM element at certain index.

Parameters:
Name Type Description
index number

The index of the item.
Returns:
Type
HTMLElement

initialize()

Backbone view initializer

See:

invalidate( [callback])

Invalidate the already rendered items and schedule another redraw.

Parameters:
Name Type Argument Description
callback function <optional>

The callback to notify completion.

itemAt(index)

Get the item at certain index.

Parameters:
Name Type Description
index number

The index of the item.
Returns:
Type
Object

remove()

Remove the view and unregister the event listeners.

render( [callback])

Render the list view.

Parameters:
Name Type Argument Description
callback function <optional>

The callback to notify completion.

scrollToItem(index [, position] [, callback])

Scroll to a certain item.

Parameters:
Name Type Argument Default Description
index number

The index of the item.
position string | number <optional>
 'default'

The position of the item.

The valid positions are

  • 'default', if the item is above the viewport top, scroll it to the top, if the item is below the viewport bottom, scroll it to the bottom, otherwise, keep the viewport unchanged.
  • 'top', scroll the item to top of the viewport.
  • 'middle', scroll the item to the vertical center of the viewport.
  • 'bottom', scroll the item to the bottom of the viewport.
  • {number}, scroll the item to the given offset from the viewport top.
callback function <optional>

The callback to notify completion.

set(options [, callback])

Set the list view options. The following options can be set

model: The model object to render the skeleton of the list view.

listTemplate: The template to render the skeleton of the list view.

  • By default, it would render a single UL.
  • Note: It must contain the following elements with specified class names as the first and last siblings of the list items. All list items will be rendered in between.
    • 'top-filler': The filler block on top.
    • 'bottom-filler': The filler block at bottom.

events: The events hash in form of { "event selector": callback }.

  • Refer to Backbone.View~events
  • In addition to the DOM events, it can also handle the 'willRedraw' and 'didRedraw' events of the list view.
  • Note: The callback MUST be a function. Member function names are not supported.

items: The model objects of the list items.

itemTemplate: The template to render a list item.

  • By default, it would render a single LI filled with item.text.
  • Note: list items MUST NOT have outer margins, otherwise the layout calculation will be inaccurate.

defaultItemHeight: The estimated height of a single item.

  • It's not necessary to be accurate. But the accurater it is, the less the scroll bar is adjusted overtime.

Refer to ListView for detail.

Parameters:
Name Type Argument Description
options Object

The new options.

Properties
Name Type Argument Default Description
model Object
listTemplate ListView~cbListTemplate <optional>
events Object
items Array.<Object> <optional>
 []
itemTemplate ListView~cbItemTemplate <optional>
defaultItemHeight number <optional>
 20
callback function <optional>

The callback to notify completion.
Returns:

The list view itself.

Type
ListView

Type Definitions

cbItemTemplate(item)

The template to render a list item.

Parameters:
Name Type Description
item Object

The model object of the item

cbListTemplate(model)

The template to render the skeleton of the list view.

Parameters:
Name Type Description
model Object

The model object of the list view.

Events

didRedraw

The event indicates the list view have completed redraw.

willRedraw

The event indicates the list will start redraw.