Documentation

Global

Members

<constant> extendDataColumnAttribute

Normalize the attributes configuration

Methods

cellsProjectionHandler(state)

Fill the headRows, bodyRows and footRows with cells.

Parameters:
Name Type Description
state ContentChainState

All data, configurations and events needed in grid cells.
Returns:
Type
ContentChainState

columnGroupProjectionHandler(state)

Resolve grid structure from columns configuration and build the ColumnGroup object.

Parameters:
Name Type Description
state ContentChainState

The input content chain state.
Returns:
Type
ContentChainState

columnsProjectionHandler(state [, columnsConfig])

Columns projection handling columns configuration

  1. If the columnsConfig is null, generate the columns config.
  2. Add head/body/foot attribute data-column="name" which will render data-column attribute on each cell.
Parameters:
Name Type Argument Description
state Object
Properties
Name Type Argument Description
items Array.<object> | FakeArray <optional>

Original data items from data source.
columnsConfig Array.<ColumnConfig> <optional>

Columns configuration defined by user. If omitted, all columns in original data will be shown.

eventsProjectionHandler(state, eventsOptions)

Merge the customized events with the projection injected events.

Parameters:
Name Type Description
state ContentChainState

The input state.
eventsOptions external:BackboneViewEventHash

The customized events in form of Backbone.View#events.

normalizeAttributes(attributes, context)

Normalize the attributes configuration

Parameters:
Name Type Description
attributes AttributesConfig

The attributes configuration.
context Object

The context for the classes. It could be

  • A ColumnConfig for a column's headAttributes/colAttributes
  • A RowConfig for a column or row's bodyAttributes/footAttributes
  • An object representing the data item for data rows in the body
Returns:

The normalized attributes configuration.

Type
Object.<string, string>

normalizeClasses(classes, context)

Normalize the classes configuration

Parameters:
Name Type Description
classes ClassesConfig

The classes configuration.
context Object

The context for the classes. It could be

  • A ColumnConfig for a column's headClasses/colClasses
  • A RowConfig for a column or row's bodyClasses/footClasses
  • An object representing the data item for data rows in the body
Returns:

The normalized classes configuration.

Type
Array.<string>

normalizeSelectionConfig(selection)

Normalize the selection config

Parameters:
Name Type Description
selection boolean | SelectionConfig

The selection configuration.

queryProjectionHandler(state, params)

Fetching data from the data source

Parameters:
Name Type Description
state DataChainState
params QueryConfig

The data source configurations.
Returns:
Type
DataChainState

rowsProjectionHandler(state, options)

Handling bodyRows and adding headRows, bodyRows, footRows to state

Parameters:
Name Type Description
state StructureChainState

The input state.
options RowsConfig

The configuration for rows projection.
Returns:
Type
StructureChainState

selectionProjectionHandler(state, selection)

Add selection box to rows

Parameters:
Name Type Description
state StructureChainState

The input state.
selection boolean | SelectionConfig

The selection configuration. It can be

  • A boolean to indicate whether the grid has the selection column.
  • A detailed SelectionConfig object.

sortableHeaderProjectionHandler(state, options)

Add click event to sortable column and wrap sortable column's head with a template

Parameters:
Name Type Description
state ContentChainState

The input state.
options SortableHeaderConfig

The sortable header configurations.

translateRow(options, rowType, primaryKey)

Translate the RowConfig into RowContent

Parameters:
Name Type Description
options Object
Properties
Name Type Description
columnGroup ColumnGroup

The column group.
row RowConfig

The RowConfig to translate.
rowType string

Which group the row belongs to. It could be 'head', 'body' or 'foot'.
primaryKey string

The primary key of the data items.
Returns:
Type
RowContent

Type Definitions

BuiltinDataSourceConfig

Type:
  • Object
Properties:
Name Type Argument Description
type string

The builtin data source type, available values are 'odata', 'js-data' and 'memory'.
primaryKey string <nullable>

The primaryKey for the data source. Required by 'odata' and 'memory' data sources.
entity JSDataResource <nullable>

The JSDataResource representing the entity set. Required by 'js-data' data source.
url string <nullable>

The URL for the entity set. Required by 'odata' data source.
data Array.<Object> <nullable>

The in-memory data set. Required by 'memory' data source.

CellContent

The object represents a cell.

Type:
  • Object
Properties:
Name Type Description
classes Array.<string>

The classes for the TD/TH element
attributes Object.<string, string>

The HTML attributes for the TD/TH element.
html string

The HTML string to be rendered inside the cell.
view Backbone.View

The Backbone View to be filled into the cell. Unsupported for the body cells.
group string

[group=other] Group name. A Row will be separated by the group name. [[cell, cell], [cell], [cell]]

ClassesConfig

The classes configuration. It could be

  • A array of class strings
  • A space separated classes string
  • A hash from class names to ClassPredicate
Type:

ClassPredicate

A boolean or a callback to decide whether or not a class is applied. When it's a function, it takes the context and return a boolean.

Type:

ClassPredicateCallback(context)

Parameters:
Name Type Description
context Object

Refer to the context of normalizeClasses.
Returns:

Whether or not the class is applied.

Type
boolean

ColContent

The content of a COL element in COLGROUP.

Type:
  • Object
Properties:
Name Type Description
classes Array.<string>

The classes of the COL element.
width number | string

The CSS width for the column.

ColumnConfig

Type:
  • Object
Properties:
Name Type Description
name string

Name of the column.
title string

The localized column title. The name will be used if title is omitted.
html string

The HTML string to be rendered in the column header. The title string will be rendered in the column header if html is omitted.
property string | PropertyCallback | PropertyConfig

The data property of the column. It defines how to get/set values with a data item. If it's omitted, will use the column name as the key path. It could be
template CellTemplate

The template to render a cell for the column.
sortable boolean | number | OrderByKey

The ordering configuration. If it's omitted, the column is unsortable. It could be

  • A boolean simply say the column is sortable or not.
  • A number, positive for ascending first, otherwise descending first.
  • A string, the key path of the sorting values.
  • A PropertyGetter to get the sorting values from data items. Only available for memory data source.
  • A detailed SortableConfig object.
colClasses ClassesConfig

The classes for the COL element in COLGROUP.
headClasses ClassesConfig

The classes for the TH element in THEAD.
bodyClasses ClassesConfig

The classes for the TD elements in TBODY.
footClasses ClassesConfig

The classes for the TD elements in TFOOT.
colAttributes ClassesConfig

The attributes for the COL element in COLGROUP.
headAttributes AttributesConfig

The attributes for the TH elements in THEAD.
bodyAttributes AttributesConfig

The attributes for the TD elements in TBODY.
footAttributes AttributesConfig

The attributes for the TD elements in TFOOT.
columns Array.<ColumnConfig>

The children columns.

ContentChainState

It extends the StructureChainState with extra properties, and overrides some of the properties.

Type:
Properties:
Name Type Description
columnGroup ColumnGroup

The column group object, represents the compiled column hierarchy.
cols Array.<ColContent>

The content for COL elements in COLGROUP.
headRows RowContent

The content for rows in THEAD.
bodyRows RowContent

The content for rows in TBODY.
footRows RowContent

The content for rows in TFOOT.

DataChainState

Type:
  • Object
Properties:
Name Type Description
uniqueId string

The unique id for the set of data items. It changes each time new query is made to the server.
primaryKey string

The primary key of the data items.
items Array.<Object> | FakeArray

An array or a fake array of data items.
totalCount number

The total item count on the server.
itemIndex Object.<string, Object>

The items indexed by primary key.
events external:BackboneViewEventHash

The event has in form of Backbone.View#events. Any projection can response to the DOM events by adding its own event handlers.

DataSourceConfig

Type:

ExtendedColumnConfig

An extended internal representation of columns. It extends ColumnConfig with several extra properties.

Type:
Properties:
Name Type Description
parent ExtendedColumnConfig

The parent column if there's a column hierarchy.
columns Array.<ExtendedColumnConfig>

The children columns.
cell CellContent

The configuration of the header cell.
height number

The rowspan of the header cell.
treeWidth number

The colspan of the header cell. The tree width of the column subtree in number of columns.
treeHeight number

The height of the column subtree in number of rows.

FakeArray

A object implements a minimal interface of array to lazy fetch items. We use this structure a lot in projections, so that we don't need to procceed all the rows when virtualization is on.

Type:
  • Object
Properties:
Name Type Description
slice function

a callback to get a slice of the items. It has the same signature as Array.slice().
length number

length of the array

GridViewConfig

Type:
  • Object
Properties:
Name Type Description
name string

Name of the grid
el string | HTMLElement | jQuery

The root element of the grid view.
scrolling ScrollingConfig

The scrolling behavior configuratoin.
tableClasses Array.<strings>

An array of classes to be applied to TABLE elements.
tableAttributes object

An object of attributes to be applied to TABLE elements.
plugins Object.<string, Object>

The plugin configurations. The keys are the plugin names, and the values are the configuation objects.
rows RowsConfig

The structure of the head/body/foot rows.
columns Array.<ColumnConfig>

Array of the columns configurations.
dataSource DataSourceConfig

The data source configurations. Tells the grid how to fetch data.
query QueryConfig

The query parameters for data fetch.
selection SelectionConfig

Config the behavior for row selection.
sortableHeader SortableHeaderConfig

Config the state and visual of the click-to-sort column headers.
events external:BackboneViewEventHash

Customized event hash in form of Backbone.View#events. It can be set to handle

  • The DOM events inside the GridView.
  • The GridView events, e.g. GridView#willUpdate, GridView#didUpdate.

HeaderConfig

Type:
  • Object
Properties:
Name Type Description
type string

the header type. It can have the following values

  • 'static': static header, the normal case, the header is rendered to the top of the grid.
  • 'sticky': sticky header, the header will stick to the viewport with a given offset.
  • 'fixed': fixed header, the header will be outside the viewport. Only the body and footer are scrollable.
offset number | function

special configuration for sticky header indicating its position. It's can be a number or a function returning a number, represents number of pixels below the viewport top.

NormalizedOrderByPair

A [key: string, direction: number] pair.

Type:
  • array

OrderByCallback(direction)

Parameters:
Name Type Description
direction number

The direction of the order by item
Returns:
Type
OrderByConfig

OrderByConfig

The order-by configuration for the data source.

Type:

OrderByItem

A single order-by item with key and direction.

Type:

OrderByKey

Represents an order by key

  • When it's a string, it's the key path of the sorting value.
  • When it's a callback, it takes a direction, and return a normalized order config.
Type:

OrderByObject

Type:
  • object
Properties:
Name Type Description
key OrderByKey

The key off the order by item
direction number

The direction of the order by item, positive for ascending, non-positive for descending

OrderByPair

A [key: OrderByKey, direction: number] pair.

Type:
  • array

ProjectionDefinition

Type:
  • Object
Properties:
Name Type Description
name string

name of the projection
handler ProjectionHandler

The callback to transform the state
defaults Object

The default configuration of the projection
normalize function

The callback to normalize the projection configurations.

ProjectionHandler(state, config)

Parameters:
Name Type Description
state DataChainState | StructureChainState | ContentChainState

The input state.
config Object

The projection configuration object.
Returns:

The output state or the Promise of the output state.

Type
DataChainState | StructureChainState | ContentChainState | Promise

PropertyCallback(item [, value])

It behaves as a PropertyGetter when passed 1 argument, and behaves as a PropertySetter when passed 2 arguments.

Parameters:
Name Type Argument Description
item Object

The data item.
value <optional>

The new value for the property.
Returns:
  • The value for the property.

PropertyConfig

Type:
  • Object
Properties:
Name Type Description
get PropertyGetter

The getter function.
set PropertySetter

The setter function.

PropertyGetter(item)

Parameters:
Name Type Description
item Object

The data item.
Returns:
  • The value for the property.

PropertySetter(item, value)

Parameters:
Name Type Description
item Object

The data item.
value

The value for the property.

QueryConfig

The data source configurations.

Type:
  • Object
Properties:
Name Type Description
orderby OrderByConfig

The sorting parameter.
filter Object

The filter object in MangoDB format.
skip number

The number of item to skip from the query result.
take number

The number of item to take from the query result.

RowConfig

Configuration for a row. It can be an object or a special

Type:
  • string | Object
Properties:
Name Type Argument Description
type string <nullable>

Optional parameter to define the type of the row. Special values are

  • 'data-rows'. A row configuration which will be expanded into multiple rows representing each of the data items.
  • 'data'. Indicating the row is expanded from the 'data-rows'.
classes ClassesConfig <nullable>

The classes of the TR element.
attributes AttributesConfig <nullable>

The attributes of the TR element.
item Object <nullable>

The data item for the row.
html string <nullable>

The HTML string rendered in a cell taking the entire row.
view Backbone.View <nullable>

The Backbone View take the place of the entire row. This is is only for the header and footer rows.

RowContent

Extends the RowConfig with extra properties

Type:
Properties:
Name Type Description
cells Array.<CellContent>

The cells in the row.
attributes Object.<string, string>

The HTML attributes for the TR element.

RowsConfig

The configuration for rows projection. When defining header rows, it can be a special string 'column-header-rows', representing all the column header rows.

Type:
  • string | Object
Properties:
Name Type Description
headRows Array.<RowConfig>

Row configurations for THEAD. It can take a special string value column-header-rows, which will be expanded into the column headers.
bodyRows Array.<RowConfig>

Row configurations for TBODY. It can take a special row with type data-rows. This row will be expanded, one for each data item.
footRows Array.<RowConfig>

Row configurations for TFOOT.

ScrollingConfig

Type:
  • Object
Properties:
Name Type Description
virtualized boolean

flag for virtualization.
viewport string | HTMLElement | jQuery | window

the scrolling viewport. If omit, the table view will auto detect the closest ancestor of the $el with 'overflowY' style being 'auto' or 'scroll'. Use the window viewport if found none.

NOTE: the viewport takes no effect when using fixed header. Tables with fixed header render its viewport inside, as the container of the body and footer.
header string | HeaderConfig

the header scrolling behavior configurations. It can be a string to indicate the header type ('static', 'sticky' or 'fixed'). Or an detailed configuration object.

SelectableCallback(item)

Callback to decide whether a row is selectable.

Parameters:
Name Type Description
item Object

The data item of the row.
Returns:
Type
boolean

SelectionConfig

Type:
  • Object
Properties:
Name Type Description
enabled boolean

Whether the selection feature is enabled.
single boolean

True if only 1 row can be selected at the same time.
selected Array.<string>

The primary key of rows being selected.
selectable SelectableCallback

A callback to decide whether a row is selectable.
colClasses ClassesConfig

The classes of the 'COL' element for the selection column.
headClasses ClassesConfig

The classes of the 'TH' element in 'THEAD' of the selection column.
bodyClasses ClassesConfig

The classes of the 'TD' elements in 'TBODY' of the selection column.
footClasses ClassesConfig

The classes of the 'TD' elements in 'TFOOT' of the selection column.

SetRowsCallback(rows)

Parameters:
Name Type Description
rows Array.<RowConfig>

The current row configurations.
Returns:
  • The new row configurations.
Type
Array.<RowConfig>

SortableConfig

Type:
  • Object
Properties:
Name Type Description
key string | PropertyGetter

The sort key. It could be

  • A string, the key path of the sorting values.
  • A PropertyGetter to get the sorting values from data items. Only available for memory data source.
direction number | Array.<number>

The direction could be

  • A number A number indicating the order on first click. Positive for ascending, otherwise descending.
  • An array of numbers Indicating the sequence of sorting orders.
template SortableHeaderTemplate

A customized template to render the sortable column header.

SortableHeaderConfig

Type:
  • Object
Properties:
Name Type Argument Description
name string

The name of the ordered column.
directionIndex number

The index of direction in the direction sequence.
template SortableHeaderTemplate <nullable>

The template to render the sortable column headers.

SortableHeaderTemplate(locals)

Parameters:
Name Type Description
locals Object
Properties
Name Type Description
html string

The original HTML string for the column header.
direction number

The sort state.

  • Positive value for ascending.
  • Negative value for descending.
  • 0 for not sorted.

StructureChainState

It extends the DataChainState with extra properties.

Type:
Properties:
Name Type Description
columns Array.<ColumnConfig>

The array of column configurations.
headRows Array.<RowConfig>

The row configurations for THEAD.
bodyRows Array.<RowConfig>

The row configurations for TBODY.
footRows Array.<RowConfig>

The row configurations for TFOOT.