import FeatureFormViewModel from "@arcgis/core/widgets/FeatureForm/FeatureFormViewModel.js";const FeatureFormViewModel = await $arcgis.import("@arcgis/core/widgets/FeatureForm/FeatureFormViewModel.js");- Inheritance:
- FeatureFormViewModel→
Accessor
- Since
- ArcGIS Maps SDK for JavaScript 4.9
Provides the logic for the FeatureForm widget.
Known Limitations
This widget is not yet at full parity with the functionality provided in the 3.x AttributeInspector widget. There is currently no support for editing attachments or related records solely within this widget, although it is possible to edit attachments and relationship data via the Editor widget. Please refer to the Editor documentation for any known limitations regarding this.
Example
let featureForm = new FeatureForm({ viewModel: { // Autocasts as new FeatureFormViewModel() map: map, // Required if using Arcade expressions that use the global $map variable layer: featureLayer // Associates the FeatureForm to the layer }, container: "formDiv"});Constructors
Constructor
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| properties | | |
Properties
| Property | Type | Class |
|---|---|---|
Association | null | undefined | | |
activeAssociationInput readonly | | |
declaredClass readonly inherited | ||
| | ||
| | ||
| | ||
inputs readonly | | |
| | ||
| | ||
state readonly | | |
submittable readonly | | |
| | ||
updating readonly | | |
valid readonly | |
activeAssociation
- Type
- Association | null | undefined
The [Association]Association that the selected feature is involved in. The association is provided by the activeAssociationInput of the previous Editor workflow.
This property is null until the user has drilled into an associated feature in the Editor widget.
activeAssociationInput
- Type
- UtilityNetworkAssociationInput | null | undefined
The [UtilityNetworkAssociationInput]UtilityNetworkAssociationInput providing association data for the active workflow and selected association type in the Editor widget.
This property is null until an association type is selected in the Editor widget.
editType
- Type
- EditType
- Since
- ArcGIS Maps SDK for JavaScript 4.33
The edit type for the form, which determines the editing context and behavior.
This property is used in two primary ways:
-
Arcade Expressions Context: When evaluating Arcade expressions, the value of this property is assigned to the
$editContext.editTypevariable. This allows Arcade expressions to adapt their behavior based on the type of edit being performed (e.g., "INSERT", "UPDATE", "DELETE", or "NA"). -
Layer Editing Capabilities: This property is also used to determine whether the layer allows the specified type of edit. For example:
- If
editTypeis set to"INSERT"but the layer hassupportsAdd: false, all inputs in the form will be read-only. - If
editTypeis set to"UPDATE"but the layer hassupportsUpdate: false, all inputs will also be read-only.
- If
This behavior applies regardless of whether a form template or Arcade expressions are present. For instance:
- If a layer has
{ supportsAdd: true, supportsUpdate: false }and no form template, settingeditTypeto"INSERT"will allow the user to modify all fields, while setting it to"UPDATE"will make all fields read-only. - If a form template is present with field elements that include
editableExpressionorvalueExpression, theeditTypestill determines whether the layer permits editing in the given context.
- Default value
- "NA"
feature
The associated feature containing the editable attributes.
A common way to access this is via the MapView.hitTest()
or SceneView's hitTest()
method.
Example
// Check if a user clicked on an incident feature.view.on("click", function(event) { view.hitTest(event).then(function(response) { // Display the attributes of selected incident feature in the form if (response.results[0].graphic && response.results[0].graphic.layer.id == "incidentsLayer") { formVM.feature = result.results[0].graphic } });}); formTemplate
- Type
- FormTemplate | null | undefined
- Since
- ArcGIS Maps SDK for JavaScript 4.16
The associated template used for the form.
The FormTemplate is where you configure how the form should display and set any associated properties for the form, e.g. title, description, field elements, etc.
inputs
- Since
- ArcGIS Maps SDK for JavaScript 4.27
The field, group, or relationship inputs that make up the form FeatureForm widget.
layer
- Type
- FeatureFormLayerUnion | null | undefined
Layer containing the editable feature attributes. If this layer is not specified, it is the same as the graphic's layer.
map
- Since
- ArcGIS Maps SDK for JavaScript 4.27
A reference to the associated Map.
This property is required if working with Arcade expressions in the FeatureForm that make use of the $map global variable.
submittable
- Type
- boolean
Indicates if the field's value can be submitted without introducing data validation issues.
timeZone
- Type
- TimeZone
- Since
- ArcGIS Maps SDK for JavaScript 4.28
The timezone displayed within the form. If unknown, it will display the FeatureLayer.preferredTimeZone of the layer. If this layer property is not set, it will default to UTC.
updating
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 4.27
Indicates whether the form is currently updating.
Methods
| Method | Signature | Class |
|---|---|---|
emit inherited | emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean | |
findField(fieldName: string | null | undefined): FieldInput | null | undefined | | |
getValues(): Attributes | | |
hasEventListener inherited | hasEventListener<Type extends EventNames<this>>(type: Type): boolean | |
isFulfilled inherited | isFulfilled(): boolean | |
isRejected inherited | isRejected(): boolean | |
isResolved inherited | isResolved(): boolean | |
on inherited | on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle | |
setValue(fieldName: string, value: FieldValue): void | | |
submit(): void | | |
validateContingencyConstraints(values: Attributes, options?: FeatureFormViewModelValidateContingencyConstraintsOptions): object[] | | |
when inherited | when<TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2> |
emit
- Signature
-
emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
- Type parameters
- <Type extends EventNames<this>>
Emits an event on the instance. This method should only be used when creating subclasses of this class.
getValues
- Signature
-
getValues (): Attributes
Returns all of the field values, regardless of whether or not they were updated.
- Returns
- Attributes
An object of key-value pairs of field names with their values.
Example
function updateFeature() { // Get the updated field values const attributes = formVM.getValues(); // Call applyEdits on the feature layer layer.applyEdits({ // Pass in the updated field values updateFeatures: [{ attributes }] });} hasEventListener
- Signature
-
hasEventListener <Type extends EventNames<this>>(type: Type): boolean
- Type parameters
- <Type extends EventNames<this>>
Indicates whether there is an event listener on the instance that matches the provided event name.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | The name of the event. | |
- Returns
- boolean
Returns true if the class supports the input event.
isFulfilled
- Signature
-
isFulfilled (): boolean
isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected).
If it is fulfilled, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been fulfilled (either resolved or rejected).
isRejected
- Signature
-
isRejected (): boolean
isRejected() may be used to verify if creating an instance of the class is rejected.
If it is rejected, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been rejected.
isResolved
- Signature
-
isResolved (): boolean
isResolved() may be used to verify if creating an instance of the class is resolved.
If it is resolved, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been resolved.
on
- Signature
-
on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
- Type parameters
- <Type extends EventNames<this>>
Registers an event handler on the instance. Call this method to hook an event with a listener.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | An event or an array of events to listen for. | |
| listener | EventedCallback<this["@eventTypes"][Type]> | The function to call when the event fires. | |
- Returns
- ResourceHandle
Returns an event handler with a
remove()method that should be called to stop listening for the event(s).Property Type Description remove Function When called, removes the listener from the event.
Example
view.on("click", function(event){ // event is the event handle returned after the event fires. console.log(event.mapPoint);}); setValue
- Signature
-
setValue (fieldName: string, value: FieldValue): void
- Since
- ArcGIS Maps SDK for JavaScript 4.21
The method used to set the updated field value.
This renders the new value within the form but does not update the underlying input feature's attributes.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| fieldName | The target field to update. | | |
| value | The value to set on the target field. | |
- Returns
- void
submit
- Signature
-
submit (): void
Fires the @submit event.
- Returns
- void
Example
// Listen for when 'submit' is called.// Once it is fired, update the feature.formVM.on("submit", updateFeature);
// When the DOM's button (btnUpdate) is clicked,// Update attributes of the selected feature.document.getElementById("btnUpdate").onclick = function() { // Fires feature form's submit event. formVM.submit();} validateContingencyConstraints
- Signature
-
validateContingencyConstraints (values: Attributes, options?: FeatureFormViewModelValidateContingencyConstraintsOptions): object[]
- Since
- ArcGIS Maps SDK for JavaScript 4.23
Validates whether a feature's attribute values conform to the defined contingent values.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| values | A hash map of the form fields and their values. | | |
| options | An object specifying additional options on what should be considered an error. | |
- Returns
- object[]
An array of objects, each representing a violation of a field group's contingent value rules.
Example
// Validate a features attribute values against the layer's contingent valuesfeatureForm.on("value-change", () => { const validations = featureForm.viewModel.validateContingencyConstraints(featureForm.getValues()); !!validations.length ? console.log("found some validation errors: ", validations) : console.log("no errors found!");}); when
- Signature
-
when <TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2>
when() may be leveraged once an instance of the class is created. This method takes two input parameters: an onFulfilled function and an onRejected function.
The onFulfilled executes when the instance of the class loads. The
onRejected executes if the instance of the class fails to load.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| onFulfilled | OnFulfilledCallback<this, TResult1> | null | undefined | The function to call when the promise resolves. | |
| onRejected | The function to execute when the promise fails. | |
- Returns
- Promise<TResult1 | TResult2>
Returns a new promise for the result of
onFulfilledthat may be used to chain additional functions.
Example
// Although this example uses MapView, any class instance that is a promise may use when() in the same waylet view = new MapView();view.when(function(){ // This function will execute once the promise is resolved}, function(error){ // This function will execute if the promise is rejected due to an error});Events
submit
submit: CustomEvent<SubmitEvent> Fires when the FeatureForm.submit() method is called. Call FeatureLayer.applyEdits() method to update a feature's attributes.
Example
// Listen to the feature form's submit event.featureForm.on("submit", function(){ if (editFeature) { // Grab updated attributes from the form. const updated = featureForm.getValues();
// Loop through updated attributes and assign // the updated values to feature attributes. Object.keys(updated).forEach(function(name) { editFeature.attributes[name] = updated[name]; });
// Setup the applyEdits parameter with updates. const edits = { updateFeatures: [editFeature] }; applyEdits(edits); }}); value-change
value-change: CustomEvent<ValueChangeEvent> Fires when a field value is updated.
Type definitions
SubmitEvent
values
- Type
- Attributes
An object of key-value pairs of field names with all of their values, regardless of whether or not they were updated.
FeatureFormViewModelValidateContingencyConstraintsOptions
includeIncompleteViolations
- Type
- boolean
If true, return contingency violations for field groups that are invalid because values have not yet been specified for all their fields. If false, any of these violations are ignored.