Edit using toolkit

The FeatureFormView in the ArcGIS Maps SDK for .NET Toolkit provides a ready-to-use form for editing attributes and attachments of one feature at a time. The toolkit component provides the following functionality:

• Displays the feature form UI in your app.
• Handles interactions between the user and the feature form.
• Displays validation errors below field form elements that are visible in the form.
• Evaluates Arcade expressions defined in the expressionInfos array in the feature form definition. The expressions provide values for properties in the formElements array.

Since the toolkit is open source, the component can be extended to meet any special UI requirements your app might have.

A typical feature form view from the toolkit looks something like the following.

Using the toolkit component allows you to focus on intuitive editing workflows for your user, rather than the low-level details of creating an editing UI, handling user interaction, and validating input. Implementing an editing workflow using feature forms may follow a pattern like this:

1. Create the feature form UI.
2. Display a feature's attributes for editing.
3. Process form errors before submitting edits.
4. Save or discard edits.
5. Persist edits.

Create a feature form UI

In the xaml file for your app UI, import the ArcGIS Maps SDK for .NET toolkit. After creating a map view or scene view, create a FeatureFormView using the ArcGIS Maps SDK for .NET toolkit.

1
<toolkit:FeatureFormView x:Name="FeatureFormViewPanel" />

Create buttons that allow your users to save or discard the edits they've made in the feature form.

1
2
<Button Content="Discard" Click="DiscardButton_Click" />
<Button Content="Save" Click="SaveButton_Click" IsEnabled="{Binding IsValid, ElementName=featureFormView}" />

Display a feature's attributes for editing

Exposing a feature's attributes for editing consists of two steps. First you create an instance of the FeatureForm class defined in the ArcGIS Maps SDK for .NET API. Then you set the FeatureForm property on the FeatureFormView from the ArcGIS Maps SDK for .NET toolkit

1
2
3
var featureForm = new FeatureForm(feature)

FeatureFormView.FeatureForm = featureForm

For ways to obtain a feature, see the Create a feature form instance section on the Overview page.

Process form errors before submitting edits

When users are ready to submit their feature form edits, your app logic can check for validation errors. If there are no such errors, the edits can be saved to the local geodatabase. If there are errors, your app can display the errors (for example, in a dialog) and require the user to fix them all. Alternatively, you can determine which errors must be fixed before saving and which can be temporarily ignored. This approach enables more flexible workflows, such as those that consist of two or more stages. For example, new features with default values could be edited in the first stage, automatically providing values for most fields but leaving other fields empty because the values are not yet available. The logic of processing validation errors is up to the needs of your users and the design goals of your app.

You retrieve errors for a feature form by calling FeatureForm.ValidationErrors. An error results from one or more violations of the constraints of a field form element as expressed by element's input type and the FieldFormElement.IsRequired property. Validation errors are returned as a dictionary mapping from the field form element's field name (the key) to an array of errors (the value). An empty dictionary implies that that all form element values are valid. Note that errors are returned for all field form elements that are both visible and editable. The form author defines a form field element as visible using the visibilityExpression property and editable using the editable property in the feature form definition.

The array of errors for a field form element contains one or more of the following FeatureFormValidationErrorTypes:

• FeatureFormNullNotAllowedException - The field is not nullable and cannot be set to null.
• FeatureFormIncorrectValueTypeException - The type of the value does not match the type of the field.
• FeatureFormExceedsMaximumDateTimeException - The value for a field of type esriFieldTypeDate exceeds the allowed maximum value of DateTime.
• FeatureFormLessThanMinimumDateTimeException - The value for a field of type esriFieldTypeDate is less than the allowed minimum value of DateTime.
• FeatureFormExceedsMaximumLengthException - This value exceeds the maximum allowed length.
• FeatureFormLessThanMinimumLengthException - The value is less than the minimum allowed length.
• FeatureFormExceedsNumericMaximumException - The value exceeds the allowed numeric maximum.
• FeatureFormLessThanNumericMinimumException - The value is less than the allowed numeric minimum.
• FeatureFormNotInCodedValueDomainException - The value is not present in the coded value domain.
• FeatureFormFieldIsRequiredException - The value is required and the value is null or empty.

Process all validation errors

The FeatureForm.ValidationErrors property returns errors for field form elements that are editable and currently visible on the form. In some cases, however, you may want to retrieve all errors, even those for elements that are currently hidden. To do so, you can access the validation errors for individual feature form elements:

Start by accessing FeatureForm.Elements to get a collection of all the form elements in the feature form. Then iterate over the collection, filtering for FieldFormElement. For each field form element, call FieldFormElement.ValidationErrors, which will evaluate the element's Arcade expressions and any other relevant expressions and validate the field's value.

Save or discard edits

When a user is finished making edits in the form, you can allow them to either save their edits to the local geodatabase or discard them.

If the user chooses to save edits:

1. Retrieve the error validations for the feature form, or for each field form element.

2. If there are no errors or the current validation errors are acceptable, call FeatureForm.FinishEditingAsync(). This will save the edits to the local geodatabase.

3. Optionally, (perhaps when all feature editing is complete), persist the local edits to the feature service.

If the user decides that the edits in the form should not be saved to the local geodatabase, you can discard them:

1. Call FeatureForm.DiscardEdits().
2. Notify the user that edits have been discarded.

Persist edits

When feature form edits are saved to the local geodatabase, they are preserved on the user's device. These edits are not stored with the associated feature service until they are explicitly persisted.

To persist all edits from your service geodatabase to its associated service feature.

1. Get the ServiceFeatureTable from the Feature that was edited.
2. Get the ServiceGeodatabase from the table.
3. Get the service info with ServiceGeodatabase_serviceInfo and then use ArcGISFeatureServiceInfo.CanUseServiceGeodatabaseApplyEdits to check that you can commit edits back to the feature service.
4. Call ServiceGeodatabase.ApplyEditsAsync() to commit the edits.

For more information, see the Persist edits topic in the Basic editing workflow section of this guide.

As part of your app design, you can decide when and how users save edits in the local database and ultimately persist them with the feature service. For example, your app could persist edits to the service each time an edit is made and saved locally, or you could wait until the user has completed all local edits (or a set of them) before persisting them to the service. Likewise, you can either let the user decide when edits are persisted (with a UI control, for example) or you can persist edits for them automatically.