Merge pull request #62 from SharePoint/dev

Merge for v1.6.0
pnp · May 8, 2018 · ffcb027 · ffcb027
2 parents ce0bb82 + af533c2
commit ffcb027
Show file tree

Hide file tree

Showing 69 changed files with 2,485 additions and 160 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,21 @@
 # Releases
 
+## 1.6.0 
+
+**New controls**
+
+- `PropertyFieldCollectionData` was added [58](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/58)
+- `PropertyFieldOrder` was added [19](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/19)
+- `PropertyFieldSwatchColorPicker` was added [55](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/55)
+
+**Enhancements**
+
+- Allow the term set to be selectable in the `PropertyFieldTermPicker` [#60](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/60)
+
+**Fixes**
+
+- Fix for `PropertyFieldColorPicker` Palette Icon alignment issue in IE11 [56](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/56)
+
 ## 1.5.1
 
 **Enhancements**

diff --git a/docs/documentation/docs/about/release-notes.md b/docs/documentation/docs/about/release-notes.md
@@ -1,5 +1,17 @@
 # Releases
 
+## 1.6.0 
+
+**New controls**
+
+- `PropertyFieldCollectionData` was added [58](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/58)
+- `PropertyFieldOrder` was added [19](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/19)
+- `PropertyFieldSwatchColorPicker` was added [55](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/55)
+
+**Fixes**
+
+- Fix for `PropertyFieldColorPicker` Palette Icon alignment issue in IE11 [56](https://github.com/SharePoint/sp-dev-fx-property-controls/issues/56)
+
 ## 1.5.1
 
 **Enhancements**

diff --git a/docs/documentation/docs/assets/collectiondata.gif b/docs/documentation/docs/assets/collectiondata.gif
diff --git a/docs/documentation/docs/assets/order-onRenderItem.png b/docs/documentation/docs/assets/order-onRenderItem.png
diff --git a/docs/documentation/docs/assets/order-textProperty.png b/docs/documentation/docs/assets/order-textProperty.png
diff --git a/docs/documentation/docs/assets/order.gif b/docs/documentation/docs/assets/order.gif
diff --git a/docs/documentation/docs/assets/swatchcolorpicker-initial.png b/docs/documentation/docs/assets/swatchcolorpicker-initial.png
diff --git a/docs/documentation/docs/assets/swatchcolorpicker-selector.png b/docs/documentation/docs/assets/swatchcolorpicker-selector.png
diff --git a/docs/documentation/docs/controls/PropertyFieldCollectionData.md b/docs/documentation/docs/controls/PropertyFieldCollectionData.md
@@ -0,0 +1,127 @@
+# PropertyFieldCollectionData control
+
+This property field control gives you the ability to insert a list / collection data which can be used in your web part. For example: you want to specify multiple locations for showing a weather information.
+
+The control allows you to specify multiple data types like: string, number, boolean, or dropdown.
+
+**PropertyFieldCollectionData**
+
+![Code editor initial](../assets/collectiondata.gif)
+
+The type of data you get returned depends on the fields you defined. For the example above, the data looks like this:
+
+```json
+[
+  {"Title":"Person","Lastname":"1","Age":"42","City":"helsinki","Sign":true},
+  {"Title":"Person","Lastname":"2","Age":"42","City":"helsinki","Sign":true}
+]
+```
+
+## How to use this control in your solutions
+
+1. Check that you installed the `@pnp/spfx-property-controls` dependency. Check out The [getting started](../#getting-started) page for more information about installing the dependency.
+2. Import the following modules to your component:
+
+```TypeScript
+import { PropertyFieldCollectionData, CustomCollectionFieldType } from '@pnp/spfx-property-controls/lib/PropertyFieldCollectionData';
+```
+
+3. Create a new property for your web part, for example:
+
+```TypeScript
+export interface IPropertyControlsTestWebPartProps {
+  collectionData: any[];
+}
+```
+
+4. Add the custom property control to the `groupFields` of the web part property pane configuration:
+
+```TypeScript
+PropertyFieldCollectionData("collectionData", {
+  key: "collectionData",
+  label: "Collection data",
+  panelHeader: "Collection data panel header",
+  manageBtnLabel: "Manage collection data",
+  value: this.properties.collectionData,
+  fields: [
+    {
+      id: "Title",
+      title: "Firstname",
+      type: CustomCollectionFieldType.string,
+      required: true
+    },
+    {
+      id: "Lastname",
+      title: "Lastname",
+      type: CustomCollectionFieldType.string
+    },
+    {
+      id: "Age",
+      title: "Age",
+      type: CustomCollectionFieldType.number,
+      required: true
+    },
+    {
+      id: "City",
+      title: "Favorite city",
+      type: CustomCollectionFieldType.dropdown,
+      options: [
+        {
+          key: "antwerp",
+          text: "Antwerp"
+        },
+        {
+          key: "helsinki",
+          text: "Helsinki"
+        },
+        {
+          key: "montreal",
+          text: "Montreal"
+        }
+      ],
+      required: true
+    },
+    {
+      id: "Sign",
+      title: "Signed",
+      type: CustomCollectionFieldType.boolean
+    }
+  ],
+  disabled: false
+})
+```
+
+## Implementation
+
+The `PropertyFieldCollectionData` control can be configured with the following properties:
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| key | string | yes | An unique key that indicates the identity of this control. |
+| label | string | yes | Property field label displayed on top. |
+| panelHeader | string | yes | Label to be used as the header in the panel. |
+| manageBtnLabel | string | yes | Label of the button to open the panel. |
+| fields | ICustomCollectionField[] | yes | The fields to be used for the list of collection data. |
+| value | string | yes | The collection data value. |
+| disabled | boolean | no | Specify if the control is disabled. |
+
+Interface `ICustomCollectionField`
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| id | string | yes | ID of the field. |
+| title | string | yes | Title of the field. This will be used for the label in the table. |
+| type | yes | CustomCollectionFieldType | Specifies the type of field to render. |
+| required | no | boolean | Specify if the field is required. |
+| options | no | [IDropdownOption[]](https://developer.microsoft.com/en-us/fabric#/components/dropdown) | Dropdown options. Only necessary when dropdown type is used. |
+
+Enum `CustomCollectionFieldType`
+
+| Type |
+| ---- |
+| string |
+| number |
+| boolean |
+| dropdown |
+
+![](https://telemetry.sharepointpnp.com/sp-dev-fx-property-controls/wiki/PropertyFieldCollectionData)
diff --git a/docs/documentation/docs/controls/PropertyFieldColorPicker.md b/docs/documentation/docs/controls/PropertyFieldColorPicker.md
@@ -51,10 +51,11 @@ The `PropertyFieldColorPicker` control can be configured with the following prop
 | ---- | ---- | ---- | ---- |
 | label | string | yes | Property field label displayed on top. |
 | disabled | boolean | no | Specify if the control needs to be disabled. |
-| selectedColor | string | no | The CSS-compatible string to describe the initial color |
+| selectedColor | string or IColor | no | The CSS-compatible string or an IColor object to describe the initial color |
 | alphaSliderHidden | boolean | no | When true, the alpha slider control is hidden |
 | style | PropertyFieldColorPickerStyle | no | Determines how the control is displayed (defaults to inline) |
 | iconName | string | no | The name of the UI Fabric Font Icon to use for Inline display (defaults to Color) |
+| valueAsObject | boolean | no | When true, the property is returned as an IColor object. When false (default), the property is returned as a CSS-compatible string |
 | properties | any | yes | Parent web part properties, this object is use to update the property value.  |
 | onPropertyChange | function | yes | Defines a onPropertyChange function to raise when the date gets changed. |
 | key | string | yes | An unique key that indicates the identity of this control. |
@@ -66,4 +67,21 @@ Enum `PropertyFieldColorPickerStyle`
 | Full | Display the full control in the property pane |
 | Inline | Display the color picker inline |
 
+## Value
+
+By default, the Color Picker returns the value as a CSS-compatible string. This allows you the flexibility of simply assigning the value to an inline style as is and this is usually sufficient. However, this also limits the information directly available to you since the format could be a Hex code, an RGBA value, or even a named color and may not be suitable for advanced scenarios.
+
+By setting the `valueAsObject` property to true, you will always receive a consistent IColor object that provides you detailed information about the chosen color. Here are the properties available in the IColor object:
+
+| Property | Type | Description |
+| ---- | ---- | ---- |
+| str | string | CSS-compatible string (this is the same value that would normally be returned when `valueAsObject` is false) |
+| hex | string | Hex value (does not reflect alpha) |
+| r |  number | Red |
+| g | number | Green |
+| b | number | Blue |
+| h | number | Hue |
+| s | number | Saturation |
+| v | number | Value |
+
 ![](https://telemetry.sharepointpnp.com/sp-dev-fx-property-controls/wiki/PropertyFieldColorPicker)
diff --git a/docs/documentation/docs/controls/PropertyFieldNumber.md b/docs/documentation/docs/controls/PropertyFieldNumber.md
@@ -8,22 +8,22 @@ This control generates an input field for numbers. Text is not allowed as this w
 
 ## How to use this control in your solutions
 
-1. Check that you installed the `@pnp/spfx-property-controls` dependency. Check out The [getting started](../#getting-started) page for more information about installing the dependency.
-2. Import the following modules to your component:
+- Check that you installed the `@pnp/spfx-property-controls` dependency. Check out The [getting started](../#getting-started) page for more information about installing the dependency.
+- Import the following modules to your component:
 
 ```TypeScript
 import { PropertyFieldNumber } from '@pnp/spfx-property-controls/lib/PropertyFieldNumber';
 ```
 
-3. Create a new property for your web part, for example:
+- Create a new property for your web part, for example:
 
 ```TypeScript
 export interface IPropertyControlsTestWebPartProps {
   numberValue: number;
 }
 ```
 
-4. Add the custom property control to the `groupFields` of the web part property pane configuration:
+- Add the custom property control to the `groupFields` of the web part property pane configuration:
 
 ```TypeScript
 PropertyFieldNumber("numberValue", {
@@ -37,7 +37,7 @@ PropertyFieldNumber("numberValue", {
 })
 ```
 
-You can also implement your own validation with the `onGetErrorMessage` property as follows:
+- You can also implement your own validation with the `onGetErrorMessage` property as follows:
 
 ```TypeScript
 PropertyFieldNumber("numberValue", {

diff --git a/docs/documentation/docs/controls/PropertyFieldOrder.md b/docs/documentation/docs/controls/PropertyFieldOrder.md
@@ -0,0 +1,125 @@
+# PropertyFieldOrder control
+
+This control generates a list that can be easily reordered using drag and drop and/or arrow buttons.
+
+**PropertyFieldOrder**
+
+![PropertyfieldOrder reordering](../assets/order.gif)
+
+## How to use this control in your solutions
+
+1. Check that you installed the `@pnp/spfx-property-controls` dependency. Check out The [getting started](../#getting-started) page for more information about installing the dependency.
+2. Import the following modules to your component:
+
+```TypeScript
+import { PropertyFieldOrder } from '@pnp/spfx-property-controls/lib/PropertyFieldOrder';
+```
+
+3. Create a new property for your web part, for example:
+
+```TypeScript
+export interface IPropertyControlsTestWebPartProps {
+  orderedItems: Array<any>;
+}
+```
+
+4. Add the custom property control to the `groupFields` of the web part property pane configuration:
+
+```TypeScript
+PropertyFieldOrder("orderedItems", {
+  key: "orderedItems",
+  label: "Ordered Items",
+  items: this.properties.orderedItems,
+  properties: this.properties,
+  onPropertyChange: this.onPropertyPaneFieldChanged
+})
+```
+
+## Item Rendering
+
+By default, items will render using the `toString()` method for each element in your `items` array. This works well for simple arrays of strings, numbers, etc.
+
+### Object Property
+
+When working with an array of objects, you can specify the name of the property to use as the display value by specifying the `textProperty` property.
+
+For instance, for an array of objects like the following:
+```
+[
+  {"text": "Cat", "iconName": "Cat"},
+  {"text": "Pig", "iconName": "Savings"},
+  {"text": "Human", "iconName": "Running"},
+  {"text": "Robot", "iconName": "Robot"},
+  {"text": "Dog", "iconName": "FangBody"}
+]
+```
+To prevent every item from showing as `[object Object]`, you can set the `textProperty` property to the name of the property you would like to use for display:
+```TypeScript
+PropertyFieldOrder("orderedItems", {
+  key: "orderedItems",
+  label: "Ordered Items",
+  items: this.properties.orderedItems,
+  textProperty: "text",
+  properties: this.properties,
+  onPropertyChange: this.onPropertyPaneFieldChanged
+})
+```
+![PropertyFieldOrder display fixed by using the textProperty](../assets/order-textProperty.png)
+
+### Custom Rendering
+
+You can fully customize how items are rendered by providing the `onRenderItem` callback function and returning whatever `JSX.Element` you want.
+
+For example, you can define your function in a _tsx_ file like this:
+```TypeScript
+import * as React from 'react';
+
+export const orderedItem = (item:any, index:number): JSX.Element => {
+	return (
+		<span>
+			<i className={"ms-Icon ms-Icon--" + item.iconName} style={{paddingRight:'4px'}}/>
+			{item.text}
+		</span>
+	);
+};
+```
+
+You can then import this function into your webpart using the relative path to this file similar to the following:
+```TypeScript
+import { orderedItem } from './components/OrderedItem';
+```
+
+Then you can simply reference it in your `PropertyFieldOrder`:
+```TypeScript
+PropertyFieldOrder("orderedItems", {
+  key: "orderedItems",
+  label: "Ordered Items",
+  items: this.properties.orderedItems,
+  onRenderItem: orderedItem,
+  properties: this.properties,
+  onPropertyChange: this.onPropertyPaneFieldChanged
+})
+```
+![Customized item display using the onRenerItem callback property](../assets/order-onRenderItem.png)
+
+## Implementation
+
+The `PropertyFieldOrder` control can be configured with the following properties:
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| label | string | yes | Property field label displayed on top. |
+| items | Array<any> | yes | An array of values to reorder. |
+| textProperty | string | no | The property to use for display, when undefined, the toString() method of the object is used (ignored when the onRenderItem function is specified) |
+| maxHeight | number | no | The maximun height for the items in px (when not set, the control expands as necessary) |
+| disabled | boolean | no | Specify if the control needs to be disabled. |
+| disableDragAndDrop | boolean | no | When true, drag and drop reordering is disabled (defaults to false) |
+| removeArrows | boolean | no | When true, arrow buttons are not displayed (defaults to false) |
+| moveUpIconName | string | no | The name of the UI Fabric Font Icon to use for the move up button (defaults to ChevronUpSmall) |
+| moveDownIconName | string | no | The name of the UI Fabric Font Icon to use for the move down button (defaults to ChevronDownSmall) |
+| onRenderItem | function | no | Optional callback to provide custom rendering of the item (default is simple text based on either item or the property identified in the textProperty) |
+| properties | any | yes | Parent web part properties, this object is use to update the property value.  |
+| onPropertyChange | function | yes | Defines a onPropertyChange function to raise when the date gets changed. |
+| key | string | yes | An unique key that indicates the identity of this control. |
+
+![](https://telemetry.sharepointpnp.com/sp-dev-fx-property-controls/wiki/PropertyFieldOrder)