`FeatureForm` : support for UtilityAssociations #776

kaushikrw · 2025-03-10T22:12:23Z

Related to issue: #kotlin/5456

Description:

Adds UtilityAssociations support for FeatureForm.

UtilityAssociations UI structure

A new UtilityAssociationsFormElement is displayed if it is part of the form info.
- First step is to call element.fetchAssociationsFilterResults which fetches the list of associations organized within a specific structure represented by the UtilityAssociationsFilterResult class.
- Once fetched, this element will display the list of UtilityAssociationsFilters.
- Each filter will have a list of UtilityAssociations that are grouped by layer, sublayer, table or subtable. This is represented by the UtilityAssociationGroupResult class.
- Finally, once you click on a group, this will display the actual UtilityAssociations present in the UtilityAssociationGroupResult.

Navigation Support

The component allows you to navigate to the FeatureForm of an ArcGISFeature on the other end of the UtilityAssociation. This is achieved by adding a navigation graph within the component.
Since with compose navigation only Serializable or Parcelable objects can be saved, for example during configuration changes, this means the FeatureForm api object cannot be used here and has to hoisted out of the navigation graph.
Hence, a Stack data structure is created out of the composition that will track all the FeatureForms visited. This stack will closely track the current navigation stack and provide the source of truth for the navigation destinations.

API Changes

Since the Stack has to be out of the composition, this means providing a State holder class for the FeatureForm composable. This state holder can then be hoisted up, like in a ViewModel. Hence the proposed API changes -

A new FeatureFormState class which internally creates and holds on to this Stack of FeatureForm api objects.
Provides an observable activeFeatureForm property that will always point to the current FeatureForm instance being edited.
Deprecate the older FeatureForm composable in favor of the new one.
- Internally, the deprecated FeatureForm composable utilizes the FeatureFormState.
- This composable will also not display any UtilityAssociationsFormElements and will function and look exactly like it used to.
Deprecated the ValidationErrorVisibility class as the updated workflow specifies to show all errors when the form is opened. This setting will possibly be part of the web map spec in a future release.
FeatureForm composable provides an optional onDimiss callback. If this is provided, a "close" icon is displayed which when clicked raises this event.
FeatureForm composable provides a boolean showFormActions. If this is true (default), A "Discard" and "Save" buttons within an action bar is displayed when there are edits in the form.
A new FeatureFormEditingEvent is introduced which is raised when the user "Saves" or "Discards" edits on the Form. (see ui changes below).

UI Changes

FeatureForm.hasEdits property is used to show an action bar on top of the form if showFormActions is true which enables two options -
- "Save" - saves the edits using FeatureForm.finishEditing() and raises the FeatureFormEditingEvent.SavedEdits if only the result of the operation is successful.
- "Discard" - discards any edits using FeatureForm.discarEdits() and raises the FeatureFormEditingEvent.DiscardedEdits.
"Close" - if the corresponding onDimiss callback is provided, a close icon is shown. If there are active edits on the form as indicated by FeatureForm.hasEdits, a dialog is presented to save or discard edits. These actions will have the same behavior as above.
When attempting to navigate to another Feature, the same workflow applies. If there are edits, a dialog is presented to save/discard.
If the user attempts to save and there are validation errors as indicated by FeatureForm.validationErrors, a dialog is presented with this information.

These changes should satisfy the workflows mentioned in the issue here.

Internal Changes

Since any internal states that are created for other FormElements are now stored in the FeatureFormState class, this means we no longer need any rememberSaveable methods on these elements.

Test Changes

Updated the tests that used any of the removed APIs.

Test Data

I've added some test data in the linked issue.

Notes

Tests for UN elements will be added in a separate PR. I will also update the deprecated constructor for the other tests here.
Readme and doc will be updated in a separate PR.

Pre-merge Checklist

a vTest Job for this PR has been run
- link: https://runtime-kotlin.esri.com/job/vtest/job/toolkit/526/
Unit and/or integration tests have been added to exercise this PR's logic, and the tests are passing:
- Yes
- No

kaushikrw · 2025-03-14T18:07:49Z

toolkit/featureforms/build.gradle.kts

@@ -23,6 +23,7 @@ plugins {
    id("artifact-deploy")
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    alias(libs.plugins.binary.compatibility.validator) apply true
+    alias(libs.plugins.kotlin.serialization) apply true


Serialization plugin is needed for compose navigation. Specifically, for the route classes used.

kaushikrw · 2025-03-14T18:08:15Z

.../featureforms/src/androidTest/java/com/arcgismaps/toolkit/featureforms/DateTimeFieldTests.kt

@@ -99,7 +98,7 @@ class DateTimeFieldTests : FeatureFormTestRunner(
        }
        dateTimeField.assertIsDisplayed()
        val helper = dateTimeField.onChildWithContentDescription("supporting text")
-        val helperMatcher = hasText("Date Entry is Required")
+        val helperMatcher = hasText("Required")


Updated the correct text to check for.

kaushikrw · 2025-03-14T18:50:11Z

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureFormState.kt

+        evaluateExpressions()
+    }
+
+    internal constructor(


This constructor is to primarily support the deprecated FeatureForm composable which creates its own FormStateCollection.

kaushikrw · 2025-03-14T18:51:27Z

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureFormState.kt

+    form: FeatureForm,
+    elements: List<FormElement>,
+    scope: CoroutineScope,
+    ignoreList : Set<Class<out FormElement>> = emptySet(),


This param allows the deprecated FeatureForm composable to not display any FormElements such as UtillityAssociationsFormElement.

kaushikrw · 2025-03-14T18:59:47Z

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureForm.kt

 */
 @Composable
 public fun FeatureForm(
-    featureForm: FeatureForm,
+    featureFormState: FeatureFormState,
+    onDismiss: (() -> Unit)?,


Should this use a different mechanism to hide the close icon? For ex, use a showCloseIcon: Boolean instead of an optional parameter.

use a showCloseIcon: Boolean instead of an optional parameter.

I think that would be a good replacement

kaushikrw · 2025-03-15T01:31:35Z

...com/arcgismaps/toolkit/featureforms/internal/components/attachment/AttachmentElementState.kt

@@ -159,8 +149,6 @@ internal class AttachmentElementState(
        state.loadWithParentScope()
        // scroll to the new attachment after a delay to allow the recomposition to complete
        scope.launch {
-            delay(100)
-            lazyListState.scrollToItem(0)


Moved this into the composition as I was seeing an exception about doing this scrollToItem during the measurement phase.

eri9000

Some initial observations/suggestions

toolkit/featureforms/src/main/res/values/strings.xml

...reFormsApp/app/src/main/java/com/arcgismaps/toolkit/featureformsapp/screens/map/MapScreen.kt

eri9000 · 2025-03-17T18:22:18Z

...reFormsApp/app/src/main/java/com/arcgismaps/toolkit/featureformsapp/screens/map/MapScreen.kt

-                }
-            )
-        }
-
        // show pick a feature dialog if the layer is a sublayer
        is UIState.SelectFeature -> {


could this be a navigation route?

Possibly. I think that would be a good idea. It would also mean moving other screens like the FeatureFormSheet and AddFeatureSheet into separate destinations. If its okay, I will tackle this in a separate PR.

...reFormsApp/app/src/main/java/com/arcgismaps/toolkit/featureformsapp/screens/map/MapScreen.kt

...ormsApp/app/src/main/java/com/arcgismaps/toolkit/featureformsapp/screens/map/MapViewModel.kt

eri9000

a few more comments

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/internal/utils/Dialog.kt

...ismaps/toolkit/featureforms/internal/components/utilitynetwork/UtilityAssociationsElement.kt

.../java/com/arcgismaps/toolkit/featureforms/internal/components/utilitynetwork/Associations.kt

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureFormState.kt

kaushikrw · 2025-03-18T17:01:14Z

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureForm.kt

+    DisposableEffect(state) {
+        onDispose {
+            state.setNavigationCallback(null)
+            state.setNavigateBack(null)
+        }


Added DisposableEffect to set the navigation events back to null.

eri9000

Good work, a few more things.

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureFormState.kt

eri9000 · 2025-03-17T22:47:40Z

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureFormState.kt

+     * Pops the current [FeatureForm] from the stack and sets the previous form as the [activeFeatureForm].
+     */
+    internal fun popBackStack(): Boolean {
+        return if (store.size <= 1) {


Suggested change

return if (store.size <= 1) {

return if (store.isEmpty()) {

It's actually meant to check there is more than 1 element in the stack.

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureFormState.kt

toolkit/featureforms/src/main/java/com/arcgismaps/toolkit/featureforms/FeatureForm.kt

also updated api dump

eri9000

Great work @kaushikrw 👍🏼

kaushikrw and others added 30 commits January 9, 2025 18:16

init prototype

ee5abe2

added thru callback

96bc9d4

added utility element tap event

769f08b

reset lazy list state on new form

6cb5656

updated ui

fc09902

remove display count

70fa3ee

bump hilt version

da89ef3

add full view

32a0685

updated ui design

b7c692e

move navigation internally

4e27fe6

fix column

645bde3

add animations

72bd417

add feature selection

6118c0a

add state

12bb67f

bump compose navigation

8ae1f49

added state object

e5910b5

fixed element navigation

ad8df20

revert state data param

d02e7ec

hoist elements state upto the state holder

69dea0d

fixed saved navigation state

d44cc50

renamed state classes

f5cb866

add back save/discard dialog

5971be7

add doc

ec0a938

add back navigation to inner forms

3544d40

add icons

6c6a133

hoist evaluation expression to the state object

542db02

bump lib versions

f23f18a

add doc

c4a28ea

Update FeatureForm.kt

7762141

remove validation errors filtering (#762)

e13372d

optimize imports and remove unused code

4208963

kaushikrw commented Mar 14, 2025

View reviewed changes

Update FeatureForm.kt

5a7250b

kaushikrw commented Mar 14, 2025

View reviewed changes

kaushikrw added 4 commits March 14, 2025 13:40

add showActions and update API

0e454a6

add doc and fix association target element

c83c65e

disonnect navcontroller from state object

01ff67f

Update AttachmentElementState.kt

a2eaadf

kaushikrw commented Mar 15, 2025

View reviewed changes

kaushikrw marked this pull request as ready for review March 15, 2025 01:54

eri9000 self-requested a review March 17, 2025 16:48

eri9000 reviewed Mar 17, 2025

View reviewed changes

kaushikrw added 8 commits March 17, 2025 15:40

CR : Erick

e704e22

rename Associations to UtilityAssociations

fcf1d9e

change parameter to groupResults

5a21d8c

use rememberLazyListState

a618470

fix doc

18a12a9

removed dependency on navcontroller for dialogs

6267c41

optimize imports

edbbaf9

add disposable effect for navigation callbacks

eedb80e

kaushikrw commented Mar 18, 2025

View reviewed changes

update file name

75c6e56

eri9000 reviewed Mar 18, 2025

View reviewed changes

CR : feedback and add showCloseIcon param

05435c7

also updated api dump

eri9000 approved these changes Mar 18, 2025

View reviewed changes

Base automatically changed from feature-branches/forms to v.next March 28, 2025 23:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`FeatureForm` : support for UtilityAssociations #776

`FeatureForm` : support for UtilityAssociations #776

kaushikrw commented Mar 10, 2025 •

edited

Loading

kaushikrw Mar 14, 2025

kaushikrw Mar 14, 2025

kaushikrw Mar 14, 2025 •

edited

Loading

kaushikrw Mar 14, 2025

kaushikrw Mar 14, 2025 •

edited

Loading

eri9000 Mar 18, 2025

kaushikrw Mar 18, 2025

kaushikrw Mar 15, 2025

eri9000 left a comment

eri9000 Mar 17, 2025

kaushikrw Mar 17, 2025

eri9000 left a comment

kaushikrw Mar 18, 2025

eri9000 left a comment

eri9000 Mar 17, 2025

kaushikrw Mar 18, 2025

eri9000 left a comment

FeatureForm : support for UtilityAssociations #776

Are you sure you want to change the base?

FeatureForm : support for UtilityAssociations #776

Conversation

kaushikrw commented Mar 10, 2025 • edited Loading

Description:

UtilityAssociations UI structure

Navigation Support

API Changes

UI Changes

Internal Changes

Test Changes

Test Data

Notes

Pre-merge Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kaushikrw Mar 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kaushikrw Mar 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eri9000 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eri9000 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eri9000 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eri9000 left a comment

Choose a reason for hiding this comment

`FeatureForm` : support for UtilityAssociations #776

`FeatureForm` : support for UtilityAssociations #776

kaushikrw commented Mar 10, 2025 •

edited

Loading

kaushikrw Mar 14, 2025 •

edited

Loading

kaushikrw Mar 14, 2025 •

edited

Loading