Merge remote-tracking branch 'upstream/master'

Author: skaggej

docs/declarative-customization/column-formatting.md

@@ -222,6 +222,18 @@ This example demonstrates an alternate syntax to express a conditional expressio
 }
 ```
 
+Here's the same sample from above, using the Excel-style expression syntax:
+```JSON
+{
+   "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+   "elmType": "div",
+   "txtContent": "@currentField",
+   "style": {
+      "color": "=if([$DueDate] <= @now + 86400000, '#ff0000', '')"
+   }
+}
+```
+
 <br/>
 
 
@@ -256,6 +268,18 @@ To compare a date/time field value against another date constant, use the `Date(
 }
 ```
 
+Here's the same sample from above, using the Excel-style expression syntax:
+```JSON
+{
+   "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+   "elmType": "div",
+   "txtContent": "@currentField",
+   "style": {
+      "color": "=if([$DueDate] <= Date('3/22/2017'), '#ff0000', '')"
+   }
+}
+```
+
 ## Create clickable actions
 
 You can use column formatting to provide hyperlinks that go to other webpages, or start custom functionality. This functionality is limited to static links that can be paramaterized with values from fields in the list. You can't use column formatting to output links to protocols other than `http://`, `https://`, or `mailto:`.
@@ -333,18 +357,28 @@ The following image shows a number column formatted as a data bar.
 
 ![Effort list with number list items shown as bars](../images/sp-columnformatting-databars.png)
 
-This example applies `background-color` and `border-top` styles to create a data bar visualization of `@currentField`, which is a number field. The bars are sized differently for different values based on the way the `width` attribute is set - it's set to `100%` when the value is greater than 95, and `(@currentField * 100 / 95)%` otherwise. To fit this example to your number column, you can adjust the boundary condition (`20`) to match the maximum anticipated value inside the field, and change the equation to specify how much the bar should grow depending on the value inside the field.
+This example applies `background-color` and `border-top` styles to create a data bar visualization of `@currentField`, which is a number field. The bars are sized differently for different values based on the way the `width` attribute is set - it's set to `100%` when the value is greater than 20, and `(@currentField * 5)%` otherwise. To fit this example to your number column, you can adjust the boundary condition (`20`) to match the maximum anticipated value inside the field, and change the equation to specify how much the bar should grow depending on the value inside the field.
 
 ```JSON
 {
   "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
   "elmType": "div",
-  "txtContent": "@currentField",
+  "children": [
+    {
+      "elmType": "span",
+      "txtContent": "@currentField",
+      "style": {
+        "padding-left": "8px",
+        "white-space": "nowrap"
+      }
+    }
+  ],
   "attributes": {
     "class": "sp-field-dataBars"
   },
   "style": {
-    "width": "=if(@currentField > 95, '100%', toString(@currentField * 100 / 95) + '%')"
+    "padding": "0",
+    "width": "=if(@currentField >= 20, '100%', (@currentField * 5) + '%')"
   }
 }
 ```
@@ -416,6 +450,27 @@ This example relies on two number fields, `Before` and `After`, for which the va
 }
 ```
 
+Here's the same sample from above, using the Excel-style expression syntax:
+```JSON
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+    "elmType": "div",
+    "children": [
+        {
+            "elmType": "span",
+            "attributes": {
+                "class": "=if([$After] > [$Before], 'sp-field-trending--up', 'sp-field-trending--down')",
+                "iconName": "=if([$After] > [$Before], 'SortUp', "=if([$After] < [$Before], 'SortDown', ''))"
+            }
+        },
+        {
+            "elmType": "span",
+            "txtContent": "[$After]"
+        }
+    ]
+}
+```
+
 ## Create a button to launch a Flow
 
 The following screenshot shows a list with a Flow button added to the Action column:
@@ -432,33 +487,33 @@ To use the sample below, you must substitute the ID of the Flow you want to run.
 
 ```JSON
 {
-	"$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
-	"elmType": "span",
-	"style": {
-		"color": "#0078d7"
-	},
-	"children": [
-    {
-		"elmType": "span",
-		"attributes": {
-			"iconName": "Flow"
-		}
-    },
-    {
-		"elmType": "button",
-		"style": {
-			"border": "none",
-			"background-color": "transparent",        
-			"color": "#0078d7",    
-			"cursor": "pointer"
-		},
-		"txtContent": "Send to Manager",
-		"customRowAction": {
-			"action": "executeFlow",
-			"actionParams": "{\"id\": \"183bedd4-6f2b-4264-855c-9dc7617b4dbe\"}"
-		}          
-    }        
-  ]
+   "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+   "elmType": "span",
+   "style": {
+      "color": "#0078d7"
+   },
+   "children": [
+      {
+         "elmType": "span",
+	 "attributes": {
+	    "iconName": "Flow"
+	 }
+      },
+      {
+         "elmType": "button",
+	 "style": {
+	    "border": "none",
+	    "background-color": "transparent",
+	    "color": "#0078d7",
+	    "cursor": "pointer"
+	 },
+	 "txtContent": "Send to Manager",
+	 "customRowAction": {
+	    "action": "executeFlow",
+	    "actionParams": "{\"id\": \"183bedd4-6f2b-4264-855c-9dc7617b4dbe\"}"
+	 }
+      }
+   ]
 }
 ```
 
@@ -746,20 +801,35 @@ The following example shows the value of a style object. In this example, two st
 ```JSON
 {
    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
-   "padding": "4px",
-   "background-color": {
-      "operator": "?",
-      "operands": [
-         {
-            "operator": "<",
-            "operands": [
-               "@currentField",
-               40
-            ]
-         },
-         "#ff0000",
-         "#00ff00"
-      ]
+   "elmType": "div",
+   "style": {
+      "padding": "4px",
+      "background-color": {
+         "operator": "?",
+         "operands": [
+            {
+               "operator": "<",
+               "operands": [
+                  "@currentField",
+                  40
+               ]
+            },
+            "#ff0000",
+            "#00ff00"
+         ]
+      }
+   }
+}
+```
+
+Here's the same sample from above, using the Excel-style expression syntax:
+```JSON
+{
+   "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+   "elmType": "div",
+   "style": {
+      "padding": "4px",
+      "background-color": "=if(@currentField < 40, '#ff0000', '#00ff00')"
    }
 }
 ```
@@ -783,9 +853,9 @@ Any other attribute name will result in an error. Attribute values can either be
 
 ```JSON
 {
-        "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
-	"target": "_blank",
-	"href": "='http://finance.yahoo.com/quote/' + @currentField"
+    "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+    "target": "_blank",
+    "href": "='http://finance.yahoo.com/quote/' + @currentField"
 }
 ```
 
@@ -799,11 +869,13 @@ An optional property that is meant for debugging. It outputs error messages and
 
 ### 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. 
+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.
+
+Expressions can be written using Excel-style expressions in SharePoint Online, or by using Abstract Syntax Tree expressions in SharePoint Online and SharePoint 2019.
 
 #### Excel-style expressions
 
-All Excel-style expressions begin with an equal (`=`) sign.  
+All Excel-style expressions begin with an equal (`=`) sign. This style of expression is only available in SharePoint Online (not SharePoint 2019).
 
 This simple conditional expression evaluates to `none` if `@me` is not equal to `[$Author.email]`, and evaluates to \`\` otherwise:
 ```JSON
@@ -896,6 +968,7 @@ Operators specify the type of operation to perform. The following operators are
 - toLowerCase
 - join
 - length
+- abs
 
 **Binary arthmetic operators** - The following are the standard arithmetic binary operators that expect two operands: 
 
@@ -936,10 +1009,13 @@ Operators specify the type of operation to perform. The following operators are
 - **toLocaleTimeString()**: returns a language sensitive representation of just the time portion of a date
   - `"txtContent":"=toLocaleTimeString(@now)"` results vary based on user's locale, but en-us looks like _"1:22:24 PM"_
 
-- **toLowerCase**: returns the value converted to lower case (only works on strings)
+- **toLowerCase**: returns the value converted to lower case (only works on strings) - _Only available in SharePoint Online_
   - `"txtContent":"=toLowerCase('DogFood')"` results in _"dogfood"_
 
-- **length**: returns the number of items in an array (multi-select person or choice field), for all other value types it returns 1 when true and 0 when false. It does NOT provide the length of a string value.
+- **abs**: returns the absolute value for a given number - _Only available in SharePoint Online_
+  - `"txtContent":"=abs(-45)"` results in _45_
+  
+- **length**: returns the number of items in an array (multi-select person or choice field), for all other value types it returns 1 when true and 0 when false. It does NOT provide the length of a string value. - _Only available in SharePoint Online_
   - `"txtContent":"=length(@currentField)"` might result in _2_ if there are 2 selected values
   - `"txtContent":"=length('Some Text')"` results in _1_
   - `"txtContent":"=length('')"` results in _0_
@@ -948,13 +1024,13 @@ Operators specify the type of operation to perform. The following operators are
 
 **Binary operators** - The following are operators that expect two operands:
 
-- **indexOf**: takes 2 operands. The first is the text you would like to search within, the second is the text you would like to search for. Returns the index value of the first occurence of the search term within the string. Indexes start at 0. If the search term is not found within the text, -1 is returned. This operator is case-sensitive.
+- **indexOf**: takes 2 operands. The first is the text you would like to search within, the second is the text you would like to search for. Returns the index value of the first occurence of the search term within the string. Indexes start at 0. If the search term is not found within the text, -1 is returned. This operator is case-sensitive. - _Only available in SharePoint Online_
   - `"txtContent": "=indexOf('DogFood', 'Dog')"` results in _0_
   - `"txtContent": "=indexOf('DogFood', 'F')"` results in _3_
   - `"txtContent": "=indexOf('DogFood', 'Cat')"` results in _-1_
   - `"txtContent": "=indexOf('DogFood', 'f')"` results in _-1_
 
-- **join**: takes 2 operands. The first is an array (multi-select person or choice field) and the second is the separating string. Returns a string concatenation of the array values separated by the separating string.
+- **join**: takes 2 operands. The first is an array (multi-select person or choice field) and the second is the separating string. Returns a string concatenation of the array values separated by the separating string. - _Only available in SharePoint Online_
   - `"txtContent": "=join(@currentField, ', ')"` might result in _"Apple, Orange, Cherry"_ (depending on the selected values)
   - `"txtContent": "=join(@currentField.title, '|')"` might result in _"Chris Kent|Vesa Juvonen|Jeff Teper"_ (depending on the selected persons)
 
@@ -1016,6 +1092,15 @@ For example, the following JSON will display the current field (assuming it's a
 }
 ```
 
+Here's the same sample from above, using the Excel-style expression syntax:
+```JSON
+{
+   "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+   "elmType": "div",
+   "txtContent": "=toLocaleString(@currentField)"
+}
+```
+
 **Lookup fields**
 
 The lookup field object has the following properties (with example values):
@@ -1085,7 +1170,7 @@ If the value of a field is an object, the object's properties can be accessed. F
 
 #### "@currentWeb"
 
-This will evaluate to the absolute url for the site. This is equivalent to the `webAbsoluteUrl` value within the page context.
+This will evaluate to the absolute url for the site. This is equivalent to the `webAbsoluteUrl` value within the page context. This value is only available in SharePoint Online.
 
 #### "@me"
 
@@ -1117,10 +1202,34 @@ This field can be used to display the current user's email address, but more lik
 }
 ```
 
+Here's the same sample from above, using the Excel-style expression syntax:
+```JSON
+{
+   "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
+   "elmType": "div",
+   "txtContent": "@currentField.title",
+   "style": {
+      "color": "=if(@me == @currentField.email, 'red', 'blue')"
+   }
+}
+```
+
 #### "@now"
 
 This will evaluate to the current date and time.
 
+#### "@rowIndex"
+
+This will evaluate to the rendered index of a row within a view. This value is based on render position and will remain consistent based on position even as views are sorted and filtered. Indexes start at 0. This value is only available in SharePoint Online.
+
+Here's an example of using the value within a view format to apply alternating styles to rows:
+```JSON
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
+  "additionalRowClass": "=if(@rowIndex % 2 == 0,'ms-bgColor-themeLighter ms-bgColor-themeLight--hover','')"
+}
+```
+
 #### "@window.innerHeight"
 
 This will evaluate to a number equal to the height of the browser window (in pixels) when the list was rendered.

docs/spfx/web-parts/basics/add-an-external-library.md

@@ -26,7 +26,7 @@ By default, the web part bundler automatically includes any library that is a de
     ```
 
     > [!NOTE] 
-    > Because you're using TypeScript, you need typings for the package you add. This is essential when you are writing code because TypeScript is just a superset of JavaScript. All the TypeScript code is still converted to JavaScript code when you compile. You can search for and find typings by using **npm**, for example: `npm install @types/{package} --save`
+    > Because you're using TypeScript, you need typings for the package you add. This is essential when you are writing code because TypeScript is just a superset of JavaScript. All the TypeScript code is still converted to JavaScript code when you compile. You can search for and find typings by using **npm**, for example: `npm install @types/{package} --save-dev`
 
 3. Create a file in the your web part's folder called `validator.d.ts` and add the following:
 
@@ -69,7 +69,7 @@ In this example, you will share the [marked](https://www.npmjs.com/package/marke
 2. Download the typings:
 
     ```sh
-    npm install @types/marked --save
+    npm install @types/marked --save-dev
     ```
 
 3. Edit the **config/config.json**, and add an entry to the **externals** map. This is what tells the bundler to put this in a separate file. This prevents the bundler from bundling this library:
@@ -101,7 +101,7 @@ In this example, you will load jQuery from CDN. You don't need to install the np
 1. Install the typings for jQuery:
 
     ```sh
-    npm install --save @types/jquery
+    npm install --save-dev @types/jquery
     ```
 
 2. Update the `config.json` in the `config` folder to load jQuery from CDN. Add an entry to the `externals` field:
@@ -279,13 +279,13 @@ Loading SharePoint JSOM is essentially the same scenario as loading non-AMD scri
 1. Install typings for Microsoft Ajax, which is a dependency for JSOM typings:
 
     ```sh
-    npm install @types/microsoft-ajax --save
+    npm install @types/microsoft-ajax --save-dev
     ```
 
 2. Install typings for the JSOM:
 
     ```sh
-    npm install @types/sharepoint --save
+    npm install @types/sharepoint --save-dev
     ```
 
 3. Add entries to the `config.json`: