Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/support
esri/workers
Class: FeatureTable

dojo.require("esri.dijit.FeatureTable");

Description

(Added at v3.12)

Creates an instance of the FeatureTable widget within the provided DOM node. The FeatureTable is a widget-based solution for where you explore and optionally edit the attribute data of a feature layer. The FeatureTable also integrates any additional information such as related records and attachments. Feature attributes displayed in the table can be edited by setting FeatureTable's editable property to true. However, setting this property to true does not make the layer editable if the editing capability for the service is set to false on the server. The pieces of related information can be exposed as columns directly in the table by setting FeatureTable's showRelatedRecords property to true. The attachments can also be displayed in the table by setting its showAttachments property to true. To help distinguish the related records and attachments from the fields in the table, the related records and attachment columns are appended to the end of the table, with the column names shown in italics. Each record in the table shows the number of related records and attachments associated with it.

As a developer you have the option to select or filter features in the table. If you call FeatureTable's selectRows() method, the selected records will be highlighted in the table while all other records remain visible. When FeatureTable's clearSelection() method is called, the selection/highlights will be removed from the table. If you call FeatureTable's filterRecordsByIds() or filterSelectedRecords() the table will only display those records that were filtered. FeatureTable's clearFilter() method will remove the filter as well as the selection/highlight from the table.

At 3.18, editing is allowed on any field in the table. This includes fields that define the relationships. However, if you edit a field that has a defined relationship, the table does not immediately update the related records. You will need to refresh the page to see the updated related records.

At 3.27, the table will automatically refresh if a feature layer has a refreshInterval set.

Samples

Search for samples that use this class.

Constructors

NameSummary
new esri.dijit.FeatureTable(params, srcNodeRef)Creates an instance of the FeatureTable widget within the provided DOM node.

CSS

esri/dijit/FeatureTable | Download source

Properties

NameTypeSummary
batchCountNumberThe number of features a service will try to fetch.
columnsObject[]Read-only: A reference to the column objects and their parameters.
dataStoreObjectRead-only: Reference to the dataStore used by the dGrid.
dateOptionsObjectObject defining the date options specifically for formatting date and time editors.
editOnString | a11yclickEvent trigger(s) used to display editing interface for an individual cell.
editableBooleanSets the editing state for the FeatureTable.
featureCountNumberRead-only: Number of records displayed in FeatureTable.
featureLayerFeatureLayerThe featureLayer that the table is associated with.
fieldInfosObject[]An array of objects representing field information.
gridObjectReference to the dGrid.
gridMenuObjectReference to the 'Options' drop-down menu.
gridOptionsObjectObject that can be used to set properties used by the underlying dgrid.
hiddenFieldsString[]Optional columns to hide by default using the dGrid ColumnHider extension.
idPropertyStringRead-only: A reference to the primary key used by the dataStore to differentiate columns.
loadedBooleanWhen true, the FeatureTable widget has successfully loaded.
mapMapReference to the map.
menuFunctionsObject[]Adds additional functional menu items for the 'Options' drop-down menu.
outFieldsString[]Attribute fields to include in the FeatureTable.
selectedRowIdsNumber[]Read-only: A comma delimited array of ObjectIds for the features selected in the FeatureTable.
selectedRowsObject[]Read-only: Each element in the array is an object that contains name-value pair of fields and field values associated with the selected rows.
showAttachmentsBooleanDisplays or hides the attachment column.
showColumnHeaderTooltipsBooleanDisplays or hides tooltips for column headers.
showCyclicalRelationshipsBoolean Relies on showRelatedRecords property.
showDataTypesBooleanDisplays or hides the data type of the field right under the field label in the column header.
showFeatureCountBooleanDisplays or hides total number of features and selected number of features in the grid header.
showGridHeaderBooleanDisplays or hides the FeatureTable header.
showGridMenuBooleanDisplays or hides 'Options' drop-down menu of the FeatureTable.
showRelatedRecordsBooleanDisplays or hides the option to show related records in a table if the layer has pre-established relationship.
showStatisticsBooleanDisplays or hides the 'Statistics' option in column menus for numeric fields.
syncSelectionBooleanEnables an interaction between the map and the feature table.
zoomToSelectionBooleanEnables pans to selected features on the map when the table in 'sync selection' mode.

Methods

NameReturn typeSummary
centerOnSelection()NoneCenters the map on combined extent of selected rows.
clearFilter()NoneRemoves all filters and selections in the table.
clearSelection()NoneRemoves all selections.
destroy()NoneDestroys the FeatureTable widget.
filterRecordsByIds(ids)NoneFilters the table based on the provided row ids.
filterSelectedRecords()NoneAllows users to see the sub-set of records.
getFeatureDataById(id)DeferredQueries and gets selected features from the FeatureLayer instead of the store.
getRowDataById(id)ObjectGets row object by the row ID.
refresh()NoneRefreshes the data in the table.
resize()NoneResizes the grid's container.
selectRows(ids, scrollToRow?)NoneAllows users to select rows(s) based on row id(s).
sort(field, descending?)NoneSorts a given field in ascending or descending order.
startup()NoneFinalizes the creation of the widget.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
clear-selectionThis event fires in response to clearSelection() method.
column-resize
{
  resizeEvent: <Object>
}
Fires when the grid column is resized.
column-state-change
{
  stateChangeEvent: <Object>
}
Fires when a column is hidden or shown via 'Options' drop-down menu.
data-changeFires when grid editor field loses focus after being changed.
editor-hideFires when grid editor is hidden.
editor-showFires when grid editor is shown.
edits-complete
{
  adds: <FeatureEditResult[]>,
  deletes: <FeatureEditResult[]>,
  updates: <FeatureEditResult[]>
}
Fires when editing is complete.
errorFires when an error occurs in the grid.
filter
{
  ids: <Number[]>
}
Fires when grid is filtered.
loadFires when the FeatureTable is loaded.
refreshFires when the grid is refreshed.
row-deselect
{
  event: <Object>
}
Fires when a row is deselected.
row-select
{
  event: <Object>
}
Fires when a row is selected.
show-attachments
{
  attachments: <Object>,
  dialog: <Object>,
  featureId: <Number>
}
Fires when attachment is displayed in the table.
show-related-records
{
  features: <Graphic[]>,
  relationship: <Object>,
  row: <Object>
}
Fires when related records are displayed in the table.
show-statistics
{
  statistics: <Object>
}
Fires when the statistics dialog box shows the calculated statistics on a column with numeric data.
sort
{
  sortEvent: <Object>
}
Fires when a column is sorted.
Constructor Details

new esri.dijit.FeatureTable(params, srcNodeRef)

Creates an instance of the FeatureTable widget within the provided DOM node.
Parameters:
<Object> params Required Various options to configure this dijit. All the properties can be passed into the params object.
<Node | String> srcNodeRef Required Reference or id of a HTML element that this dijit is rendered into.
params properties:
<Number> batchCount Optional The number of features a service will try to fetch.
<Object> dateOptions Optional Object defining the date options specifically for formatting date and time editors. See the object specifications table below.
<Boolean> editable Optional Sets the editing state for the FeatureTable.
<FeatureLayer> featureLayer Required The featureLayer that the table is associated with.
<Object[]> fieldInfos Optional An array of objects representing field information. Use this property to customize how fields appear in the feature table. Setting this property for the given field will overwrite the properties of the same field set on other objects. If nothing is specified, all fields, except the ObjectId and GlobalId are displayed. (Added at v3.16)
<Object> gridMenu Optional Reference to the 'Options' drop-down menu. For additional information, please see the Dojo dijit/Menu for additional information.
<Object> gridOptions Optional Object that can be used to set properties used by the underlying dgrid.
<String[]> hiddenFields Optional Columns to hide by default using the dGrid ColumnHider extension.
<Map> map Optional A reference to the Map.
<Object[]> menuFunctions Optional Adds additional functional menu items for the 'Options' drop-down menu.
<String[]> outFields Optional Attribute fields to include in the FeatureTable. Fields must exist in the layer. The order of the fields in the array defines the order of fields in the FeatureTable. You must list the actual field names rather than the alias names. However, the alias names are used to display the results.
<Boolean> showAttachments Optional Displays or hides the attachment column. FeatureLayer.hasAttachments must be true (attachments must be enabled on the layer).
<Boolean> showColumnHeaderTooltips Optional Displays or hides tooltips for column headers.
<Boolean> showCyclicalRelationships Optional Shows or hides cyclical relationship.
<Boolean> showDataTypes Optional Displays the data type of the field right under the field label. Default value is false<\code>.
<Boolean> showFeatureCount Optional Displays or hides total number of features and selected number of features in the grid header.
<Boolean> showGridHeader Optional Displays or hides the FeatureTable header. Default value is true.
<Boolean> showGridMenu Optional Displays or hides 'Options' drop-down menu of the FeatureTable. Default value is true.
<Boolean> showRelatedRecords Optional Displays or hides the option to show related records in a table if the layer has pre-established relationship.
<Boolean> showStatistics Optional Displays or hides the 'Statistics' option in column menus for numeric fields.
<Boolean> syncSelection Optional Enables an interaction between the map and the feature table. Setting this property to true allows selection of a feature on a map via clicking row in the table, and selection of a table's row via clicking a feature on the map. Default value is true.
<Boolean> zoomToSelection Optional Enables pan/zoom to selected features on the map when the table in 'sync selection' mode. Default value is true.
Object Specifications:
<dateOptions>
<String> datePattern Required Example: "yyyyMMdd" For additional information on this, see dojo/date/locale documentation.
<Boolean> timeEnabled Required True | False indicating whether to enable time. Default is false.
<String> timePattern Required Example: "HH:mm:ss" For additional information on this, see dojo/date/locale documentation.
Property Details

<Number> batchCount

The number of features a service will try to fetch. (Added at v3.17)
Default value: 50

<Object[]> columns

Read-only: A reference to the column objects and their parameters.

<Object> dataStore

Read-only: Reference to the dataStore used by the dGrid.

<Object> dateOptions

Object defining the date options specifically for formatting date and time editors. Setting this on the FeatureTable will affect all date fields. Use dateOptions property on fieldInfos to define See the object specifications table below.
Object Specifications:
<dateOptions>
<String> datePattern Required Example: "yyyyMMdd" For additional information on this, see dojo/date/locale documentation.
<Boolean> timeEnabled Required True | False indicating whether to enable time. Default is false.
<String> timePattern Required Example: "HH:mm:ss" For additional information on this, see dojo/date/locale documentation.

<String | a11yclick> editOn

Event trigger(s) used to display editing interface for an individual cell.
For touch-enabled devices, the default value is a11yclick (Added at v3.17)
Default value: "dblclick, keypress"

<Boolean> editable

Sets the editing state for the FeatureTable. Setting this property to true does not override a false value from the server. (Added at v3.16)
Default value: false

<Number> featureCount

Read-only: Number of records displayed in FeatureTable.

<FeatureLayer> featureLayer

The featureLayer that the table is associated with.

<Object[]> fieldInfos

An array of objects representing field information. Use this property to customize how fields appear in the feature table. Setting this property for the given field will overwrite the properties of the same field set on other objects. If nothing is specified, all fields, except the ObjectId and GlobalId are displayed. (Added at v3.16)
Object Specifications:
<fieldInfos>
<String> alias Optional The label to display. The default value is the field alias.
<Object> dateOptions Optional Object defining the date options specifically for formatting date and time editors. See dateOptions.
<Boolean> editable Optional Disable editing of the field. Setting this property to true does not override a false value from the server.
<Object> format Optional Use this property to format text, numeric, domain and subtype fields. The feature table will display url strings as hyperlinks. Set format.link property to false if you do not wish to display url strings as hyperlinks. Use format.template to define field content by specifying a string or markup that can include field values. Numeric formatters are specified by supplying the number of decimal places and optionally if the number should have a digit separator. The digitSeparator will be a comma or decimal point depending on the locale. See a sample snippet below.
  format: {
    link: false, //opt out of showing urls as clickable links
    embeddedHTML: true, //renders raw html in field values
    template: "${value}", //put content before and after the wildcard 
    places: 3, //number of decimal places 
    digitSeparator: false //default is true 
  }
<String> name Required The name of the field.
<Boolean> visible Optional Hide or display the field in the FeatureTable.

<Object> grid

Reference to the dGrid. Deprecated at v3.17

<Object> gridMenu

Reference to the 'Options' drop-down menu. For additional information, please see the Dojo dijit/Menu for additional information. (Added at v3.15)
Default value: null

<Object> gridOptions

Object that can be used to set properties used by the underlying dgrid. (Added at v3.16)
Object Specifications:
<gridOptions>
<Boolean> allowSelectAll Optional An optional dGrid property. Determines whether the "select-all" action should be permitted via a checkbox selector column or the Ctrl/Cmd+A keyboard shortcut; defaults to false.
<Boolean> allowTextSelection Optional An optional dGrid property. Optional boolean indicating whether normal text selection within grid cells should be prevented. By default, text selection is prevented unless selectionMode is set to none; setting this property to true or false will enable or disable text selection regardless of selectionMode.
<Boolean> cellNavigation Optional An optional dGrid property. Boolean indicating whether keyboard navigation should occur at the row or cell level.
Default Value: true
<Boolean> columnHider Optional An optional dGrid property. When false 'Show/Hide Columns' command will be removed from the `Options` menu. Without columnHider visible, the columns cannot be hidden.
Default Value: true
<Boolean> columnResizer Optional An optional dGrid property. If true (the default), adjusts the last column's width to "auto" at times where the browser would otherwise stretch all columns to span the grid.
Default Value: true
<String> noDataMessage Optional An optional dGrid property. A message to be displayed when the query yields no results.
<Number[]> pageSizeOptions Optional An optional dGrid property. An optional array specifying choices to present for the rowsPerPage property in a drop-down. If unspecified or empty, no drop-down is displayed (the default behavior).
<Boolean> pagination Optional An optional dGrid property.
<Number> pagingDelay Optional The minimum amount of time in milliseconds to wait after scrolling occurs before requesting items from the server.
Default Value: 300
<String> selectionMode Optional An optional dGrid property. String indicating how selection should behave in response to direct user interaction.
<Object> sort Optional Overrides the default sort field which is FeatureLayer.objectidfield. At 3.17, sort property value was a string. As of 3.18, it is an object where you can specify field name and whether you want to sort the field ascending or descending order. See a sample snippet below.
  sort: {
    field: "StateName", //field name 
    descending: true
  }

<String[]> hiddenFields

Optional columns to hide by default using the dGrid ColumnHider extension.

<String> idProperty

Read-only: A reference to the primary key used by the dataStore to differentiate columns.

<Boolean> loaded

When true, the FeatureTable widget has successfully loaded.
Known values: true | false

<Map> map

Reference to the map.

<Object[]> menuFunctions

Adds additional functional menu items for the 'Options' drop-down menu. Each object in the array represents an individual menu item. The object has two properties. See the object specifications table below for the structure of the menuFunctions object. (Added at v3.16)
Object Specifications:
<menuFunctions>
<Function> callback Required Represents a self-contained function that would trigger in response to menu item click event.
<String> label Required Represents drop-down menu item label.

<String[]> outFields

Attribute fields to include in the FeatureTable. Fields must exist in the layer. The order of the fields in the array defines the order of fields in the FeatureTable. You must list the actual field names rather than the alias names. However, the alias names are used to display the results.

<Number[]> selectedRowIds

Read-only: A comma delimited array of ObjectIds for the features selected in the FeatureTable. (Added at v3.16)

<Object[]> selectedRows

Read-only: Each element in the array is an object that contains name-value pair of fields and field values associated with the selected rows. (Added at v3.16)

<Boolean> showAttachments

Displays or hides the attachment column. FeatureLayer.hasAttachments must be true (attachments must be enabled on the layer). (Added at v3.17)
Default value: false

<Boolean> showColumnHeaderTooltips

Displays or hides tooltips for column headers. (Added at v3.18)
Default value: false

<Boolean> showCyclicalRelationships

Relies on showRelatedRecords property. Cyclical relationship is defined as:
* relationship is 1 TO 1 OR
* relationship is one to many and current related table role is a 'destination'

(Added at v3.18)
Default value: false

<Boolean> showDataTypes

Displays or hides the data type of the field right under the field label in the column header. Default value for this property is false. (Added at v3.16)
Default value: false

<Boolean> showFeatureCount

Displays or hides total number of features and selected number of features in the grid header. (Added at v3.17)
Default value: true

<Boolean> showGridHeader

Displays or hides the FeatureTable header. The FeatureTable header area shows the table name, total number of features and number of selected features displayed in the table. It also hosts 'Options' drop-down menu. (Added at v3.16)
Default value: true

<Boolean> showGridMenu

Displays or hides 'Options' drop-down menu of the FeatureTable. (Added at v3.15)
Default value: true

<Boolean> showRelatedRecords

Displays or hides the option to show related records in a table if the layer has pre-established relationship. FeatureTable allows you to edit any field in an editable layer. This includes fields that define the relationships. You will see these related records represented as columns with italicized headers on the right side of the table. (Added at v3.18)
Default value: false

<Boolean> showStatistics

Displays or hides the 'Statistics' option in column menus for numeric fields. (Added at v3.17)
Default value: true

<Boolean> syncSelection

Enables an interaction between the map and the feature table. Setting this property to true allows selection of a feature on a map via clicking a row in the table. However, it won't enable selection of records in the table when user clicks on a feature on the map. To enable selection from the map to the table, the developer must explicitly implement the layer's click logic. This is because the application might have its own selection logic elsewhere or their own click logic. (Added at v3.16)
Default value: false

<Boolean> zoomToSelection

Enables pans to selected features on the map when the table in 'sync selection' mode. (Added at v3.16)
Default value: false
Method Details

centerOnSelection()

Centers the map on combined extent of selected rows. (Added at v3.18)

clearFilter()

Removes all filters and selections in the table. (Added at v3.18)

clearSelection()

Removes all selections. (Added at v3.17)

destroy()

Destroys the FeatureTable widget. Call destroy() when the widget is no longer needed by the application.

filterRecordsByIds(ids)

Filters the table based on the provided row ids. Only filtered rows will be displayed in the table. (Added at v3.18)
Parameters:
<Number[]> ids Required Array of row ids.

filterSelectedRecords()

Allows users to see the sub-set of records. Only filtered rows will be displayed in the table. (Added at v3.17)

getFeatureDataById(id)

Queries and gets selected features from the FeatureLayer instead of the store. (Added at v3.17)
Return type: Deferred
Parameters:
<Number | Number[]> id Required Row id or an array of row ids

getRowDataById(id)

Gets row object by the row ID. (Added at v3.17)
Return type: Object
Parameters:
<Number> id Required row ID

refresh()

Refreshes the data in the table. It re-fetches features from the layer. For instance, it can be called after updating a layer's definitionExpression. (Added at v3.17)

resize()

Resizes the grid's container. (Added at v3.17)

selectRows(ids, scrollToRow?)

Allows users to select rows(s) based on row id(s). Selected rows will be highlighted while other records are still visible in the table. (Added at v3.18)
Parameters:
<Number | Number[]> ids Required Row id or an array of row ids
<Boolean> scrollToRow Optional Indicates whether the table should scroll to selected rows. If multiple row ids are provided, scrolls to first row in the array. Default value: false. Note that if scrollToRow is true, selection only occurs if rows are already displayed within the table. This is a known limitation with Dojo's dgrid.

sort(field, descending?)

Sorts a given field in ascending or descending order. Overrides the default sort field which is FeatureLayer.objectidfield. Featurelayer must support advanced queries when using this method. (Added at v3.18)
Parameters:
<String> field Required Name of the field
<Boolean> descending Optional Defines whether the specified field will be sorted in ascending or descending order. Default value: false

startup()

Finalizes the creation of the widget.
Event Details
[ On Style Events | Connect Style Event ]

clear-selection

This event fires in response to clearSelection() method. (Added at v3.18)

column-resize

Fires when the grid column is resized. See ColumnResizer Extension. (Added at v3.16)
Event Object Properties:
<Object> resizeEvent The dgrid column resizer event. This object has properties such as:
grid: The Grid instance in which this event occurred
columnId: The ID of the resized column
width: The new width of the column.

column-state-change

Fires when a column is hidden or shown via 'Options' drop-down menu. See ColumnHider Extension. (Added at v3.16)
Event Object Properties:
<Object> stateChangeEvent The dgrid column hider event. Object contains information such as hidden indicating whether the column is visible or hidden.

data-change

Fires when grid editor field loses focus after being changed. See dgrid Events. (Added at v3.16)

editor-hide

Fires when grid editor is hidden. (Added at v3.16)

editor-show

Fires when grid editor is shown. (Added at v3.16)

edits-complete

Fires when editing is complete. (Added at v3.16)
Event Object Properties:
<FeatureEditResult[]> adds An array of result objects, one for each feature, indicating if it was successfully added. If the feature was added the result object will contain the unique object ID assigned to the feature.
<FeatureEditResult[]> deletes An array of result objects, one for each feature, indicating if it was successfully deleted. If the feature was deleted the result object will contain the unique object ID previously assigned to the feature.
<FeatureEditResult[]> updates An array of result objects, one for each feature, indicating if it was successfully updated. If the feature was updated the result object will contain the unique object ID assigned to the feature.
Sample:
myFeatureTable.on("edits-complete", function(evt){
   console.log("edits-complete event - ", evt);
});

error

Fires when an error occurs in the grid. (Added at v3.16)

filter

Fires when grid is filtered. (Added at v3.16)
Event Object Properties:
<Number[]> ids Array of filtered row ids.

load

Fires when the FeatureTable is loaded.

refresh

Fires when the grid is refreshed.

row-deselect

Fires when a row is deselected. Returns an array of the deselected rows.
Event Object Properties:
<Object> event The dgrid selection event. This event exposes properties such as grid, the grid instance in which the event occured, and rows, array containing deselected rows.

row-select

Fires when a row is selected. Returns an array of the selected rows.
Event Object Properties:
<Object> event The dgrid selection event. This event exposes properties such as grid, the grid instance in which the event occured, and rows, array containing selected rows.

show-attachments

Fires when attachment is displayed in the table. (Added at v3.18)
Event Object Properties:
<Object> attachments Object containing essential information about the attachments such as contentType, globalId, id, name, and size.
<Object> dialog A reference to the attachment dialog.
<Number> featureId Feature id.
Sample:
myFeatureTable.on("show-attachments", function(evt){
 console.log("show-attachments", evt);
}); 

show-related-records

Fires when related records are displayed in the table. (Added at v3.18)
Event Object Properties:
<Graphic[]> features The array of features, from the target layer/table related to the source feature.
<Object> relationship Object containing essential information about relationship such as cardinality, composite, id, keyfield, keyFieldInRelationshipTable, name, relatedTableId, relationshipTableId and role.
<Object> row The row object.
Sample:
myFeatureTable.on("show-related-records", function(evt){
  console.log("show-related-records", evt);
}); 

show-statistics

Fires when the statistics dialog box shows the calculated statistics on a column with numeric data. Returns an object with calculated statistics. (Added at v3.16)
Event Object Properties:
<Object> statistics An object with calculated statistics. These statistics include the number of records, the minimum and maximum value, the sum of all values, the average value, and the standard deviation of all values.
Sample:
myFeatureTable.on("show-statistics", function(evt){
   console.log("show-statistics avgfield - ", evt.statistics.avgField); 
   console.log("show-statistics countfield - ", evt.statistics.countField); 
   console.log("show-statistics maxfield - ", evt.statistics.maxField); 
   console.log("show-statistics minfield - ", evt.statistics.minField); 
   console.log("show-statistics stddevfield - ", evt.statistics.stddevField); 
   console.log("show-statistics sumfield - ", evt.statistics.sumField)
});  

sort

Fires when a column is sorted. See Grid Events. (Added at v3.16)
Event Object Properties:
<Object> sortEvent Object containing a sort information. It has the following properties:
field: The field name that was sorted
descending: indicates whether the field was sorted in ascending or descending order
Show Modal