|
| 1 | +# Dashboard control |
| 2 | + |
| 3 | +Dashboard component for Microsoft Teams. |
| 4 | + |
| 5 | +!!! Note |
| 6 | + As this component is based on `@fluentui/react-northstar` the main usage scenario is Microsoft Teams projects. You can still use it in non-Teams related projects as well. |
| 7 | + |
| 8 | +Here is an example of the control in action: |
| 9 | + |
| 10 | + |
| 11 | + |
| 12 | +## How to use this control in your solutions |
| 13 | + |
| 14 | +- 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. |
| 15 | +- Import the following modules to your component: |
| 16 | + |
| 17 | +```TypeScript |
| 18 | +import { WidgetSize, Dashboard } from '@pnp/spfx-controls-react/lib/Dashboard'; |
| 19 | +``` |
| 20 | + |
| 21 | +- Use the `Dashboard` control in your code as follows: |
| 22 | + |
| 23 | +```TypeSCript |
| 24 | +const linkExample = { href: "#" }; |
| 25 | +const calloutItemsExample = [ |
| 26 | + { |
| 27 | + id: "action_1", |
| 28 | + title: "Info", |
| 29 | + icon: <Icon iconName={'Edit'} />, |
| 30 | + }, |
| 31 | + { id: "action_2", title: "Popup", icon: <Icon iconName={'Add'} /> }, |
| 32 | +]; |
| 33 | +// ... |
| 34 | +<Dashboard |
| 35 | + widgets={[{ |
| 36 | + title: "Card 1", |
| 37 | + desc: "Last updated Monday, April 4 at 11:15 AM (PT)", |
| 38 | + widgetActionGroup: calloutItemsExample, |
| 39 | + size: WidgetSize.Triple, |
| 40 | + body: [ |
| 41 | + { |
| 42 | + id: "t1", |
| 43 | + title: "Tab 1", |
| 44 | + content: ( |
| 45 | + <Text> |
| 46 | + Content #1 |
| 47 | + </Text> |
| 48 | + ), |
| 49 | + }, |
| 50 | + { |
| 51 | + id: "t2", |
| 52 | + title: "Tab 2", |
| 53 | + content: ( |
| 54 | + <Text> |
| 55 | + Content #2 |
| 56 | + </Text> |
| 57 | + ), |
| 58 | + }, |
| 59 | + { |
| 60 | + id: "t3", |
| 61 | + title: "Tab 3", |
| 62 | + content: ( |
| 63 | + <Text> |
| 64 | + Content #3 |
| 65 | + </Text> |
| 66 | + ), |
| 67 | + }, |
| 68 | + ], |
| 69 | + link: linkExample, |
| 70 | + }, |
| 71 | + { |
| 72 | + title: "Card 2", |
| 73 | + size: WidgetSize.Single, |
| 74 | + link: linkExample, |
| 75 | + }, |
| 76 | + { |
| 77 | + title: "Card 3", |
| 78 | + size: WidgetSize.Double, |
| 79 | + link: linkExample, |
| 80 | + }]} /> |
| 81 | +``` |
| 82 | + |
| 83 | +## Implementation |
| 84 | + |
| 85 | +The Dashboard component can be configured with the following properties: |
| 86 | + |
| 87 | +| Property | Type | Required | Description | |
| 88 | +| ---- | ---- | ---- | ---- | |
| 89 | +| widgets | IWidget[] | yes | Widgtets collection. | |
| 90 | +| allowHidingWidget | boolean | no | Specifies if widgets can be hidden from the dashboard. | |
| 91 | +| onWidgetHiding | (widget: IWidget) => void | no | Handler of widget hiding event. | |
| 92 | +| toolbarProps | IToolbarProps | no | Dashboard toolbar props. See [Toolbar](./Toolbar). | |
| 93 | + |
| 94 | +Interface `IWidget` |
| 95 | + |
| 96 | +Provides settings of Dashboard's widget |
| 97 | + |
| 98 | +| Property | Type | Required | Description | |
| 99 | +| ---- | ---- | ---- | ---- | |
| 100 | +| size | WidgetSize | yes | Size. | |
| 101 | +| title | string | yes | Title. | |
| 102 | +| desc | string | no | Description. | |
| 103 | +| widgetActionGroup | IWidgetActionKey[] | no | Actions. | |
| 104 | +| controlOptions | IWidgetControlOptions | no | Component rendering options. | |
| 105 | +| body | IWidgetBodyContent[] | no | Widget's content (children) rendered as tabs. | |
| 106 | +| link | IWidgetLink | no | Widget's link rendered at the bottom part of the widget. | |
| 107 | + |
| 108 | +Interface `IWidgetActionKey` |
| 109 | + |
| 110 | +Provides Dashboard Widget Action properties |
| 111 | + |
| 112 | +| Property | Type | Required | Description | |
| 113 | +| ---- | ---- | ---- | ---- | |
| 114 | +| id | string | yes | Action id. | |
| 115 | +| icon | JSX.Element | no | Action icon. | |
| 116 | +| title | string | yes | Action title. | |
| 117 | +| onClick | () => void | no | Action handler. | |
| 118 | + |
| 119 | +Interface `IWidgetControlOptions` |
| 120 | + |
| 121 | +Provides Widget component options |
| 122 | + |
| 123 | +| Property | Type | Required | Description | |
| 124 | +| ---- | ---- | ---- | ---- | |
| 125 | +| isHidden | boolean | no | Specifies if current widget is hidden. | |
| 126 | + |
| 127 | +Interface `IWidgetBodyContent` |
| 128 | + |
| 129 | +Provides Widget content (tab) properties |
| 130 | + |
| 131 | +| Property | Type | Required | Description | |
| 132 | +| ---- | ---- | ---- | ---- | |
| 133 | +| id | string | yes | Content (tab) id. | |
| 134 | +| title | string | yes | Content (tab) title. | |
| 135 | +| content | React.ReactNode | yes | Tab content. | |
| 136 | + |
| 137 | +Interface `IWidgetLink` |
| 138 | + |
| 139 | +Provides Widget link properties |
| 140 | + |
| 141 | +| Property | Type | Required | Description | |
| 142 | +| ---- | ---- | ---- | ---- | |
| 143 | +| href | string | yes | Link to be opened. | |
| 144 | + |
| 145 | +Enum `WidgetSize` |
| 146 | + |
| 147 | +Provides size of the widget |
| 148 | + |
| 149 | +| Value | Description | |
| 150 | +| ---- | ---- | |
| 151 | +| Single | Single-sized grid item. | |
| 152 | +| Double | Double-width grid item. | |
| 153 | +| Triple | Triple width grid item. | |
| 154 | +| Box | Double-width, double-height grid item. | |
| 155 | + |
| 156 | + |
0 commit comments