Edit using toolkit

The FeatureFormView in the ArcGIS Maps SDK for Swift 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 an instance of the FeatureForm from the ArcGIS Maps SDK for Swift API.
2. Create the FeatureFormView from the ArcGIS Maps SDK for Swift toolkit.
3. Process errors before submitting edits.
4. Save or discard edits.
5. Persist edits.

Create a FeatureForm instance

Before using the toolkit component, you must create an instance of the FeatureForm class, passing in the feature to be edited. The FeatureForm class is defined in the ArcGIS Maps SDK for Swift API.

You can now create an instance of FeatureForm by passing in the feature.

1
2
 // Uses the feature identified by the user to construct a new feature form.
 let featureForm = FeatureForm(feature: feature)

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

Create a feature form view from the toolkit

You display a feature form view in your app by initializing a FeatureFormView, passing in the FeatureForm instance you just created. Then you set the visibility of errors in the feature form. See Visibility of validation errors on the form

1
2
let featureFormView = FeatureFormView(featureForm: featureForm)
    .validationErrors(_ visibility: ValidationErrorVisibility.automatic)

Visibility of validation errors on the form

The toolkit's feature form has built-in functionality to display input errors directly on the form. Each error displays adjacent to the element and describes which constraint has been violated. For example, if the user inputs a string that exceeds the maximum length as defined by the form definition author, a validation error such as the following is displayed:

The validation errors on the form can be displayed in one of two ways:

• Interactively - Upon initial display of the feature form, no errors are visible. An error for a field form element can display only when the user brings focus to the element. If the element was saved with an error (for example, a required field was left empty), then tapping on the element will immediately display the error. Otherwise, an error displays after the user enters a value that violates constraints.

• All at once - Upon initial display of the feature form, all errors are visible.

You customize the visibility of errors on the form by using the Toolkit_FeatureFormView_validationErrors method. Pass in one of the following Toolkit_ValidationErrorVisibility enumeration cases: Automatic or Visible. Automatic displays validation errors interactively; this is the default. Visible displays all validation errors at once.

Save and discard buttons

When you add the toolkit's FeatureFormView, you will generally want to create at least two buttons: Discard and Save. For example, you can create icon buttons directly above the feature form.

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 cases declared in the FeatureFormError enumeration:

• exceedsMaximumDateTime - Field value exceeds the value of max.
• exceedsMaximumLength - Field value exceeds the maximum allowed length.
• exceedsNumericMaximum - Field value exceeds the allowed numeric maximum.
• fieldIsRequired - Field value is required.
• incorrectValueType - The type of the value does not match the type of the field.
• lessThanMinimumDateTime - Field value is less than the value of min.
• lessThanMinimumLength - Field value is less than the minimum allowed length.
• lessThanNumericMinimum - Field value is less than the allowed numeric minimum.
• notInCodedValueDomain - Field value is not present in the coded value domain.
• nullNotAllowed - Field value cannot be nil.

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.finishEditing(). 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.applyEdits() 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.