import BatchAttributeFormViewModel from "@arcgis/core/widgets/BatchAttributeForm/BatchAttributeFormViewModel.js";const BatchAttributeFormViewModel = await $arcgis.import("@arcgis/core/widgets/BatchAttributeForm/BatchAttributeFormViewModel.js");- Inheritance:
- BatchAttributeFormViewModel→
Accessor
- Since
- ArcGIS Maps SDK for JavaScript 4.33
Provides the logic for the BatchAttributeForm widget.
Known Limitations
Currently, relationship elements and associations elements are not supported within the BatchAttributeForm widget. Users can individually edit related records and association fields using the FeatureForm widget.
- See also
Example
let batchAttributeForm = new BatchAttributeForm({ viewModel: { // Autocasts as new BatchAttributeFormViewModel() map: map, // Required if using Arcade expressions that use the global $map variable features: featureCollection, }, container: "formDiv"});Constructors
Constructor
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| properties | | |
Properties
| Property | Type | Class |
|---|---|---|
activeFeature readonly | | |
| | ||
activeForm readonly | | |
calculating readonly | | |
declaredClass readonly inherited | ||
| | ||
| | ||
expressionEvaluationFailed readonly | | |
| | ||
hasTooManyComplexFeatures readonly | | |
hasTooManyFeatures readonly | | |
hasVisibleInputs readonly | | |
invalidFeatures readonly | Graphic[] | |
| | ||
layers readonly | | |
| | ||
mode readonly | | |
| | ||
sharedForm readonly | | |
status readonly | | |
| | ||
| | ||
updating readonly | | |
| | ||
valid readonly | | |
visibleInputs readonly | |
activeFeatureIndex
- Type
- number
The index of the active feature that is currently being edited. This will be -1 when mode is batch.
To enter single mode, set this property to the index in the features array of the feature you wish to edit individually. To enter batch mode, set this property to -1.
- Default value
- -1
activeForm
- Type
- BatchFormInputs
Returns the batch attribute form inputs that are currently being edited. This is
dependent on the form's mode. If the mode is
batch, it returns the shared form inputs. If single, it
returns the form inputs for the active feature.
This property is read-only and should not be modified directly.
To change which form is active, see activeFeatureIndex.
calculating
- Type
- boolean
Indicates whether the form is currently evaluating Arcade expressions. It returns true when the form is evaluating expressions or when it is waiting for a response from the server.
disabled
- Type
- boolean
Indicates whether the associated view should be in read-only mode.
When true, the associated view should display the form in a read-only
mode, disabling any editing.
- Default value
- false
editType
- Type
- EditType
Specifies the type of edit operation being performed by the form (for example, add, update, or delete).
This property can affect whether certain fields are editable, depending on the layer's capabilities.
Its value is also used for the $editcontext.editType variable in Arcade expressions.
The value "NA" is always permitted when checking if a layer supports the current edit type.
- Default value
- "NA"
expressionEvaluationFailed
- Type
- boolean
Indicates whether any of the Arcade expressions in the form have failed to evaluate.
- See also
features
- Type
- Collection<Graphic>
The set of features whose attributes are being edited by the form. This collection is intended to be immutable: do not add, remove, or reorder features in place, as this may cause unexpected behavior. To update the features, assign a new collection to this property. Doing so will regenerate the form inputs and discard any unsaved changes.
hasTooManyComplexFeatures
- Type
- boolean
Indicates whether the form cannot load because there are too many features whose forms have complex Arcade expressions. These are expressions that that involve advanced logic, calculations, or asynchronous operations, such as accessing data from other layers, performing network requests, or using functions that require waiting for a response. These expressions go beyond simple field value lookups or basic calculations.
hasTooManyFeatures
- Type
- boolean
Indicates whether the form has too many features to be loaded.
hasVisibleInputs
- Type
- boolean
Indicates whether there are any visible inputs in the form.
This is true if there are any inputs that are visible to the user, meaning they are not hidden by a visibility expression or group visibility expression.
invalidFeatures
- Type
- Graphic[]
Returns an array of features that are invalid, meaning they have at least one invalid attribute value.
layerInfos
- Type
- AttributeFormSupportedLayerInfo[] | null | undefined
An array of objects containing a FormTemplate and its corresponding layer.
This allows per-layer overrides which provides a FormTemplate for building batch form templates. The formTemplate defined here overrides any formTemplate defined on the layer itself. Otherwise, the layer's own formTemplate is used if it exists.
Example
// Query for featuresconst { features } = await featureLayer.queryFeatures();
// Initialize BatchAttributeFormViewModelconst batchAttributeFormViewModel = new BatchAttributeFormViewModel({ features: features, layerInfos: [{ layer: featureLayer, formTemplate: { // autocasts to FormTemplate elements: [ { // autocasts to FieldElement type: "field", fieldName: "fulladdr", label: "Full Address" } ] }, }]}); layers
An array of layers included in the batch attribute form. Each layer must support feature editing and field access.
The following layer types are supported:
- FeatureLayer
- GeoJSONLayer
- SceneLayer (with
featureLayerproperty) - SubtypeSublayer
- OrientedImageryLayer
- KnowledgeGraphSublayer
map
A reference to the associated Map.
This property is required if working with Arcade expressions in the BatchAttributeForm that make use of the $map global variable.
mode
The mode of the form, which can be either "single" or "batch".
In "single" mode, the form is editing a single feature at a time, while in
"batch" mode, it is editing all of the features in the features collection. To change the mode, set the activeFeatureIndex property.
sharedForm
- Type
- BatchFormInputs
The set of form inputs used in batch editing mode.
status
Indicates whether the view model is ready to be used. Upon construction,
and then again any time the features Collection is modified or
re-assigned, the view model must perform certain asynchronous tasks in
order to compile the shared attribute form. Use the status property to
determine when this processing occurs.
| Value | Description |
|---|---|
| not-loaded | The features property has not been initialized or is an empty Collection. |
| loading | The features property has been set or modified, and the view model is compiling the shared form. Certain properties, like activeForm, should not be accessed yet. |
| loaded | The view model is ready to use. |
| failed | An error occurred while compiling the shared form. |
submitHasBeenAttempted
- Type
- boolean
Indicates whether the user has attempted to submit the form.
- Default value
- false
timeZone
The time zone used to interpret date values in the form. If this property is null or set to "unknown", date values are displayed in the time zone specified by the layer's FeatureLayer.preferredTimeZone. If none is provided there, date values are interpreted in UTC.
updating
- Type
- boolean
Indicates whether the form is updating or calculating expressions.
- See also
userHasChangedValues
- Type
- boolean
Indicates whether any values, for any features, have been modified by the user. This property does not take into account changes to attribute values that resulted from calculated value expressions.
- Default value
- false
valid
- Type
- boolean
Returns true if all fields for all features in the form are valid, with no validation errors present.
visibleInputs
- Type
- FormInput[]
An array of inputs in the active form that are currently visible to the user. This array includes only those inputs that are not hidden by visibility settings or expressions.
Methods
| Method | Signature | Class |
|---|---|---|
emit inherited | emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean | |
findFieldInput(elementId: string | null | undefined): FieldInput | null | undefined | | |
getFieldInputValue(elementId: string): FieldValue | undefined | | |
getValues(feature: Graphic): Graphic["attributes"] | | |
hasEventListener inherited | hasEventListener<Type extends EventNames<this>>(type: Type): boolean | |
on inherited | on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle | |
submit(): void | | |
userChangesHaveMadeFeatureInvalid(feature: Graphic): boolean | |
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.
getFieldInputValue
- Signature
-
getFieldInputValue (elementId: string): FieldValue | undefined
Gets the updated value for the specified field in the active form.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| elementId | The id of the target field where the value is accessed. | |
- Returns
- FieldValue | undefined
Returns the associated field value, or
undefinedif there is no matching attribute.
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.
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);}); submit
- Signature
-
submit (): void
This method triggers the "submit" event, and causes submitHasBeenAttempted to become true. It does not do anything to persist the updated values. It is up to the client to verify if these values are appropriate. For example, calling FeatureLayer.applyEdits() method to update the features' attributes.
- Returns
- void
Example
// Listen for when 'submit' is called on the form.// Once it is fired, update the feature.form.on("submit", updateFeatures);// When the DOM's button (btnUpdate) is clicked,// execute the 'submit()' method.document.getElementById("btnUpdate").addEventListener("click", () => form.submit()); userChangesHaveMadeFeatureInvalid
- Signature
-
userChangesHaveMadeFeatureInvalid (feature: Graphic): boolean
Determines if user input has caused the given feature to become invalid. Only returns true if all of the following three conditions are true of the given feature:
- It had no validation errors at the start of the editing session.
- It currently has validation errors.
- At least one of the validation errors was caused by user input, as opposed to a value expression.
Events
submit
submit: CustomEvent<SubmitEvent> Fires when the BatchAttributeForm.submit() method is called.
value-change
value-change: CustomEvent<ValueChangeEvent> Fires when field values are updated.
Example
form.on("value-change", (event) => { const result = {}; for (const feature of form.features) { const value = form.viewModel.getValues(feature)[event.fieldName]; result[feature.getObjectId()] = typeof value === "number" ? new Date(value).toISOString() : value; } console.log(`Values for field ${event.fieldName}`, result);});