Merge pull request SharePoint#7495 from shagra-ms/shagra/docs-edit-actions

Support setValue and inlineEditField

Author: andrewconnell

docs/declarative-customization/formatting-advanced.md

@@ -254,3 +254,106 @@ The following image shows a list with a Gallery layout referencing the Category
   }
 }
 ```
+## Inline Editing
+
+With inline editing, formatters have the ability to load field editors to edit field data on an item. 
+Users need to have edit permissions on the list item and the field type should belong to set of supported types for this feature to work.
+
+A special json property `inlineEditField` is used with value as the field internal name __`[$FieldName]`__ at the target element in the json.
+
+```json
+{
+  "elmType": "div",
+  "inlineEditField": "[$FieldName]",
+  "txtContent": "[$FieldName]"
+}
+```
+<br />
+
+![Inline Editing using inlineEditField property](../images/sp-columnformatting-inline-editing.gif)
+
+This allows the users to edit items in-place, within the view, without navigating away to grid based editing or to a item edit form.
+
+### Supported Field Types
+List of supported field types for inline editing
+- Single line text
+- Multi line text (without RTF)
+- Number
+- DateTime
+- Choice and MultiChoice
+- User and Multi user
+- Lookup
+
+### Hover Borders and Customizations
+The inline editing adds a hover border on the elements to indicate these elements have an associated action. The default border is `neutralSecondary` , and on click, the editor appears with a `themePrimary` border. These border colors can be overriden via setting style on the same element with `inlineEditField` by using some special attributes - `--inline-editor-border-width`, `--inline-editor-border-style`, `--inline-editor-border-radius` and `--inline-editor-border-color`.
+
+```json
+{
+  "elmType": "div",
+  "inlineEditField": "[$FieldName]",
+  "txtContent": "[$FieldName]",
+  "style": {
+    "--inline-editor-border-color": "transparent transparent red transparent",
+    "border-color": "gray",
+    "border-width": "1px",
+    "border-style": "solid"
+  }
+}
+```
+
+## Set multiple field values of an Item using customRowAction
+
+With the new `setValue` `customRowAction`, formatters can render action buttons which modify the item internally without opening editors or forms. `setValue` also allows setting multiple field values of the item at once.
+
+The below JSON will set value of `FieldInternalName_1`, `FieldInternalName_2` and `FieldInternalName_3`with the values provided.
+
+```json
+{
+  "elmType": "div",
+  "txtContent": "[$FieldName]",
+  "customRowAction":{
+    "action": "setValue",
+    "actionInput": {
+      "FieldInternalName_1": "FieldValue_1",
+      "FieldInternalName_2": "FieldValue_2",
+      "FieldInternalName_3": "=if([$Status] == 'Completed', 'yes', 'no')"
+    }
+  }
+}
+```
+
+### Supported Field Types
+- Single line text
+- Multi line text (without RTF)
+- Number
+- DateTime
+- Choice and MultiChoice
+- User and Multi user
+
+### Value Field values in `actionInput` :
+  - Text values:
+    - a valid string like `"Choice 1"`
+    - value from other columns : `[$ColumnName]`
+    - an [expression](./formatting-syntax-reference.md#expressions) like <br>
+    `"if([$column]> 10, "Choice A", "Choice B")"` <br>
+    or
+    `{operator: "+", operands" : ["Choice", "A"]}`
+  - Number:
+    - a valid number
+    - value from other columns : `[$ColumnName]`
+    - an [expression](./formatting-syntax-reference.md#expressions)
+  - Date values :
+    - a date string
+    - `@now` token
+    - [expressions](./formatting-syntax-reference.md#expressions) which return a date using builtin date functions
+    - `addDays` and `addMinutes`, two new functions to support [expressions](./formatting-syntax-reference.md#expressions) like 7 days from today
+  - Multi-Choice and Multi-Person:
+    Multi value fields are special, as they need an array value to save multiple values.
+    - `appendTo` and `removeFrom`, two new functions which operate on multivalue fields.
+        - `appendTo([$MultiChoiceField], 'MyValue')`
+  - Person field values:
+    - User Name or Email
+    - an [expression](./formatting-syntax-reference.md#expressions) which returns these values
+    > [!NOTE]
+    > A query runs with the string value provided on people column and the first person in the returned results is used
+

docs/declarative-customization/formatting-syntax-reference.md

@@ -1,7 +1,7 @@
 ---
 title: Formatting syntax reference
 description: Formatting syntax reference
-ms.date: 11/11/2021
+ms.date: 11/16/2021
 ms.localizationpriority: high
 ---
 
@@ -180,6 +180,11 @@ An optional property that specifies style attributes to apply to the element spe
 
 'stroke'
 'fill-opacity'
+
+'--inline-editor-border-width'
+'--inline-editor-border-style'
+'--inline-editor-border-radius'
+'--inline-editor-border-color'
 ```
 
 The following example shows the value of a style object. In this example, two style properties (`padding` and `background-color`) will be applied. The `padding` value is a hard-coded string value. The `background-color` value is an Expression that is evaluated to either red (`#ff0000`) or green (`#00ff00`) depending on whether the value of the current field (specified by `@currentField`) is less than 40. For more information, see the Expression object section. 
@@ -307,6 +312,21 @@ See [here](./column-formatting.md#formatting-multi-value-fields) for examples.
 - **delete**: Clicking the button will open the delete confirmation dialog.
 - **editProps**:  Clicking the button will open the item properties page in edit mode.
 - **openContextMenu**:  Clicking the button will open the item's default context menu.
+- **setValue**:  Clicking the element will update the item with the field values provided.
+
+```JSON
+{
+  "elmType": "div",
+  "txtContent": "[$FieldName]",
+  "customRowAction":{
+    "action": "setValue",
+    "actionInput": {
+      "FieldInternalName_1": "FieldValue_1",
+      "FieldInternalName_2": "FieldValue_2",
+    }
+  }
+}
+```
 - **executeFlow**:  Clicking the button will launch the specified Flow, specified by ID inside the `actionParams` attribute.  For an example of this, see [Create a button to launch a Flow](./formatting-advanced.md#create-a-button-to-launch-a-flow). Below is an example of this type of button.
 
 ```JSON
@@ -325,7 +345,6 @@ The `actionParams` attribute can have the following options when using the `exec
 - **id**: ID of the Flow to launch _(required)_
 - **headerText**: Sets the text at the top of the flow panel _(optional)_
 - **runFlowButtonText**: Sets the text of the primary button in the flow panel _(optional)_
-- 
 
 ## customCardProps
 
@@ -353,6 +372,18 @@ This will be replaced with the referenced column's formatter JSON. Multi level r
 }
 ```
 
+## inlineEditField
+
+Adds the field editor for the referenced column. 
+
+```JSON
+{
+  "elmType": "div",
+  "inlineEditField": "[$FieldName]",
+  "txtContent": "[$FieldName]"
+}
+```
+
 ## Expressions
 
 Values for `txtContent`, style properties, and attribute properties can be expressed as expressions, so that they are evaluated at runtime based on the context of the current field (or row). Expression objects can be nested to contain other Expression objects.
@@ -473,6 +504,10 @@ Operators specify the type of operation to perform. The following operators are
 - padStart
 - padEnd
 - getUserImage
+- addDays
+- addMinutes
+- appendTo
+- removeFrom
 
 **Binary arithmetic operators** - The following are the standard arithmetic binary operators that expect two operands: 
 
@@ -584,6 +619,22 @@ Operators specify the type of operation to perform. The following operators are
   - `"src":"=getUserImage('[email protected]', 'large')"` returns a URL pointing to user's profile picture in large resolution
   - `"src":"=getUserImage('[email protected]', 'l')"` returns a URL pointing to user's profile picture in large resolution
 
+- **appendTo**: returns an array with the given entry appended to the given array
+  - `"txtContent": "=appendTo(@currentField, 'Choice 4')"` returns an array with 'Choice 4' added to the @currentField array
+  - `"txtContent": "=appendTo(@currentField, '[email protected]')"` returns an array with '[email protected]' added to the @currentField array
+
+- **removeFrom**: returns an array with the given entry removed from the given array, if present
+  - `"txtContent": "=removeFrom(@currentField, 'Choice 4')"` returns an array with 'Choice 4' removed from the @currentField array
+  - `"txtContent": "=removeFrom(@currentField, '[email protected]')"` returns an array with '[email protected]' removed from the @currentField array
+
+- **addDays**: returns a datetime object with days added (or deducted) from the given datetime value
+  - `"txtContent": "=addDays(Date('11/14/2021'), 3)"` returns a 11/17/2021, 12:00:00 AM
+  - `"txtContent": "=addDays(Date('11/14/2021'), -1)"` returns a 11/13/2021, 12:00:00 AM
+
+- **addMinutes**: returns a datetime object with minutes added (or deducted) from the given datetime value
+  - `"txtContent": "=addMinutes(Date('11/14/2021'), 3)"` returns a 11/14/2021, 12:03:00 AM
+  - `"txtContent": "=addMinutes(Date('11/14/2021'), -1)"` returns a 11/13/2021, 11:59:00 AM
+ 
 **Ternary operators** - The following are operators that expect three operands:
 
 - **substring**: returns the part of the string between the start and end indices. - _Only available in SharePoint Online_