require(["esri/dijit/FeatureTable"], function(FeatureTable) { /* code goes here */ });
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
CSS
esri/dijit/FeatureTable | Download source
Properties
Methods
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.
Old Events
onload() | Fires when the FeatureTable is loaded. |
Constructor Details
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
The number of features a service will try to fetch. (Added at v3.17)
Default value: 50
Read-only: A reference to the column objects and their parameters.
Read-only: Reference to the dataStore used by the
dGrid.
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. |
Sample:
dateOptions: {
timePattern: "h:mm:ss a",
timeEnabled: true,
datePattern: "MMMM d, y"
}
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"
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
Read-only: Number of records displayed in FeatureTable.
The featureLayer that the table is associated with.
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. |
<Object > stringOptions |
Optional |
Simple object containing one string property, input . The input property accepts one value, textarea . If input is set to textarea the FeatureTable will display a SimpleTextarea instead of a ValidationTextBox . |
<Boolean > visible |
Optional |
Hide or display the field in the FeatureTable. |
Sample:
fieldInfos: [
{
name: "Address",
stringOptions:
{
input: "textarea"
}
},
{
name: "moreInfo",
alias: "More Information",
editable: false,
visible: false,
format:{
embeddedHTML: true
}
},
{
name: "startDate",
alias: "Start Date",
editable: true,
visible: false,
dateOptions: {
datePattern: 'M/d/y',
timeEnabled: true,
timePattern: 'H:mm',
}
},
{
name: 'pocphone',
alias: 'Phone #',
format: {
template: "tel: ${value}"
}
},
{
name: 'usd',
alias: 'Currency',
format: {
template: "${value} USD",
places: 2
}
}
]
Reference to the
dGrid.
Deprecated at v3.17
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 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
}
|
Sample:
var gridOptions = {
noDataMessage: "No Data",
allowSelectAll: false,
cellNavigation: false,
selectionMode: "extended",
pagination: false,
allowTextSelection: true,
pageSizeOptions: [10, 25, 50],
columnHider: true,
columnResizer: true,
pagingDelay: 300,
sort: {
field: "StateName", descending: true}
},
Optional columns to hide by default using the
dGrid ColumnHider extension.
Read-only: A reference to the primary key used by the dataStore
to differentiate columns.
When true, the FeatureTable widget has successfully loaded.
Known values: true | false
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. |
Sample:
//add custom menu items to 'Options' drop-down menu
menuFunctions: [
{
label: "Zoom To Selected Feature(s)",
callback: function(evt){
console.log(" -- evt: ", evt);
}
},
{ label: "Custom Refresh",
callback: customRefreshFunction
}
]
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.
Read-only: A comma delimited array of ObjectIds for the features selected in the FeatureTable. (Added at v3.16)
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)
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
Displays or hides tooltips for column headers. (Added at v3.18)
Default value: false
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
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
Displays or hides total number of features and selected number of features in the grid header. (Added at v3.17)
Default value: true
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
Displays or hides 'Options' drop-down menu of the FeatureTable. (Added at v3.15)
Default value: true
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
Displays or hides the 'Statistics' option in column menus for numeric fields. (Added at v3.17)
Default value: true
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
Enables pans to selected features on the map when the table in 'sync selection' mode. (Added at v3.16)
Default value: false
Method Details
Centers the map on combined extent of selected rows. (Added at v3.18)
Sample:
myFeatureTable.selectRows([37, 38, 39], true); myFeatureTable.centerOnSelection();
Removes all filters and selections in the table. (Added at v3.18)
Removes all selections. (Added at v3.17)
Sample:
myFeatureTable.clearSelection();
Destroys the FeatureTable widget. Call destroy() when the widget is no longer needed by the application.
Sample:
myFeatureTable = new FeatureTable({
featureLayer : myFeatureLayer,
map : map
}, 'myTableNode');
myFeatureTable.startup();
// widget no longer needed
myFeatureTable.destroy();
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. |
Sample:
myFeatureTable.filterRecordsByIds([37, 38, 39]);
Allows users to see the sub-set of records. Only filtered rows will be displayed in the table. (Added at v3.17)
Sample:
myFeatureTable.filterSelectedRecords();
Queries and gets selected features from the FeatureLayer instead of the store. (Added at v3.17)
Sample:
myFeatureTable.getFeatureDataById(myFeatureTable.selectedRowIds).then(function(features){
console.log("features", features);
});
Gets row object by the row ID. (Added at v3.17)
Sample:
var rowData = myFeatureTable.getRowDataById(myFeatureTable.selectedRowIds[0]);
console.log("row data", rowData);
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) Sample:
myFeatureTable.refresh();
Resizes the grid's container. (Added at v3.17)
Sample:
myFeatureTable.grid.resize();
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. |
Sample:
myFeatureTable.selectRows([37, 38, 39], true);
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 |
Sample:
// State_Name field will be sorted
// in descending order.
myFeatureTable.sort("State_Name", true);
Finalizes the creation of the widget.
Event Details
[ On Style Events | Connect Style Event ]
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.
|
Fires when a column is hidden or shown via 'Options' drop-down menu. See
ColumnHider Extension.
(Added at v3.16)
Fires when grid editor field loses focus after being changed. See
dgrid Events.
(Added at v3.16)
Fires when grid editor is hidden. (Added at v3.16)
Fires when grid editor is shown. (Added at v3.16)
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);
});
Fires when an error occurs in the grid. (Added at v3.16)
Fires when grid is filtered. (Added at v3.16)
Event Object Properties:
<Number[] > ids |
Array of filtered row ids. |
Fires when the FeatureTable is loaded.
Fires when the grid is refreshed.
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. |
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. |
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);
});
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);
});
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)
});
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 |
Fires when the FeatureTable is loaded.