Forms: Update readme (#305)

Author: kaushikrw

toolkit/featureforms/README.md

@@ -1,70 +1,96 @@
+
+
 # FeatureForm
 
 ## Description
 
-The Forms toolkit component enables users to edit field values of features in a layer using forms that have been configured externally (using either in the the Web Map Viewer or the Fields Maps web app).
+The FeatureForm toolkit component enables users to edit field values of features in a layer using the `FeatureForm` API that has been configured externally (using either in the Web Map Viewer or the Fields Maps web app).
 
 ## Behavior
 
 To see it in action, check out the [microapp](../../microapps/FeatureFormsApp).
 
-## Usage
+## Features
 
-The `FeatureForm` composable is provided with its `FeatureFormState` and its default implementation `FeatureFormStateImpl` which is also available through the Factory function `FeatureFormState()`.
-They can be used either as a simple state class or within a ViewModel.
+The `FeatureForm` is a Composable that can render a `FeatureForm` object with a `FeatureFormDefinition`  using Jetpack Compose.
+- It can be integrated into any custom layout or container. The [microapp](../../microapps/FeatureFormsApp) integrates it into a `BottomSheet`.
+- All expressions are initially evaluated with a progress indicator before the FeatureForm is available for editing.
+- Provides automatic saving and restoring of form data after device configuration changes.
+- Shows validation errors for any fields with errors.
+- Visibility behavior of validation errors can be customized.
+- Supports all `FormInput` types except Attachments, Relationships and Barcodes.
+- Provides a DateTime picker and a picker for coded-value field types.
+- Follows material 3 design system.
 
 
-#### Creating the state using the Factory function
+## Usage
 
-```kotlin
-val formState = FeatureFormState()
-```
+A `FeatureForm` composable can be created using a `FeatureForm` object as follows.
 
-#### Using ViewModels
+#### Creating a FeatureForm object
 
 ```kotlin
-class MyViewModel : FeatureFormState by FeatureFormState() {
-    ...
-}
+// get the feature layer
+val layer = feature.featureTable.layer as FeatureLayer  
+// grab the FeatureFormDefinition from the layer
+val featureFormDefinition = layer.featureFormDefinition
+// create the FeatureForm from the Feature and the FeatureFormDefinition
+val featureForm = FeatureForm(feature, featureFormDefinition)
 ```
 
-#### Creating the FeatureForm
+#### Creating a FeatureForm in Compose
 
-The FeatureForm should be displayed in a Container and passed the `FeatureFormState`. 
-It's visibility and the container are external and should be controlled by the calling Composable.
+A `FeatureForm` can be created within a composition by simply calling the `FeatureForm` composable with the `FeaureForm` object. The FeatureForm should be displayed in a container. It's visibility and the container are external and should be controlled by the calling Composable.
 
-```kotlin
-@Composable
-fun MyComposable() {
-    // use the inEditingMode to control the visibility of the FeatureForm
-    val inEditingMode by formState.inEditingMode.collectAsState()
-    // a container
+```kotlin  
+@Composable  
+fun MyComposable(featureForm : FeatureForm) {  
+    // a container  
+    MyContainer(modifier = Modifier) {
+	// create a FeatureForm Composable
+        FeatureForm(  
+	    // pass in the FeatureForm object  
+	    featureForm = featureForm,  
+	    // control the layout using the modifier property  
+	    modifier = Modifier.fillMaxSize()  
+	)  
+    }  
+} 
+```  
+
+#### Updating the `FeatureForm`
+
+To display a new `FeatureForm`  object, simply trigger a recomposition with the new `FeatureForm` object.
+
+```kotlin  
+@Composable  
+fun MyComposable(viewModel : MyViewModel) {  
+    // use a state object that will recompose this composable when the featureForm changes
+    // in this example, the FeatureForm object is hoisted in the ViewModel
+    val featureForm : State by viewModel.featureForm  
+    // a container  
     MyContainer(modifier = Modifier) {
-        if (inEditingMode) {
-            // show the FeatureForm only when inEditingMode is true
-            FeatureForm(
-                // pass in our FeatureFormState
-                featureFormState = formState,
-                // control the layout using the modifier property
-                modifier = Modifier.fillMaxSize()
-            )
-        }
-    }
+        FeatureForm(    
+	    featureForm = featureForm,  
+	    modifier = Modifier.fillMaxSize()  
+	)  
+    }  
 }
-```
+```  
+
+#### Changing the Validation Error Visibility policy
 
-#### Updating the `FeatureFormState`
+By default validation errors for any fields are only visible after the fields gain focus. But this can be customized using the `validationErrorVisibility` parameter of the `FeatureForm`. This property can be changed at any time to show all the errors. It supports two modes of visibility.
 
-Changes to the `FeatureFormState` will cause a recomposition.
+- **ValidationErrorVisibility.Automatic** : *Indicates that the validation errors are only visible for editable fields that have received focus.*
+- **ValidationErrorVisibility.Visible** : *Indicates the validation is run for all the editable fields, and errors are displayed regardless of the focus state.*
 
 ```kotlin
 @Composable
-fun MyComposable() {
-    ....
-    // set the feature, this causes recomposition
-    formState.setFeature(feature)
-    // set formViewModel to editing state
-    formState.setEditingActive(true)
-    ....
-}
+FeatureForm(  
+    featureForm = featureForm,  
+    modifier = Modifier.fillMaxSize(),  
+    validationErrorVisibility = ValidationErrorVisibility.Visible  
+)
 ```
+*Note* : Once the `validationErrorVisibility`  is set to `Visible`, changing it back to `Automatic` will have no effect since all the fields have now gained focus to show any errors.