Merge pull request #122 from SharePoint/Multi-Select-Samples

Multi-select and indexOf samples

column-samples/multi-choice-icons/README.md

@@ -0,0 +1,66 @@
+# Multi-Choice Icons
+
+## Summary
+This sample demonstrates using the `indexOf` and `join` functions (O365 only) to test if a multi-select choice field has a selected choice. Providing icons of the known choices and applying themed colors based on if the given choice is selected or not creates an intuitive, easy to understand visualization that doesn't suffer from varying item order or text formatting issues.
+
+![screenshot of the sample](./screenshot.png)
+
+This sample also demonstrates how to use double-quotes within your values. To include double quotes, you'll need to escape them using standard JSON syntax where you place a slash in front of the double quote: `"\"Juice\""`
+
+The `indexOf` function returns the index where a given value is found within a string (indexes start at 0). If the value is not found in the text, the result is -1.
+
+To evaluate if text contains a given value, we want to know if the index of the value within the string is anything but -1. So we can use the function like this:
+
+`"=if(indexOf(@currentField,'dog') != -1, 'Yes', 'No')"`
+
+Some example values and the result using the function above:
+`@currentField`|result
+---|---
+A dog | Yes
+a Dog | No
+dog's are nice | Yes
+bark dog bark | Yes
+
+Notice that the `indexOf` function is **case-sensitive**. You can do a case-insensitive check by adding the `toLowerCase` function like this:
+
+`"=if(indexOf(toLowerCase(@currentField),'dog') != -1, 'Yes', 'No')"`
+
+When it comes to an array of values (such as a multi-select choice or person column) we can't use `indexOf` directly because it expects a string value. Using it directly on multi-select fields will always result in -1.
+
+We can use the `join` or `toString` functions on the value first and then nest those within the `indexOf` call:
+
+`"=if(indexOf(join(@currentField,''),'dog') != -1, 'Yes', 'No')`
+
+## View requirements
+- This format can be applied to a Multi-Select Choice column
+
+### Sample Choice Values
+- Water
+- Coffee
+- Wine
+- Beer
+- "Juice"
+
+## Sample
+
+Solution|Author(s)
+--------|---------
+multi-choice-icons.json | [Chris Kent](https://twitter.com/thechriskent)
+
+## Version history
+
+Version|Date|Comments
+-------|----|--------
+1.0|February 5, 2019|Initial release
+
+## Disclaimer
+**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
+
+---
+
+## Additional notes
+- [Use column formatting to customize SharePoint](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/column-formatting)
+
+The `indexOf` and `join` functions are not available in SharePoint 2019
+
+<img src="https://telemetry.sharepointpnp.com/sp-dev-list-formatting/column-samples/multi-choice-icons" />

column-samples/multi-choice-icons/multi-choice-icons.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+  "elmType": "div",
+  "style": {
+    "font-size": "16px"
+  },
+  "children": [
+    {
+      "elmType": "span",
+      "attributes": {
+        "title": "Water",
+        "iconName": "Precipitation",
+        "class": "='ms-fontColor-' + if(indexOf(join(@currentField,''),'Water') != -1, 'themeDark', 'neutralLight')"
+      },
+      "style": {
+        "padding": "0 2px"
+      }
+    },
+    {
+      "elmType": "span",
+      "attributes": {
+        "title": "Coffee",
+        "iconName": "CoffeeScript",
+        "class": "='ms-fontColor-' + if(indexOf(join(@currentField,''),'Coffee') != -1, 'themeDark', 'neutralLight')"
+      },
+      "style": {
+        "padding": "0 2px 0 0"
+      }
+    },
+    {
+      "elmType": "span",
+      "attributes": {
+        "title": "Wine",
+        "iconName": "Wines",
+        "class": "='ms-fontColor-' + if(indexOf(join(@currentField,''),'Wine') != -1, 'themeDark', 'neutralLight')"
+      },
+      "style": {
+        "padding": "0 2px"
+      }
+    },
+    {
+      "elmType": "span",
+      "attributes": {
+        "title": "Beer",
+        "iconName": "BeerMug",
+        "class": "='ms-fontColor-' + if(indexOf(join(@currentField,''),'Beer') != -1, 'themeDark', 'neutralLight')"
+      },
+      "style": {
+        "padding": "0 2px"
+      }
+    },
+    {
+      "elmType": "span",
+      "attributes": {
+        "title": "\"Juice\"",
+        "iconName": "TestBeaker",
+        "class": "='ms-fontColor-' + if(indexOf(join(@currentField,''),'\"Juice\"') != -1, 'themeDark', 'neutralLight')"
+      },
+      "style": {
+        "padding": "0 2px"
+      }
+    }
+  ]
+}

column-samples/multi-person-currentuser/README.md

@@ -0,0 +1,39 @@
+# Highlight the current user
+
+## Summary
+This sample uses the `@me` keyword to check if the person field contains the current user and shows that entry using a different color and weight. This is a dynamic check that will always highlight the user using the list (not the creater of the format). This template could easily be extended to apply different/additional styles or icons as desired by simply copying the same expression logic for other fields.
+
+> Note - The entry set of users will be formatted (not just the current user's name)
+
+The [Office UI Fabric](https://developer.microsoft.com/en-us/fabric) theme color classes and a font weight class are used to ensure the format looks good across themes (including custom themes).
+
+![screenshot of the sample](./screenshot.png)
+
+## View requirements
+- This format can be applied to a Person column
+
+## Sample
+
+Solution|Author(s)
+--------|---------
+multi-person-currentuser.json | [Chris Kent](https://twitter.com/thechriskent)
+
+## Version history
+
+Version|Date|Comments
+-------|----|--------
+1.0|February 5, 2019|Initial release
+
+## Disclaimer
+**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
+
+---
+
+## Additional notes
+
+- [Use column formatting to customize SharePoint](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/column-formatting#me)
+
+This sample works for **both** single and multi-select person fields.However, an additional sample is available intended for use with single-select person fields: [person-currentuser-rowclass](../person-currentuser). It is a simpler sample intended to show how to use the `@me` operator.
+
+
+<img src="https://telemetry.sharepointpnp.com/sp-dev-list-formatting/column-samples/multi-person-currentuser" />

column-samples/multi-person-currentuser/multi-person-currentuser.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+  "elmType": "div",
+  "txtContent": "=join(@currentField.title, ', ')",
+  "attributes": {
+    "class": "=if(indexOf(join(@currentField.email,';'), @me) != -1, 'ms-fontColor-themePrimary ms-fontWeight-semibold', '')"
+  }
+}

column-samples/person-currentuser-format/README.md → column-samples/person-currentuser/README.md

@@ -37,4 +37,6 @@ A similar template is also included in the [Column Formatter](https://github.com
 
 > An additional version using Abstract Tree Syntax (AST) is also provided for environments where the Excel-style expressions are not supported.
 
+A similar sample is available for use with multi-select person fields: [multi-person-currentuser](../multi-person-currentuser)
+
 <img src="https://telemetry.sharepointpnp.com/sp-dev-list-formatting/column-samples/person-currentuser-format" />

column-samples/text-contains/README.md

@@ -0,0 +1,51 @@
+# Text Contains
+
+## Summary
+This sample demonstrates using the `indexOf` function (O365 only) to test if text contains a given value. The sample also uses the `toLowerCase` function to ensure the contains condition is case-insensitive. In this sample, if the text of the current field contains the word _"dead"_ a class is applied to turn the text red.
+
+![screenshot of the sample](./screenshot.png)
+
+The `indexOf` function returns the index where a given value is found within a string (indexes start at 0). If the value is not found in the text, the result is -1.
+
+To evaluate if text contains a given value, we want to know if the index of the value within the string is anything but -1. So we can use the function like this:
+
+`"=if(indexOf(@currentField,'dog') != -1, 'Yes', 'No')"`
+
+Some example values and the result using the function above:
+`@currentField`|result
+---|---
+A dog | Yes
+a Dog | No
+dog's are nice | Yes
+bark dog bark | Yes
+
+Notice that the `indexOf` function is **case-sensitive**. You can do a case-insensitive check by adding the `toLowerCase` function like this:
+
+`"=if(indexOf(toLowerCase(@currentField),'dog') != -1, 'Yes', 'No')"`
+
+## View requirements
+- This format can be applied to a Text or Choice column
+
+## Sample
+
+Solution|Author(s)
+--------|---------
+text-contains.json | [Chris Kent](https://twitter.com/thechriskent)
+
+## Version history
+
+Version|Date|Comments
+-------|----|--------
+1.0|February 5, 2019|Initial release
+
+## Disclaimer
+**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
+
+---
+
+## Additional notes
+- [Use column formatting to customize SharePoint](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/column-formatting)
+
+The `indexOf` and `toLowerCase` functions are not available in SharePoint 2019
+
+<img src="https://telemetry.sharepointpnp.com/sp-dev-list-formatting/column-samples/text-contains" />

column-samples/text-contains/text-contains.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+  "elmType": "div",
+  "txtContent": "@currentField",
+  "attributes": {
+    "class": "=if(indexOf(toLowerCase(@currentField),'dead') != -1, 'ms-fontColor-redDark','')"
+  }
+}

column-samples/text-startswith-callingcodes/README.md

@@ -0,0 +1,50 @@
+# Text StartsWith Calling Codes
+
+## Summary
+This sample demonstrates using the `indexOf` function (O365 only) to test if text starts with a given value. Using the international calling code at the start of a phone number, the correct country's flag is shown next to the phone number. The same nested conditionals are also used for the tooltip.
+
+![screenshot of the sample](./screenshot.png)
+
+The `indexOf` function returns the index where a given value is found within a string (indexes start at 0). If the value is not found in the text, the result is -1.
+
+To evaluate if text "startsWith" a given value, we want to know if the index of the value within the string is 0 (at the beginning). So we can use the function like this:
+
+`"=if(indexOf(@currentField,'A')==0, 'Yes', 'No')"`
+
+Some example values and the result using the function above:
+`@currentField`|result
+---|---
+A dog | Yes
+a dog | No
+Pet A dog | No
+
+Notice that the `indexOf` function is **case-sensitive**. You can do a case-insensitive check by adding the `toLowerCase` function like this:
+
+`=if(indexOf(toLowerCase(@currentField),'a')==0, 'Yes', 'No')`
+
+## View requirements
+- This format can be applied to a Text or Choice column
+
+## Sample
+
+Solution|Author(s)
+--------|---------
+text-startswith-callingcodes.json | [Chris Kent](https://twitter.com/thechriskent)
+
+## Version history
+
+Version|Date|Comments
+-------|----|--------
+1.0|February 5, 2019|Initial release
+
+## Disclaimer
+**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
+
+---
+
+## Additional notes
+- [Use column formatting to customize SharePoint](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/column-formatting)
+
+The `indexOf` function is not available in SharePoint 2019
+
+<img src="https://telemetry.sharepointpnp.com/sp-dev-list-formatting/column-samples/text-startswith-callingcodes" />

column-samples/text-startswith-callingcodes/text-startswith-callingcodes.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+  "elmType": "div",
+  "children": [
+    {
+      "elmType": "img",
+      "attributes": {
+        "src": "='http://flags.fmcdn.net/data/flags/h20/' + if(indexOf(@currentField,'+358')==0,'fi', if(indexOf(@currentField,'+61')==0,'au', if(indexOf(@currentField,'+46')==0,'se', if(indexOf(@currentField,'+47')==0,'no', if(indexOf(@currentField,'+7')==0,'ru', if(indexOf(@currentField,'+32')==0,'be', if(indexOf(@currentField,'+31')==0,'nl', if(indexOf(@currentField,'+43')==0,'at', if(indexOf(@currentField,'+353')==0,'ie', if(indexOf(@currentField,'+39')==0,'it', 'us')))))))))) + '.png'",
+        "title": "=if(indexOf(@currentField,'+358')==0,'Finland', if(indexOf(@currentField,'+61')==0,'Australia', if(indexOf(@currentField,'+46')==0,'Sweden', if(indexOf(@currentField,'+47')==0,'Norway', if(indexOf(@currentField,'+7')==0,'Russia', if(indexOf(@currentField,'+32')==0,'Belgium', if(indexOf(@currentField,'+31')==0,'Netherlands', if(indexOf(@currentField,'+43')==0,'Austria', if(indexOf(@currentField,'+353')==0,'Ireland', if(indexOf(@currentField,'+39')==0,'Italy', 'USA'))))))))))"
+      },
+      "style": {
+        "max-width": "23px",
+        "padding": "0 6px 0 0"
+      }
+    },
+    {
+      "elmType": "span",
+      "txtContent": "@currentField"
+    }
+  ]
+}

view-samples/multi-person-currentuser-rowclass/README.md

@@ -0,0 +1,34 @@
+# Current User's Rows (Using a Multi-Person Column)
+
+## Summary
+Highlights the entire row for any list items where one of the assigned to users is the current user (the user viewing the list view, not the author of the format). You can easily adjust this to use a different person column by changing the `[$AssignedTo]` portion of the expression.
+
+By using the Office UI Fabric color classes for themes, we can ensure our format looks good in all themes including both light and dark as well as custom themes.
+
+![Light and Dark Themes](./screenshot.png)
+
+## View requirements
+- This format expects a person column with an internal name of `AssignedTo` to be part of the view. This column can be single or multi-select.
+
+## Sample
+
+Solution|Author(s)
+--------|---------
+multi-person-currentuser-rowclass | [Chris Kent](https://twitter.com/thechriskent)
+
+## Version history
+
+Version|Date|Comments
+-------|----|--------
+1.0|January 29, 2019|Initial release
+
+## Disclaimer
+**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
+
+---
+
+## Additional notes
+
+This sample works for **both** single and multi-select person fields.However, an additional sample is available intended for use with single-select person fields: [person-currentuser-rowclass](../person-currentuser-rowclass). It is a simpler sample intended to show how to use the `@me` operator.
+
+<img src="https://telemetry.sharepointpnp.com/sp-dev-list-formatting/view-samples/multi-person-currentuser-rowclass" />

view-samples/multi-person-currentuser-rowclass/multi-person-currentuser-rowclass.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+  "elmType": "div",
+  "txtContent": "=join(@currentField.title, ', ')",
+  "attributes": {
+    "class": "=if(indexOf(join(@currentField.email,';'), @me) != -1, 'ms-fontColor-themePrimary ms-fontWeight-semibold', '')"
+  }
+}

view-samples/person-currentuser-rowclass/README.md

@@ -8,7 +8,9 @@ By using the Office UI Fabric color classes for themes, we can ensure our format
 ![Light and Dark Themes](./screenshot.png)
 
 ## View requirements
-- This format expects a person column with an internal name of `AssignedTo` to be part of the view
+- This format expects a person column with an internal name of `AssignedTo` to be part of the view 
+
+> Note - This format is intended only for single-select person fields. There is a slightly more complicated sample ([multi-person-currentuser-rowclass](../multi-person-currentuser-rowclass)) that works for both single and multi-select person columns.
 
 ## Sample
 
@@ -40,5 +42,6 @@ Column Format samples shown above:
 - [person-currentuser-format](../../column-samples/person-currentuser-format)
 - [date-range-format](../../column-samples/date-range-format)
 
+A similar sample is available for use with multi-select person fields: [multi-person-currentuser-rowclass](../multi-person-currentuser-rowclass)
 
 <img src="https://telemetry.sharepointpnp.com/sp-dev-list-formatting/view-samples/person-currentuser-rowclass" />