Class: DataView

DataView

dataview.js, line 268

Creates a new instance of DataView.

Parameters:
Name Type Description
container HTMLElement

Container node the grid attached.

data Array | Object

An array of objects for the grid model or a dataSource object, see dataSource definition for details.

config Array | Object

An array of column definitions or a JSON object used to deserialize the grid. If it is an array of column objects, the column object contains the following properties:

Name Type Default Description
id string

A unique identifier for the column.

caption string optional

Sets the display name of the column header. For a bound column, the default value is the string of the dataField, for others, the default value is null.

isCollapsed boolean true optional

Indicates whether the initial column group is collapsed.

dataField string optional

The string name of the property in the data model you want the column to refer to. The prefix a '=' if it is a calculated column or different column types.

cssClass string optional

The default css class for cells in this column or a function.

dataType string optional

Gets or sets the type of value stored in this column. Values are coerced into the proper type when editing the grid. The available data types are Array, Boolean, Date, Number, Object, and String.

editor object optional

The GeneralEditor will be used if not specified. The user can define their own custom editors for different field types.

allowEditing boolean true optional

Defines whether the cells in this column can be edited.

allowResizing boolean true optional

If false, the column can no longer be resized.

colHeaderPresenter string optional

Used to define the appearance of cell in the column header.

presenter string optional

Used to define the appearance of cells in the column. notice that if you use doT expression, the value passed to evaluate the template will be the formatted value.

asyncRender function optional

Used to load heavy javascript widget asynchronously in column..

format string | Object optional

Used to format the value of data items to different forms of text. This can be a string or a function, see GC.Spread.Views.DataView~formatCallback.

visible boolean true optional

Whether the column is visible by default.

width string optional

Sets the width of the column. Can be any positive number (column width in pixels), null, negative number (use the layoutEngine default column width), or string in the format '{number}' (start sizing). If this option is omitted, it uses the layout engine default column width. Start-sizing allows you to define columns that automatically stretch to fill the width available. For example, if a grid has three columns with widths '100', '', and '3*' the first column is 100 pixels wide, the second takes up to 1/4th of the remaining space, and the last takes up the remaining 3/4ths of the remaining space.

minWidth number optional

Sets the minimum width of the column. Can be any positive number. If this option is omitted, it uses the layout engine default minimum column width as the default value.This option takes effect on GridLayout or HorizontalLayout.

allowSorting boolean optional

If true, clicking on the column header sorts this column.

allowGrouping boolean optional

If true, the column can be grouped with drag and drop.

pinned string optional

Can be 'left' or 'right' to pin columns left or right.

columns Array optional

A child column object array that contains columns in the column group.

headerGroupShow boolean optional

Indicates when to show a child column in a column group. There are two values: expanded: the column is only shown when the group is expanded. collapsed: the column is only shown when the group is collapsed.

action Array optional

An array of actions for the column.

Name Type Description
name string

A unique identifier for the action.

handler Object optional

The action handler.

presenter string optional

The action presenter to allow the user to click.

flickAction string optional

Determines if this action is executed when the user flicks a row. There are two values, 'left' and 'right'. Left means to execute the action when flicking left. Right means to execute the action when flicking right.

swipeDirection string optional

Specifies when to show the swipe column. If allowSwipe is true and this property exists, the column is hidden by default and only shows when swiping in the same direction.

headerRow Object optional

An object used to define the header row settings.. The object looks like {renderer: "" or function }.

footer string optional

The renderer or aggregate formuals for the column on grid footer.

groupFooter string optional

The renderer or aggregate formuals for the column on group footer.

ganttColumn Object optional

An object defines the gantt column. Only one gantt column is allowed.

Name Type Description
id string optional

Id of gantt column.

timeLineScale string optional

Enumerates the value of ["day", "month", "hour", "year", "quarter"] to define the date label of gantt. The default value is "week".

scale number optional

Pixel unit of bottom span in the time label. Can be a decimal.

start string | date | number optional

The column defines the start date of gantt task.

end string | date | number optional

The column defines the end date of gantt task.

text string optional

The column renders the text on gantt task body.

predecessorID string optional

The column defines the gantt task processing line.

percentComplete string optional

The column defines the complete percentage of gantt task.

layoutEngine Object

A layoutEngine instance.

Classes

Methods

dataview.js, line 4331

staticGC.Spread.Views.DataView.getControlByElement(node){Object}

Gets the instance of DataView which is hosted to the specified node.

Parameters:
Name Type Description
node Element

An HTML element which is used to host the DataView instance.

Returns: {Object} A DataView instance.
dataview.js, line 923

cancelBatchEdit()

Cancel batch edit and clear changes.

dataview.js, line 1866

cancelEditing()

Cancels editing the current row.

dataview.js, line 1886

clearSelection()

Clear selection.

dataview.js, line 1122

destroy()

Removes the DataView instance from the host and destroys all resources used by the current instance which includes layout engine and group strategy.

dataview.js, line 693

formatDataItem(dataItem){Object}

Formats the dataItem based on column formats.

Parameters:
Name Type Description
dataItem Object

Object that needs to be formatted.

Returns: {Object} The formatted object.
dataview.js, line 892

getCachedBatchActions()

Get cahced actions which havn't been saved.

dataview.js, line 770

getItem(index){GC.Spread.Views.DataView.itemInfo|Array}

Gets item information by given index or row id.

Parameters:
Name Type Description
index Number | string | Array

The input view index or row id, can be an array. notice that the index is the view index in control.

Returns: {GC.Spread.Views.DataView.itemInfo|Array} The queried item information.
dataview.js, line 806

Gets the layout information of the current instance.

Returns: {GC.Spread.Views.DataView.layoutInfo} An object which uses the area name as the key and the layout information as the value.
dataview.js, line 838

Gets the render information.

Parameters:
Name Type Description
option Object

An object used to specify the area, horizontal scroll offset, and vertical offset. The object indicates whether the return value contains row render infos.

Name Type Default Description
area string

The area name.

offsetTop number

The vertical scroll offset.

offsetLeft number

The horizontal scroll offset.

includeRows boolean true optional

Whether the rows render information is contained in the result.

Returns: {GC.Spread.Views.DataView.renderInfoObj} The render information result.
dataview.js, line 1338

getRowId(hitInfo){string}

Util method, used to get the corresponding row element id from hitInfo

Parameters:
Name Type Description
hitInfo GC.Spread.Views.DataView.hitTestInfoObj

hit test result, can get this by calling hitTest method

Returns: {string} row element id
dataview.js, line 1353

getRowInfoFromId(rowId){object}

Util method, used to get the row info from row id

Parameters:
Name Type Description
rowId string

the id of the row

Returns: {object} row info.
dataview.js, line 1874

getSelections(){Array}

Gets the data of selected rows.

Returns: {Array} The information of selected rows, including data, sourceRow and columns id.
dataview.js, line 939

hideLoadingOverlay()

Hide built-in loading overlay

dataview.js, line 885
Parameters:
Name Type Description
e TouchEvent | MouseEvent
Returns: {GC.Spread.Views.DataView.hitTestInfoObj} The hit test information.
dataview.js, line 1178

invalidate(rebuildDOMTree)

Invalidates the entire control.

Parameters:
Name Type Description
rebuildDOMTree boolean

Whether to rebuild the entire DOM tree. If true, it replaces the old DOM tree with a new one; otherwise, it updates the old DOM tree container and refreshes each layout area. The default value is true.

dataview.js, line 1364

refresh(area)

Refreshes the specified part of the grid.

Parameters:
Name Type Description
area string

The area that needs to be refreshed.

dataview.js, line 908

saveBatchEdit(callback)

Save batch edit changes.

Parameters:
Name Type Description
callback function

callback function which will be executed after save all actions to server return results.

dataview.js, line 1898

setSelections(sourceRow, columns)

Set selection.

Parameters:
Name Type Description
sourceRow number | Array

The source row index or source row indexes array of selected row.

columns string | Array

The column id collection of selected row. It will work if selectionUnit is cell.

dataview.js, line 932

showLoadingOverlay()

Show built-in loading overlay

dataview.js, line 1821

startEditing(viewIndex, colIndex)

Starts to edit the current row

Parameters:
Name Type Description
viewIndex number | string

The dataview row viewIndex or id.

colIndex number

DataView column index.

dataview.js, line 1860

stopEditing()

Stops editing the current row and commits the new value.

dataview.js, line 1707

toJSON(){Object}

Serializes the current instance to a JSON object

Returns: {Object} A JSON object
dataLoader.js, line 210

innerfailedCallback(error)

failedCallback function need to be called after user retrieve/operate data from server by CRUD/batch.

Parameters:
Name Type Description
error Object

Error information.

dataLoader.js, line 202

innersuccessCallback(data, dataSourceLength)

successCallback function need to be called after user retrieve/operate data from server by CRUD/batch.

Parameters:
Name Type Description
data Array | Object

The requested data. When used in batch edit, it is the responses Array of server.

dataSourceLength number nullable

Change the length of data, used only in loadRange callback.

Type Definitions

GC.Spread.Views.DataView.hitTestInfoObjObject

An object used to represent the hitTest result.

Properties:
Name Type Argument Description
area string

The area name.

row number

The row index, if groupInfo or nodeInfo is not empty, should use row in groupInfo or nodeInfo

column number <optional>

The column index of the row, if groupInfo or nodeInfo is not empty, should use column in groupInfo or nodeInfo

headerInfo object <optional>

The headerInfo object. If the area is columnHeader, there is a headerInfo object which contains more details.

Properties
Name Type Argument Description
inResizeMove boolean <optional>

Indicates whether the column can be resized.

inHeaderRow boolean <optional>

Indicates whether this is in the column header row.

resizeFromZero boolean <optional>

Indicates whether the column can be resized when its width is zero.

onTreeExpandToggle boolean <optional>

Indicates whether this is on the tree expand toggle button. This property only occurs when there is no grouping; otherwise, it is on the groupInfo object.

isHierarchyFooter boolean <optional>

Indicates whether this is on the tree footer. This property only occurs when there is no grouping; otherwise, it is on the groupInfo object.

groupInfo Object <optional>

The groupInfo object if there are groups.

Properties
Name Type Argument Description
area string

The area of the group, The value can be 'groupHeader', 'groupContent', or 'groupFooter'.

path Array.<number>

The path used to locate the group, i.e [0,1] means the first group of the root, then the second group in that group.

row number <optional>

The row index in the current group.

column number <optional>

The column index of the row.

onGroupExpandToggle boolean <optional>

Indicates whether this is on the group expand toggle button.

isHierarchyFooter boolean <optional>

Indicates whether this is on the tree footer in the group.

onTreeExpandToggle boolean <optional>

Indicates whether this is on the tree expand toggle button in the group.

GC.Spread.Views.DataView.itemInfoObject

An object.

Properties:
Name Type Description
groupArea string

The group area.

group DataManagerGroup

The group instance.

nodeArea string

The area of the tree node.

node DataManagerNode

The instance of the tree node.

item Object

The data item of the queried row.

GC.Spread.Views.DataView.layoutInfoObject

An object that uses the area name as the key and layout information as the value. It can contain arbitrary areas.

Properties:
Name Type Description
areaName GC.Spread.Views.DataView.layoutInfoObj

The area name.

GC.Spread.Views.DataView.layoutInfoObjObject

Properties:
Name Type Description
top number

The vertical offset between the container's top-left point and the top-left current viewport rectangle.

left number

The horizontal offset between the container's top-left point and the top-left current viewport rectangle.

height number

The height of the current viewport rectangle.

width number

The width of the current viewport rectangle.

contentHeight number

The height of the content area of the current viewport rectangle.

contentWidth number

The width of the content area of the current viewport rectangle.

GC.Spread.Views.DataView.renderInfoObjObject

An object used to present the render information object of a viewport.

Properties:
Name Type Description
outerDivStyle Object

The style object used for the outer div.

outerDivCssClass Object

The class list used for the outer div.

innerDivStyle Object

The style object used for the inner div.

innerDivTranslate Object

The translate object used to set the inner div translation.

Properties
Name Type Description
left number

The horizontal div.

top number

The vertical div.

renderedRows Array.<Object>

The collection of the render rows information.

Properties
Name Type Description
isRowRole boolean

Whether the role is 'row'. This is used for ARIA.

key string

The key of the row. It is used as the id for the row.

renderInfo Object

The render information of the row.

Properties
Name Type Description
cssClass string

The class list of the row.

renderedHTML string

The innerHTML of the row.

style Object

The style object of the row.

dataLoader.js, line 193

batchCallback(params)

This callback is displayed as part of the Requester class.

Parameters:
Name Type Description
params Object

The parameters.

Name Type Description
success GC.Spread.Views.DataView~successCallback

The success function which need to be called after succeed.

failed GC.Spread.Views.DataView~failedCallback

The failed function need to be called after failed.

actions Array

An array of GC.Spread.Views.DataView~CRUDaction which are the stored CRUD actions.

dataLoader.js, line 153

Callback(params)

This callback is displayed as part of the Requester class.

Parameters:
Name Type Description
params Object

The parameters.

Name Type Description
success GC.Spread.Views.DataView~successCallback

The success function which need to be called after succeed.

failed GC.Spread.Views.DataView~failedCallback

The failed function need to be called after failed.

start number

The index which the loaded data range starts. User can set.

size number

The loaded data range's length. User can set.

sort Array

An array of GC.Spread.Views.DataView.DataManager.sortDescriptor which are the current sorting status, for user to sort in server.

filter Array

An array of GC.Spread.Views.DataView.DataManager.filterDescriptor which are the current filtering status, for user to filter in server.

dataLoader.js, line 165

createCallback(params)

This callback is displayed as part of the Requester class.

Parameters:
Name Type Description
params Object

The parameters.

Name Type Description
success GC.Spread.Views.DataView~successCallback

The success function which need to be called after succeed. If server validated the dataItem and responsed with a new dataItem, user should call params.success(dataItem).

failed GC.Spread.Views.DataView~failedCallback

The failed function need to be called after failed.

dataItem Object

The created dataItem.

CRUDactionObject

CRUD action

Properties:
Name Type Argument Description
type string

The type of CRUD, could be 'create', 'update' and 'delete'.

dataItem Object

The dataItem to operate. When type is update, it is the updated new item.

index number <optional>

The dataItem's index in current view. Not exist when type is create.

oldDataItem Object <optional>

The dataItem before update. Only exist when type is update.

dataSourceObject

Data source object.

Properties:
Name Type Argument Description
loadRange GC.Spread.Views.DataView~loadRangeCallback <nullable>

The loadRange callback, called when dataView needs update.data

create GC.Spread.Views.DataView~createCallback <nullable>

The create callback, called when dataView create a new item.

update GC.Spread.Views.DataView~updateCallback <nullable>

The update callback, called when dataView edit an item.

delete GC.Spread.Views.DataView~deleteCallback <nullable>

The delete callback, called when dataView delete an item.

batch GC.Spread.Views.DataView~batchCallback <nullable>

The batch callback. In batch editing mode, called when user call saveBatchEdit.

batchEdit boolean

Decide whether to use batch edit. when batch edit mode applied, create, update, delete action won't request server data instantly, but will send a batch request after user call saveBatchEdit, and will recover to old status when user call cancelBatchEdit.

serverSideSort boolean

Whether to sort in user's server. If was set true, local sort is disabled.

serverSideFilter boolean

Whether to filter in user's server. If was set true, local filter is disabled.

dataLoader.js, line 184

deleteCallback(params)

This callback is displayed as part of the Requester class.

Parameters:
Name Type Description
params Object

The parameters.

Name Type Description
success GC.Spread.Views.DataView~successCallback

The success function which need to be called after succeed.

failed GC.Spread.Views.DataView~failedCallback

The failed function need to be called after failed.

dataItem Object

The dataItem to be removed.

dataview.js, line 96

formatCallback(args){string}

This callback is displayed as part of the Requester class.

Parameters:
Name Type Description
args object

The argument the format function will take.

Name Type Description
colId string

The id of column been format.

value object

The value to be format.

data object

The entire row data.

Returns: {string} The formatted value.
dataview.js, line 89

hierarchyOffsetCallback(node){number}

This callback is displayed as part of the Requester class.

Parameters:
Name Type Description
node dataManagerNode

The dataManager node to render.

Returns: {number} The offset value in pixels.
dataLoader.js, line 174

updateCallback(params)

This callback is displayed as part of the Requester class.

Parameters:
Name Type Description
params Object

The parameters.

Name Type Description
success GC.Spread.Views.DataView~successCallback

The success function which need to be called after succeed.

failed GC.Spread.Views.DataView~failedCallback

The failed function need to be called after failed.

dataItem Object

The new dataItem.

oldDataItem Object

The old dataItem to update.

layoutEngines/gridlayout.js, line 44

updateOverlayStatusCallback(args)

This callback will be called when loading data from remote server if exist, otherwise, the control will call built-in showLoadingOverlay before loading data and call hideLoadingOverlay after loading data.

Parameters:
Name Type Description
args object

The argument the callback function will take.

Name Type Description
newStatus string

the new status of the overlay will change to, the value can be 'show' or 'hide'.

Events

dataview.js, line 211

GC.Spread.Views.DataView.#event:collectionChanged

Occurs after data has changed, such as after sorting, filtering, or grouping.

Type:
  • object
Properties:
Name Type Description
sender Object

The control instance that causes this event to occur.

args Object

Provides arguments that are useful for the event.

Properties
Name Type Description
action Object

The type of data changed event.

dataview.js, line 138

columnChanged

Occurs when the user changes the column visibility, pinned option, or column width, or expands or collapses the column group from UI.

Type:
  • object
Properties:
Name Type Description
sender Object

The control instance that causes this event to occur.

args Object

Provides arguments that are useful for the event.

Properties
Name Type Description
type string

Indicates the column change type. The type can be 'visible', 'pinned', 'resized', or 'groupCollapsed'.

index string | number

The current column that fired the event. If the value is string, it indicates a column group and the value is the group caption. If the value is number, it indicates a single column and the index is in the Grid.columns collection.

oldValue string | number

The old value.

newValue string | number

The new value.

dataview.js, line 124

columnReorder

Occurs when the user starts dragging the column and before dropping the column in the column header.

Type:
  • object
Properties:
Name Type Description
sender Object

The control instance that fires this event.

args Object

Provides arguments that are useful for the event.

Properties
Name Type Description
status string

Indicates the editing status. The status can be 'beforeColumnReorder' and 'endColumnReorder'.

oldIndex string | number

The original index of the reordered column. If the value is string, it indicates the current reorder target is a column group and the value is the group caption. If the value is a number, it indicates the reorder column is a single column. The index is in the Grid.columns collection.

newIndex string | number

The drop target column. If the value is a string, it indicates the current reorder target is a column group and the value is the group caption. If the value is a number, it indicates the reorder column is a single column and the index is in the Grid.columns collection.

insertBefore boolean

If it is set to true, the column is inserted before the drop target; otherwise, it is inserted after the target.

cancel boolean

If it is set to true, the action is canceled.

dataview.js, line 106

editing

Editing event. The event occurs before editing, once editing has started, before editing has ended, or editing has stopped.

Type:
  • object
Properties:
Name Type Description
sender Object

The control instance that causes this event to occur.

args Object

Provides arguments that are useful for the event.

Properties
Name Type Description
status string

Indicates the editing status. The status can be 'beforeStartEditing', 'startEditing', 'beforeEndEditing', 'endEditing' or 'cancelEditing'.

groupInfo Object

The group information for the data.

row number

The editing row index.

oldItem Object

The original data of the editing row.

newItem Object

The new data of the editing row.

cancel boolean

If it is set to true, the current status is canceled. It can be used when status is 'beforeStartEditing' or 'beforeEndEditing'.

useDecodedItem boolean

If it is set to true, special charactors are decoded. It can be used when status is 'beforeStartEditing'. The default value is true.

useEncodedItem boolean

If it is set true, special charactors are encoded. It can be used when status is 'beforeEndEditing'. The default value is true.

isNewRow boolean

Indicates whether editing in new row.

dataview.js, line 176

focusChanged

The focused row changed event.The event fires on GridLayout or HorizontalLayout.

Type:
  • object
Properties:
Name Type Description
sender Object

The control instance that causes this event to occur.

args Object

Provides arguments that are useful for the event.

Properties
Name Type Description
sourceRow number

Indicates the source data row index of the current focused row, it is -1 if the focused row element has no mapping source data.

column number

Indicates the focused column, it is -1 if the focus unit is row.

dataview.js, line 151

grouping

Occurs when the user updates groups with UI actions. The event is fired before the actual update happens.

Type:
  • object
Properties:
Name Type Description
sender Object

The control instance that causes this event to occur.

args Object

Provides arguments that are useful for the event.

Properties
Name Type Description
action string

Indicates the group action. The group action can be 'insert', 'remove', or 'reorder'

oldIndex number

If the action is 'remove', the groupDescriptor index is removed. If the action is 'reorder', the old index of the reorder groupDescriptor is used.

newIndex number

If the action is 'insert', the index of the new group descriptor is inserted before. If the action is 'reorder', the new index of the reordered groupDescriptor in the old collection is inserted before.

cancel boolean

If it is set to true, the action is canceled.

newGroupDescriptor object

The new group descriptor to be inserted . See groupDescriptor for details.

dataview.js, line 187

rowClick

Occurs when clicking the row.

Type:
  • object
Properties:
Name Type Description
sender Object

The control instance that causes this event to occur.

args Object

Provides arguments that are useful for the event.

Properties
Name Type Description
event Object

The original event triggered by the browser.

hitInfo Object

The hit information when clicking.

item Object

The dataItem of the clicked row.

idList Object

The row elements' id list.

dataview.js, line 199

rowDbClick

Occurs when double-clicking the row.

Type:
  • object
Properties:
Name Type Description
sender Object

The control instance that causes this event to occur.

args Object

Provides arguments that are useful for the event.

Properties
Name Type Description
event Object

The original event triggered by the browser.

hitInfo Object

The hit information when double-clicking.

item Object

The dataItem of the clicked row.

idList Object

The row elements' id list.

dataview.js, line 165

selectionChanged

Occurs when the user changes the selection using UI actions.

Type:
  • object
Properties:
Name Type Description
sender object

The control instance that causes this event to occur.

args object

Provides arguments that are useful for the event.

Properties
Name Type Description
event Object

The event.

rows Array

That new selected rows information. Including sourceRow index and column id.