I am GuidoZam

Introduction

With this blog post I want to cover what the top actions are and how to use those in your solution.

The top actions of a web part are the commands available when you select a web part, to better understand what we are talking about, have a look at the following screenshot:

What you might not know is that it’s possible to add some customisation. The actual supported customisations are:

• a button.
• a drop down control.

In this sample I’ll be demonstrating how to use those two options.

Visual appearance

Starting with the visual appearance of the sample web part, this is how the web part renders in edit mode:

Let’s zoom a little bit more on the editing toolbar:

Aside of the default buttons, you can see that there is a separator and, on the right side of it, the custom controls:

• A like button, used to demonstrate how the control works. In this sample it will be a simple like/unlike button.
• A drop down control, used to specify the logging level for the web part.

After clicking on the like button, the icon will be updated:

Let me zoom in a little bit to better show you:

Now, let’s have a quick look at the drop down:

In the previous screenshot you can see that there are four different logging levels:

• Off: the logging is turned off and will not display anything in the browser console.
• Warning: the logging is turned on and will only display warnings in the browser console.
• Error: the logging is turned on and will only display errors in the browser console.
• Verbose: the logging is turned on and will display all the logging messages.

Show me the code

Now let’s cover the code to use the top actions.

Prerequisite

The first thing, in order to use the top actions, is to install the required package:

npm install @microsoft/sp-top-actions

Once added the package, it’s possible to import the required types in the web part component:

import {
  ITopActions,
  TopActionsFieldType
} from '@microsoft/sp-top-actions';

The types are used to define the required getTopActionsConfiguration method. The ITopActions is the return type of the new method, the other type is used to define the type of the action button, but we will cover that in a short while.

The method has the following structure:

public getTopActionsConfiguration = (): ITopActions | undefined => {
  return {
    topActions: [
      // list of actions
    ],
    onExecute(actionName, updatedValue) {
      // code to handle execution of action button
    },
  };
}

Top action structure

Before diving into the objects, let’s talk a little bit about the structure of the top actions.

All the objects used to define a top action must have the following properties:

• type: is the type of the control to be displayed. This is defined using the TopActionsFieldType. As of now, the supported types are:
  • Button
  • Dropdown
• targetProperty: this is the name of the top action.
• properties: the specific properties for the selected type. Each type has a different available set of properties.

There are also some common properties that are not required. Those properties are:

• title: the tooltip to be displayed for the control, this is also used as value for the arial-label property. 
• shouldFocus: it’s a flag to specify if the control should be focused or not.

Sample code

In the getTopActionsConfiguration, inside the topActions property, you can configure the buttons that you want to be displayed.

In the following snippet it’s defined the structure of the “Like” button:

{
  type: TopActionsFieldType.Button,
  title: strings.TopActions.ButtonTitle,
  targetProperty: "button",
  properties: {
    text: strings.TopActions.ButtonText,
    icon: properties.like === true ? "LikeSolid" : "Like",
  }
}

In the following one, instead of the previous one, it’s defined the dropdown top action:

{
  type: TopActionsFieldType.Dropdown,
  title: strings.TopActions.DropdownTitle,
  targetProperty: "dropdown",
  properties: {
    options: [
      {
        key: LoggingEnum.Off,
        text: strings.TopActions.DropdownOptionOff,
        checked: true
      },
      {
        key: LoggingEnum.Warning,
        text: strings.TopActions.DropdownOptionWarning,
      },
      {
        key: LoggingEnum.Error,
        text: strings.TopActions.DropdownOptionError,
      },
      {
        key: LoggingEnum.Verbose,
        text: strings.TopActions.DropdownOptionVerbose,
      },
    ],
  },
}

The question you should be asking now it’s: ok, but how do I handle the button clicks or the dropdown option selection?

This is achieved using the onExecute method inside the getTopActionsConfiguration method of the web part.

Here is a snippet of how the onExecute method can be defined:

onExecute(actionName, updatedValue) {
  switch (actionName) {
    case "button":
      properties.like = !properties.like;
      break;
    case "dropdown":
      properties.logging = updatedValue as LoggingEnum;
      break;
  }
}

The method is shared across all the top actions defined. The actionName argument contains the value of the targetProperty. The updatedValue will have different values based on the type of control:

• Button control: the updatedValue will be a boolean value set to true when the button is clicked.
• Dropdown control: contains the key value of the selected option.

Conclusions

If you’re interested in knowing more you can have a look at the official documentation here.

If you’re interested in having a look at the complete sample code you can find it here.

Top actions are an extremely useful addition to SharePoint Framework web parts, I think that many developers might be interested in using those controls and enabling different ways of interaction with the custom web parts.

Hope this helps!