Skip to content

Commit 69234e9

Browse files
andrewconnellandrewconnell
committed
📜♻️ update spfx topactions doc
- matches SPFx v1.17 released API - closes SharePoint#8877
1 parent 48c5cc2 commit 69234e9

File tree

2 files changed

+121
-101
lines changed

2 files changed

+121
-101
lines changed

‎docs/images/webpart-top-actions.png

5.39 KB
Loading

‎docs/spfx/web-parts/guidance/getting-started-with-top-actions.md

Lines changed: 121 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,163 +1,183 @@
11
---
22
title: Adding support for web part Top Actions
3-
description: Top Actions is a SharePoint Framework feature that allows web part developers to add commands to a web part's toolbar
4-
ms.date: 04/04/2023
3+
description: Top Actions is a SharePoint Framework feature that allows web part developers to add commands to a web part's toolbar.
4+
ms.date: 04/12/2023
55
ms.localizationpriority: high
66
---
7-
87
# Adding support for web part Top Actions
98

10-
Top actions provide an alternative and more end user friendlier way to expose the different options and configuration capabilities for web parts in edit mode. You can use top actions to surface most common configurations from the web part property panel directly in web part toolbar, which is exposed when the page is edited.
9+
Top Actions provide an alternative and more end user friendlier way to expose the different options and configuration capabilities for web parts in edit mode. You can use Top Actions to surface most common configurations from the web part property panel directly in web part toolbar, which is exposed when the page is in edit mode.
1110

1211
![Top Actions Example](../../../images/webpart-top-actions.png)
1312

13+
> [!IMPORTANT]
14+
> Web part Top Actions were introduced in the [SharePoint Framework (SPFx) v1.17 release](../../release-1.17.md).
15+
1416
## Getting started
1517

18+
To add Top Actions to a web part, you'll implement two things:
19+
20+
- return a collection of Top Actions to display at the top of the web part when the page is in edit mode
21+
- implement a handler that's called by SPFx when the Top Action is selected
22+
23+
Both of these steps are accomplished by providing a configuration object of type [ITopActions](/javascript/api/sp-top-actions/itopactions) to the SPFx.
24+
1625
> [!TIP]
1726
> These instructions assume you know [how to create a hello world web part](../get-started/build-a-hello-world-web-part.md).
1827
19-
### Define your Top Action configurations
28+
## Define a Top Action configuration
2029

21-
The example below defines the callback function that will be used to pull the configurations for our Top Action commands.
30+
Adding Top Actions to a web part follows a similar pattern to configuring the web part property pane.
2231

23-
> [!NOTE]
24-
> `getTopActionsConfiguration` must be defined as public on your web part's class.
32+
To add Top Actions to a web part, implement the `getTopActionsConfiguration()` member that returns an object of type ITopActions:
2533

2634
```typescript
27-
import { ITopActions } from '@microsoft/sp-top-actions';
35+
// existing imports omitted for brevity
36+
import {
37+
ITopActions,
38+
ITopActionsField
39+
} from '@microsoft/sp-top-actions';
40+
41+
export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
42+
43+
// existing web part members omitted for brevity
44+
45+
public getTopActionsConfiguration(): ITopActions | undefined {
46+
return {
47+
topActions: [],
48+
onExecute: (actionName: string, newValue: any): void { }
49+
};
50+
}
2851

29-
public getTopActionsConfiguration(): ITopActions | undefined {
30-
return {
31-
topActions: [],
32-
onExecute: (actionName: string, newValue: any) => {}
33-
};
3452
}
3553
```
3654

37-
### Define your toolbar's user interface
55+
Notice the returned object has two properties:
56+
57+
- `topActions`: this contains an array of supported Top Action controls that are rendered in the web part's toolbar when the page is in edit mode
58+
- `onExecute`: this handler is called when one of the Top Actions is selected
3859

39-
The `topActions` array is an ordered list of controls to render in the web part toolbar. The example below defines one top action as a button interface.
60+
## Define the Top Actions user interface
61+
62+
The `topActions` array is an ordered list of controls, or *fields* of type [ITopActionsField](/javascript/api/sp-top-actions/itopactionsfield), to render in the web part toolbar. You can choose from two types of user interface elements:
63+
64+
- button
65+
- dropdown list
66+
67+
All controls must have the following properties defined:
68+
69+
- `type`: this is the type of the control - *button* (`TopActionsFieldType.Button`) or *dropdown list* (`TopActionsFieldType.Dropdown)
70+
- `targetProperty`: this is the name of the Top Action
71+
- `properties`: properties unique to the type of Top Action control
72+
73+
You can optionally specify a `title` which is used as the tooltip & value for an `aria-label` property, and the Boolean `shouldFocus` flag to indicate if the control should be focused.
74+
75+
## Define the Top Actions button field
76+
77+
The following code defines a button Top Action control:
4078

4179
```typescript
42-
import { ITopActions, TopActionsFieldType } from '@microsoft/sp-top-actions';
80+
import {
81+
ITopActions,
82+
TopActionsFieldType
83+
} from '@microsoft/sp-top-actions';
4384

4485
return {
4586
topActions: [
4687
{
47-
targetProperty: 'reset',
88+
targetProperty: 'button',
89+
type: TopActionsFieldType.Button,
90+
title: 'Button',
4891
properties: {
49-
icon: 'Reset'
50-
},
51-
type: TopActionsFieldType.Button
92+
text: 'Button',
93+
icon: 'SharePointLogo'
94+
}
5295
}
53-
]
54-
...
96+
],
97+
onExecute: (actionName: string, newValue: any): void { }
5598
}
5699
```
57100

58-
### Execute the command when the user interacts
101+
The `properties` for a button control are defined in the [ITopActionsButtonProps](/javascript/api/sp-top-actions/itopactionsbuttonprops) interface.
102+
103+
## Define the Top Actions dropdown field
59104

60-
The previous step demonstrated how to get a button to display in the web part's toolbar. This step shows how to perform an action when the user selects the button. `actionName` was defined as `targetProperty` in the last step and since this is a button that can ignore the `newValue` that comes in.
105+
The following code defines a dropdown Top Action control:
61106

62107
```typescript
108+
import {
109+
ITopActions,
110+
TopActionsFieldType
111+
} from '@microsoft/sp-top-actions';
112+
63113
return {
64-
...
65-
onExecute: (actionName: string, newValue: any) => {
66-
if (actionName === 'reset') {
67-
// user defined logic to reset the web part
68-
this.reset();
114+
topActions: [
115+
{
116+
targetProperty: 'dropdown',
117+
type: TopActionsFieldType.Dropdown,
118+
title: 'Dropdown',
119+
properties: {
120+
options: [{
121+
key: '1',
122+
text: 'Option 1'
123+
}, {
124+
key: '2',
125+
text: 'Option 2'
126+
}]
127+
}
69128
}
70-
}
129+
],
130+
onExecute: (actionName: string, newValue: any): void { }
71131
}
72132
```
73133

74-
> [!TIP]
75-
> Common pitfall when implementing the `onExecute` command, is not syncing the new state with the web part properties and/or not refreshing or re-rendering the web part.
134+
The `properties` for a dropdown control are defined in the [ITopActionsButtonProps](/javascript/api/sp-top-actions/itopactionsdropdownoption) interface.
76135

77-
## Code Snippets
136+
## Define the handler when controls are selected
78137

79-
### Button command
138+
The last step is to implement the handler when Top Action controls are selected. This is done by implementing the `onExecute()` method on the ITopActions interface.
80139

81-
The type interface for a button is similar to the property panel's button (`IPropertyPaneButtonProps`).
140+
The `onExecute()` handler passes two arguments in that you can handle:
82141

83-
```typescript
84-
import { ITopActions, TopActionsFieldType } from '@microsoft/sp-top-actions';
85-
...
86-
public getTopActionsConfiguration(): ITopActions | undefined {
87-
return {
88-
topActions: [
89-
{
90-
targetProperty: 'reset',
91-
type: TopActionsFieldType.Button,
92-
properties: {
93-
text: 'Reset',
94-
icon: 'Reset'
95-
}
96-
}
97-
],
98-
onExecute: (actionName: string, newValue: any) => {
99-
if (actionName === 'reset') {
100-
// user defined logic to reset the web part
101-
this.reset();
102-
}
103-
}
104-
};
105-
}
106-
```
107-
108-
### Drop-down command
109-
110-
The type interface for a drop-down is similar to the property panel's choice group (`IPropertyPaneChoiceGroupOption`).
142+
- `actionName`: maps to the `targetProperty` of the Top Action control that triggered this handler to be called
143+
- `updatedValue`: when the Top Action is of type dropdown, this is the `key` property of the selected dropdown option; otherwise when the Top Action is of type button, the value of this property is `true`
111144

112145
```typescript
113-
import { ITopActions, TopActionsFieldType } from '@microsoft/sp-top-actions';
114-
...
115146
public getTopActionsConfiguration(): ITopActions | undefined {
116147
return {
117148
topActions: [{
118-
targetProperty: 'layout',
119-
type: TopActionsFieldType.ChoiceGroup,
149+
type: TopActionsFieldType.Button,
150+
title: 'Button',
151+
targetProperty: 'button',
120152
properties: {
121-
options: [
122-
{
123-
// key maps to newValue in onExecute
124-
key: 'card',
125-
text: 'Card Layout',
126-
imageSize: { width: 32, height: 32 },
127-
iconProps: { officeFabricIconFontName: 'ArticlesIcon' },
128-
checked: this.state.layout === 'card'
129-
},
130-
{
131-
key: 'list',
132-
text: 'List Layout',
133-
imageSize: { width: 32, height: 32 },
134-
// you can use iconProps, icon to define icons
135-
icon: 'List',
136-
checked: this.state.alignment === 'list'
137-
}
138-
]
153+
text: 'Button',
154+
icon: 'SharePointLogo'
139155
}
140-
}],
141-
// for ChoiceGroup drop-down, the newValue tells us which option's key was selected
142-
onExecute: (actionName: string, newValue: any) => {
143-
if (actionName === 'layout') {
144-
this.setLayout(newValue);
145-
this.render();
156+
}, {
157+
type: TopActionsFieldType.Dropdown,
158+
title: 'Dropdown',
159+
targetProperty: 'dropdown',
160+
properties: {
161+
options: [{
162+
key: '1',
163+
text: 'Option 1'
164+
}, {
165+
key: '2',
166+
text: 'Option 2'
167+
}]
146168
}
169+
}],
170+
onExecute(actionName, updatedValue) {
171+
console.log('onExecute', actionName, updatedValue);
147172
}
148-
};
173+
}
149174
}
150175
```
151176

152-
## Advanced configurations
153-
154-
For advanced configurations of your top action commands, see the type definitions from `@microsoft/sp-top-actions`.
155-
177+
## Testing & debugging Top Actions
156178

157-
```typescript
158-
import { ITopActions, ITopActionsButtonProps, ITopActionsDropdownProps } from '@microsoft/sp-top-actions';
159-
```
179+
Similar to the different types of SPFx extensions, Top Actions must be tested in a live SharePoint modern page. They won't render on the SharePoint hosted workbench.
160180

161181
### See more
162182

163-
[Top Actions API](/javascript/api/sp-top-actions)
183+
- [Top Actions API](/javascript/api/sp-top-actions)

0 commit comments

Comments
 (0)