Merge branch 'dev' into iconPickerNewViewOptions

Author: AJIXuMuK

CHANGELOG.JSON

@@ -4,7 +4,8 @@
       "version": "1.18.0",
       "changes": {
         "new": [
-          "Pagination Control [#535](https://github.com/SharePoint/sp-dev-fx-controls-react/pull/535)"
+          "Pagination Control [#535](https://github.com/SharePoint/sp-dev-fx-controls-react/pull/535)",
+          "TreeView Control [#536](https://github.com/SharePoint/sp-dev-fx-controls-react/pull/536)"
         ],
         "enhancements": [
           "`FolderExplorer` updates: allow selection of libraries if site url is used as the root, allow passing items to be passed as a property and added to the breadcrumb, add support for loading folders from a different site, fix breadcrumb names for document libraries [#534](https://github.com/SharePoint/sp-dev-fx-controls-react/pull/534)"
@@ -21,6 +22,7 @@
         "[Gautam Sheth](https://github.com/gautamdsheth)",
         "[João Mendes](https://github.com/joaojmendes)",
         "[Joel Rodrigues](https://github.com/joelfmrodrigues)",
+        "[Nanddeep Nachan](https://github.com/nanddeepn)",
         "[Prasad Kasireddy](https://github.com/PrasadKasireddy)",
         "[Siddharth Vaghasia](https://github.com/siddharth-vaghasia)"
       ]

docs/documentation/docs/assets/TreeView-all-possible-options.png

@@ -0,0 +1,246 @@
+## TreeView control
+
+This graphical control allows to present a hierarchical view of information. Each tree item can have a number of subitems. This is often visualized by indentation in a list. A tree item can be expanded to reveal subitems (if exist), and collapsed to hide subitems.
+
+Here are examples of the control in action:
+
+![Tree View control](../assets/TreeView-control.gif)
+
+**With all possible options**
+
+![Tree View control](../assets/TreeView-all-possible-options.png)
+
+**Without check boxes or when selection mode is 'None'**
+
+![Tree View control](../assets/TreeView-without-checkbox.png)
+
+**Without check boxes, and selection mode is multiple**
+
+![Tree View control](../assets/TreeView-without-checkbox-selection-mode.png)
+
+## How to use this control in your solutions
+
+- Check that you installed the `@pnp/spfx-controls-react` 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 { TreeView, ITreeItem } from "@pnp/spfx-controls-react/lib/TreeView";
+```
+
+- Use the `TreeView` control in your code as follows:
+
+```TypeScript
+<TreeView 
+    items={treeitems}
+    defaultExpanded={false}
+    selectionMode={TreeViewSelectionMode.Multiple}
+    selectChildrenIfParentSelected={true}
+    showCheckboxes={true}
+    treeItemActionsDisplayMode={TreeItemActionsDisplayMode.ContextualMenu}
+    defaultSelectedKeys=['key1', 'key2'],
+    onSelect={this.onTreeItemSelect}
+    onExpandCollapse={this.onTreeItemExpandCollapse}
+    onRenderItem={this.renderCustomTreeItem} />
+```
+
+- With the `onSelect` property you can capture the event of when the tree item in the TreeView has changed the selection:
+
+```typescript
+private onTreeItemSelect(items: ITreeItem[]) {
+    console.log("Items selected: ", items);
+}
+```
+
+- With the `onExpandCollapse` property you can capture the event of when the tree item in the TreeView has expanded or collapsed:
+
+```typescript
+private onTreeItemExpandCollapse(item: ITreeItem, isExpanded: boolean) {
+    console.log((isExpanded ? "Item expanded: " : "Item collapsed: ") + item);  
+}
+```
+
+## Custom Rendering
+You can fully customize how tree 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';
+
+private renderCustomTreeItem(item: ITreeItem): JSX.Element {
+  return (
+    <span>
+      {
+        item.iconProps &&
+        <i className={"ms-Icon ms-Icon--" + item.iconProps.iconName} style={{ paddingRight: '4px' }} />
+      }
+      {item.label}
+    </span>
+  );
+}
+```
+
+## Implementation
+
+The `TreeView` control can be configured with the following properties:
+
+| Property                       | Type                       | Required | Description                                                                                                                        |
+|--------------------------------|----------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------|
+| items                          | ITreeItem[]                | yes      | An array of tree items to display. refer [example](#example-of-array-of-tree-items-used-to-render-control-as-in-first-screenshot). |
+| defaultExpanded                | boolean                    | no       | Specify if the tree items are displayed as expanded by default (defaults to false).                                                |
+| selectionMode                  | enum                       | no       | Specify the selection mode of tree view (defaults to Single selection).                                                            |
+| selectChildrenIfParentSelected | boolean                    | no       | Specify if the childrens should be selected when parent item is selected (defaults to false).                                      |
+| showCheckboxes                 | boolean                    | yes      | Specify if the checkboxes should be displayed for selection.                                                                       |
+| treeItemActionsDisplayMode     | TreeItemActionsDisplayMode | no       | Specify the display mode of the tree item actions.                                                                                 |
+| defaultSelectedKeys            | string[]                   | no       | Specify keys of items to be selected by default.                                                                                   |
+| onExpandCollapse               | function                   | no       | Defines a onExpandCollapse function to raise when the tree item has expanded or collapsed.                                         |
+| onSelect                       | function                   | no       | Captures the event of when the tree item selection has changed.                                                                    |
+| onRenderItem                   | function                   | no       | Optional callback to provide custom rendering of the item (default is simple text of item label and a checkbox for selection).     |
+
+Enum `TreeViewSelectionMode`
+
+Specifies the selection mode of tree item.
+| Value    |
+|----------|
+| Single   |
+| Multiple |
+| None     |
+
+Interface `ITreeItem`
+
+Each tree item in the `treeitems` property is defined as `ITreeItem` as follows:
+
+| Property   | Type              | Required | Description                                                      |
+|------------|-------------------|----------|------------------------------------------------------------------|
+| key        | string            | yes      | The unique ID of the tree item.                                  |
+| label      | string            | yes      | Text displayed next to checkbox.                                 |
+| subLabel   | string            | no       | The sub label of the tree item.                                  |
+| iconProps  | IIconProps        | no       | Custom icon to be rendered before label.                         |
+| disabled   | boolean           | no       | Specify if the tree item needs to be disabled. Default is false. |
+| selectable | boolean           | no       | Specify if the tree item can be selected. Default is true.       |
+| data       | any               | no       | Specify an additional data of the tree item.                     |
+| actions    | ITreeItemAction[] | no       | Specify list of actions for the tree item.                       |
+| children   | ITreeItem[]       | no       | Specify list of child tree items.                                |
+
+
+Interface `ITreeItemAction`
+
+Specifies the list of actions for the tree item.
+| Property             | Type                                 | Required | Description                                                                                                                |
+|----------------------|--------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------|
+| id                   | string                               | yes      | Unique id of the action.                                                                                                   |
+| title                | string                               | yes      | Title of the action.                                                                                                       |
+| iconProps            | IIconProps                           | no       | Name of the icon to be used to display action.                                                                             |
+| hidden               | boolean                              | no       | Specify if the action is hidden. This could be used for instance when you want to invoke the action right after rendering. |
+| invokeActionOnRender | boolean                              | no       | Specifies if you want to invoke the action on render.                                                                      |
+| actionCallback       | (currentTreeItem: ITreeItem) => void | yes      | Method to be executed when action is fired.                                                                                |
+
+Enum `TreeItemActionsDisplayMode`
+
+Specifies the display mode of the tree item action.
+| Value          |
+|----------------|
+| Buttons        |
+| ContextualMenu |
+
+## Example of array of tree items used to render control as in 2nd screenshot
+
+```typescript
+items: [
+          {
+            key: "R1",
+            label: "Root",
+            subLabel: "This is a sub label for node",
+            iconProps: skypeCheckIcon,
+            actions: [{
+              title: "Get item",
+              iconProps: {
+                iconName: 'Warning',
+                style: {
+                  color: 'salmon',
+                },
+              },
+              id: "GetItem",
+              actionCallback: async (treeItem: ITreeItem) => {
+                console.log(treeItem);
+              }
+            }],
+            children: [
+              {
+                key: "1",
+                label: "Parent 1",
+                selectable: false,
+                children: [
+                  {
+                    key: "3",
+                    label: "Child 1",
+                    subLabel: "This is a sub label for node",
+                    actions: [{
+                      title:"Share",
+                      iconProps: {
+                        iconName: 'Share'
+                      },
+                      id: "GetItem",
+                      actionCallback: async (treeItem: ITreeItem) => {
+                        console.log(treeItem);
+                      }
+                    }],
+                    children: [
+                      {
+                        key: "gc1",
+                        label: "Grand Child 1",
+                        actions: [{
+                          title: "Get Grand Child item",
+                          iconProps: {
+                            iconName: 'Mail'
+                          },
+                          id: "GetItem",
+                          actionCallback: async (treeItem: ITreeItem) => {
+                            console.log(treeItem);
+                          }
+                        }]
+                      }
+                    ]
+                  },
+                  {
+                    key: "4",
+                    label: "Child 2",
+                    iconProps: skypeCheckIcon
+                  }
+                ]
+              },
+              {
+                key: "2",
+                label: "Parent 2"
+              },
+              {
+                key: "5",
+                label: "Parent 3",
+                disabled: true
+              },
+              {
+                key: "6",
+                label: "Parent 4",
+                selectable: true
+              }
+            ]
+          },
+          {
+            key: "R2",
+            label: "Root 2",
+            children: [
+              {
+                key: "8",
+                label: "Parent 5"
+              }
+            ]
+          }
+        ]
+```
+`IconpProps` in above example can be declared as below
+
+```typescript
+private skypeCheckIcon: IIconProps = { iconName: 'SkypeCheck' };
+```
+
+

docs/documentation/docs/assets/TreeView-control.gif

@@ -67,6 +67,7 @@ The following controls are currently available:
 - [SiteBreadcrumb](./controls/SiteBreadcrumb) (Breadcrumb control)
 - [SecurityTrimmedControl](./controls/SecurityTrimmedControl) (intended to be used when you want to show or hide components based on the user permissions)
 - [TaxonomyPicker](./controls/TaxonomyPicker) (Taxonomy Picker)
+- [TreeView](./controls/TreeView) (Tree View)
 - [WebPartTitle](./controls/WebPartTitle) (Customizable web part title control)
 
 

docs/documentation/docs/assets/TreeView-without-checkbox-selection-mode.png

@@ -35,7 +35,8 @@ nav:
     - RichText: 'controls/RichText.md'
     - SiteBreadcrumb: 'controls/SiteBreadcrumb.md'
     - SecurityTrimmedControl: 'controls/SecurityTrimmedControl.md'
-    - TaxonomyPicker: 'controls/TaxonomyPicker.md'
+    - TaxonomyPicker: 'controls/TaxonomyPicker.md',
+    - TreeView: 'controls/TreeView.md',
     - WebPartTitle: 'controls/WebPartTitle.md'
   - 'Field Controls':
     - 'Getting started': 'controls/fields/main.md'

docs/documentation/docs/assets/TreeView-without-checkbox.png

@@ -0,0 +1 @@
+export * from './controls/treeView/index';

docs/documentation/docs/controls/TreeView.md

@@ -0,0 +1,104 @@
+import * as React from 'react';
+import { CommandBarButton } from 'office-ui-fabric-react/lib/Button';
+import { IIconProps } from 'office-ui-fabric-react/lib/Icon';
+import { ITreeItemAction, IConcreteTreeItemActionProps } from './ITreeItemActions';
+import styles from './TreeView.module.scss';
+
+/**
+ * Renders the controls for Button TreeItem action component
+ */
+export default class ButtonTreeItemAction extends React.Component<IConcreteTreeItemActionProps> {
+
+  /**
+   * componentWillMount lifecycle hook
+   */
+  public componentWillMount(): void {
+    this.checkForImmediateInvocations();
+  }
+
+  /**
+   * Prepares the command bar button
+   */
+  private prepareCommandBarButton = (treeItemAction: ITreeItemAction): { name: string, text: string, iconProps: IIconProps, btnTitle: string } => {
+    let name: string = treeItemAction.title;
+    let text: string = treeItemAction.title;
+    let iconProps: IIconProps = treeItemAction.iconProps;
+    let btnTitle: string = treeItemAction.title;
+
+    return { name, text, iconProps, btnTitle };
+  }
+
+  /**
+   * Gets the action button styling
+   */
+  private getTreeItemActionButtonStyle = (treeItemAction: ITreeItemAction): React.CSSProperties => {
+    let result: React.CSSProperties = {
+      backgroundColor: "transparent",
+      height: "32px"
+    };
+
+    return result;
+  }
+
+  /**
+   * Check if there are action to immediatly invoke
+   */
+  private checkForImmediateInvocations() {
+    const { treeItemActions } = this.props;
+
+    for (const action of treeItemActions) {
+      if (action.invokeActionOnRender) {
+        this.onActionExecute(action);
+      }
+    }
+  }
+
+  /**
+   * On action execution
+   */
+  private onActionExecute = async (treeItemAction: ITreeItemAction) => {
+    await treeItemAction.actionCallback(this.props.treeItem);
+    this.props.treeItemActionCallback();
+  }
+
+  /**
+   * Default React render method
+   */
+  public render(): React.ReactElement<IConcreteTreeItemActionProps> {
+    const { treeItem, treeItemActions } = this.props;
+
+    // Check if there are actions to show
+    const actionsToShow = treeItemActions.filter(a => !a.hidden);
+    if (actionsToShow && actionsToShow.length === 0) {
+      return null;
+    }
+
+    return (
+      <div>
+        {
+          treeItemActions &&
+          treeItemActions.map(treeItemAction => {
+            const { name, text, iconProps, btnTitle } = this.prepareCommandBarButton(treeItemAction);
+
+            return (
+              treeItemAction.hidden ? (
+                null
+              ) : (
+                  <div>
+                    <CommandBarButton split={true}
+                      onClick={() => { this.onActionExecute(treeItemAction); }}
+                      iconProps={iconProps}
+                      text={text}
+                      title={btnTitle}
+                      name={name}
+                      key={treeItem.key}
+                      className={styles.actionButton} />
+                  </div>
+                )
+            );
+          })
+        }
+      </div>
+    );
+  }
+}