Use the Dashboard from the PnP reusable controls

Proceeding with the appointments with the PnP React controls today I want to talk about the Dashboard control.

If you’re interested you can find the code of this sample here.

The Dashboard control is used to create a structure to display custom contents, the dashboard can contains multiple widgets and for each widget is possible to define a custom content, for example here you can see a dashboard composed of three different widgets:

In this sample the first widget (I know, I still have no imagination ) contains three different tabs, each one with a specific content.

The second widget contains a sample HTML table and display custom callout items such as Add or Edit options that in this sample shows only an alert message to signal the triggering of the selected option.

The third widget contains just some basic HTML content but shows a customizable link at the bottom.

The code

To use the PnP React controls first you need to install the package:

npm install @pnp/spfx-controls-react --save --save-exact

After the installation of the package you can proceed with the following instructions for the Dashboard control.

You can import the Dashboard control as following:

import { WidgetSize, IWidget, Dashboard } from '@pnp/spfx-controls-react/lib/Dashboard'; 

In the import there are also specified the WidgetSize and IWidget types, those are used to define the size of the widget and the interface used to define the return type of some methods that we’ll see shortly.

The Dashboard control has a widgets property which is an array of IWidget that let you define the content of the dashboard:

<Dashboard
  widgets={[
    this._getFirstWidget(),
    this._getSecondWidget(),
    this._getThirdWidget()
  ]}
/>

In the sample I defined three methods and each one returns a single widget, in the details we have the first widget:

private _getFirstWidget(): IWidget {
  return {
    title: strings.FirstWidget.Title,
    desc: strings.FirstWidget.Description,
    size: WidgetSize.Triple,
    body: [{
      id: "principalTab",
      title: strings.FirstWidget.PrincipalTab,
      content: (<Text>
        {strings.FirstWidget.PrincipalTabContent}
      </Text>),
     },{
      id: "secondaryTab",
      title: strings.FirstWidget.SecondaryTab,
      content: (<Text>
        {strings.FirstWidget.SecondaryTabContent}
       </Text>),
     },{
      id: "lastTab",
      title: strings.FirstWidget.LastTab,
      content: (<Text>
        {strings.FirstWidget.LastTabContent}
      </Text>),
     }]
  };
}

The body property of the widget enable the definition of the tabs that can be displayed and for each of those it’s possible to specify the id, title and the content of the tab.

The second widget contains the sample table, but the interesting part is the widgetActionGroup property which enable the definition of the possible actions/options for the widget.

private _getSecondWidget(): IWidget {
    return {
      title: strings.SecondWidget.Title,
      size: WidgetSize.Single,
      widgetActionGroup: this.calloutItemsExample,
      body: [
        {
          id: "content",
          title: strings.SecondWidget.ContentTitle,
          content: this._getSampleTable()
        }
      ]
    };
  }

The definition of the calloutItemsExample property is the following:

calloutItemsExample = [
    {
      id: "action_add",
      title: "Add",
      icon: <Icon iconName={'Add'} />,
      onClick: () => {
        alert("Add clicked");
      }
    },
    {
      id: "action_edit",
      title: "Edit",
      icon: <Icon iconName={'Edit'} />,
      onClick: () => {
        alert("Edit clicked");
      }
    }
  ];

For each object defined in the array you’ll have an option in the widget action group. Each of the objects have the option to define a custom icon and an action to be executed when the icon is clicked.

The last widget is to demonstrate the use of the link button in the bottom part of the widget:

 private _getThirdWidget(): IWidget {
    return {
      title: strings.ThirdWidget.Title,
      size: WidgetSize.Double,
      link: this.linkExample,
      body: [
        {
          id: "content",
          title: "Content",
          content: (
            <div>
              <h2>{strings.ThirdWidget.ContentTitle}</h2>
              <p>{strings.ThirdWidget.Description}</p>
            </div>
          ),
        }
      ]
    };
  }

The link property is a simple object with a href property used to specify the target URL, in the sample I defined the linkExample property in this way:

linkExample = { href: "https://iamguidozam.blog/" };

One last thing about the widgets is that, for each of the widgets, you can define the size using the size property which accept an WidgetSize value with one of the following values:

• Single
• Double
• Triple
• Box

The first three possible values define the width of the widget as the name says, so the single is a single sized grid item, the double a double sized and the triple a triple sized item. The one that is a little different is the Box value which define an item with double width and double height.

Conclusion

The Dashboard control is a very useful one when it comes to define the structure of a page without the hassle of constructing the whole structure.

Hope this help!