From f306d04b5133cd383a432af01d02d5143fd5064f Mon Sep 17 00:00:00 2001 From: Jay Harris Date: Mon, 14 Nov 2022 08:55:55 -0500 Subject: [PATCH 1/7] Adds top actions documentation --- .../getting-started-with-top-actions.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/spfx/web-parts/guidance/getting-started-with-top-actions.md diff --git a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md new file mode 100644 index 000000000..01b96c238 --- /dev/null +++ b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md @@ -0,0 +1,151 @@ +--- +title: Adding support for Top Actions +description: Top Actions is a SharePoint Framework feature that allows web part developers to add commands to a web part's toolbar +ms.date: 11/15/2022 +--- + +# Adding support for Top Actions + +Today, users need to be aware of the web part property panels to find out the additional options each web part provides. This is a common piece of feedback where users want actions surfacing in context of where they are without having to rely on opening something to get to those options. Therefore, we are now surfacing most common configurations from a web part's property panel directly on to the web part's toolbar. These common configurations are referred to as the web part's Top Actions. + + +> At the time of writing this article, Top Actions only supports rendering a drop down and button command. + +## Getting started + +> [!TIP] +> These instructions assume you know [how to create a hello world web part](../get-started/build-a-hello-world-web-part.md). + +### 1. Define your Top Action configurations + +In the example below we are defining the callback function that will be used to pull the configurations for our Top Action commands. + +> Note: `getTopActionsConfiguration` must be defined as public on your web part's class. + +```typescript +import { ITopActions } from '@microsoft/sp-top-actions'; + +public getTopActionsConfiguration(): ITopActions | undefined { + return { + topActions: [], + onExecute: (actionName: string, newValue: any) => {} + }; +} +``` + +### 3. Define your toolbar's user interface + +The `topActions` array is an ordered list of controls to render in the web part toolbar. In the example below we are defining one top action as a button interface. + +```typescript +import { PropertyPaneFieldType } from '@microsoft/sp-property-pane'; + +return { + topActions: [ + { + targetProperty: 'reset', + properties: { + icon: 'Reset' + }, + type: PropertyPaneFieldType.Button + } + ] + ... +} +``` + +### 4. Execute the command when the user interacts +The previous step demonstrated how to get a button to display in the web part's toolbar. Now we will perform an action when the user clicks the button. Note that `actionName` was defined as `targetProperty` in the last step and since this is a button we can ignore the `newValue` that comes in. + +```typescript +return { + ... + onExecute: (actionName: string, newValue: any) => { + if (actionName === 'reset') { + // user defined logic to reset the web part + this.reset(); + } + } +} +``` +> Common pitfalls 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. + +## Code Snippets +### Button command +The type interace for a button is similar to the property panel's button (`IPropertyPaneButtonProps`). + +```typescript +import { ITopActions } from '@microsoft/sp-top-actions'; +import { PropertyPaneFieldType } from '@microsoft/sp-property-pane'; +... +public getTopActionsConfiguration(): ITopActions | undefined { + return { + topActions: [ + { + targetProperty: 'reset', + type: PropertyPaneFieldType.Button, + properties: { + icon: 'Reset' + } + } + ], + onExecute: (actionName: string, newValue: any) => { + if (actionName === 'reset') { + // user defined logic to reset the web part + this.reset(); + } + } + }; +} +``` + +### Drop down command +The type interace for a drop down is similar to the property panel's choice group (`IPropertyPaneChoiceGroupOption`). + +```typescript +import { ITopActions } from '@microsoft/sp-top-actions'; +import { PropertyPaneFieldType } from '@microsoft/sp-property-pane'; +... +public getTopActionsConfiguration(): ITopActions | undefined { + return { + topActions: [{ + targetProperty: 'layout', + type: PropertyPaneFieldType.ChoiceGroup, + properties: { + options: [ + { + // key maps to newValue in onExecute + key: 'card', + text: 'Card Layout', + imageSize: { width: 32, height: 32 }, + iconProps: { officeFabricIconFontName: 'ArticlesIcon' }, + checked: this.state.layout === 'card' + }, + { + key: 'list', + text: 'List Layout', + imageSize: { width: 32, height: 32 }, + // you can use iconProps, icon to define icons + icon: 'List', + checked: this.state.alignment === 'list' + } + ] + } + }], + // for ChoiceGroup drop down, the newValue tells us which option's key was selected + onExecute: (actionName: string, newValue: any) => { + if (actionName === 'layout') { + this.setLayout(newValue); + this.render(); + } + } + }; +} +``` + +## Advanced configurations +For advanced configurations of your top action commands, checkout the type definitions from `@microsoft/sp-property-pane`. Currently, the two supported topActions, button and drop down, can be defined using the same structure as `IPropertyPaneChoiceGroupOption` and `IPropertyPaneButtonProps`. From here you can see how to use features like icons, aria labels, disable state, and more. + +```typescript +import { IPropertyPaneButtonProps, IPropertyPaneChoiceGroupOption } from '@microsoft/sp-property-pane' +``` From eb2efc9c64eb37446c9c6802c07055157688763e Mon Sep 17 00:00:00 2001 From: Jay Harris Date: Mon, 14 Nov 2022 08:59:26 -0500 Subject: [PATCH 2/7] Changes date --- .../spfx/web-parts/guidance/getting-started-with-top-actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md index 01b96c238..41fd99bed 100644 --- a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md +++ b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md @@ -1,7 +1,7 @@ --- title: Adding support for Top Actions description: Top Actions is a SharePoint Framework feature that allows web part developers to add commands to a web part's toolbar -ms.date: 11/15/2022 +ms.date: 11/14/2022 --- # Adding support for Top Actions From 50860f1db113317777c216fe5cd116f11335ed71 Mon Sep 17 00:00:00 2001 From: jayharris-ms <118180799+jayharris-ms@users.noreply.github.com> Date: Mon, 14 Nov 2022 10:16:06 -0500 Subject: [PATCH 3/7] Update docs/spfx/web-parts/guidance/getting-started-with-top-actions.md Co-authored-by: Alex Terentiev --- .../spfx/web-parts/guidance/getting-started-with-top-actions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md index 41fd99bed..6b86dfe48 100644 --- a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md +++ b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md @@ -8,6 +8,8 @@ ms.date: 11/14/2022 Today, users need to be aware of the web part property panels to find out the additional options each web part provides. This is a common piece of feedback where users want actions surfacing in context of where they are without having to rely on opening something to get to those options. Therefore, we are now surfacing most common configurations from a web part's property panel directly on to the web part's toolbar. These common configurations are referred to as the web part's Top Actions. +> [!IMPORTANT] +> This feature is still preview status as part of the 1.16 release and should not be used in production. We are looking into releasing them officially as part of the upcoming 1.17 release. > At the time of writing this article, Top Actions only supports rendering a drop down and button command. From ad8547861dda30e5453f67c72c568b85fdae33eb Mon Sep 17 00:00:00 2001 From: jayharris-ms <118180799+jayharris-ms@users.noreply.github.com> Date: Mon, 14 Nov 2022 10:16:14 -0500 Subject: [PATCH 4/7] Update docs/spfx/web-parts/guidance/getting-started-with-top-actions.md Co-authored-by: Alex Terentiev --- .../spfx/web-parts/guidance/getting-started-with-top-actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md index 6b86dfe48..80b99783c 100644 --- a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md +++ b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md @@ -6,7 +6,7 @@ ms.date: 11/14/2022 # Adding support for Top Actions -Today, users need to be aware of the web part property panels to find out the additional options each web part provides. This is a common piece of feedback where users want actions surfacing in context of where they are without having to rely on opening something to get to those options. Therefore, we are now surfacing most common configurations from a web part's property panel directly on to the web part's toolbar. These common configurations are referred to as the web part's Top Actions. +Today, users need to be aware of the web part property panels to find out the additional options each web part provides. This is a common piece of feedback where users want actions surfacing in context of where they are without having to rely on opening something to get to those options. Therefore, we are now allowing to surface most common configurations from a web part's property panel directly on to the web part's toolbar. These common configurations are referred to as the web part's Top Actions. > [!IMPORTANT] > This feature is still preview status as part of the 1.16 release and should not be used in production. We are looking into releasing them officially as part of the upcoming 1.17 release. From 5910ebe11856e5d7c96de0af9d9a1f08e61bf58d Mon Sep 17 00:00:00 2001 From: Jay Harris Date: Mon, 14 Nov 2022 11:03:51 -0500 Subject: [PATCH 5/7] PR comment --- .../guidance/getting-started-with-top-actions.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md index 80b99783c..9f22f0d0a 100644 --- a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md +++ b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md @@ -146,8 +146,22 @@ public getTopActionsConfiguration(): ITopActions | undefined { ``` ## Advanced configurations -For advanced configurations of your top action commands, checkout the type definitions from `@microsoft/sp-property-pane`. Currently, the two supported topActions, button and drop down, can be defined using the same structure as `IPropertyPaneChoiceGroupOption` and `IPropertyPaneButtonProps`. From here you can see how to use features like icons, aria labels, disable state, and more. +For advanced configurations of your top action commands, checkout the type definitions from `@microsoft/sp-property-pane` and `@microsoft/sp-top-actions`. Currently, the two supported top action commands, button and drop down, can be defined using a subset of the types `IPropertyPaneChoiceGroupOption` and `IPropertyPaneButtonProps`. From here you can see how to use features like icons, aria labels, disable state, and more. + +For `IPropertyPaneButtonProps`, currently supported properties are `icon`, `text`, `ariaLabel`, `disabled` + +For `IPropertyPaneChoiceGroupOption`, currently supported porperty is `options` and from that array we support `key`, `text`, `iconProps.officeFabricIconFontName`, `imageSize`, `checked`, `title` + +> [!WARNING] +> The APIs used for Top Actions are subject to change as the feature graduates to stable status. ```typescript import { IPropertyPaneButtonProps, IPropertyPaneChoiceGroupOption } from '@microsoft/sp-property-pane' +import { ITopActions } from '@microsoft/sp-top-actions'; ``` +### See more +[Top Actions API](/javascript/api/sp-top-actions) + +[IPropertyPaneButtonProps](/javascript/api/sp-webpart-base/ipropertypanebuttonprops) + +[IPropertyPaneChoiceGroupOption](/javascript/api/sp-webpart-base/ipropertypanechoicegroupoption) \ No newline at end of file From aa1b664a433a8a88d52004a042df7646f3a8fef1 Mon Sep 17 00:00:00 2001 From: Jay Harris Date: Mon, 14 Nov 2022 11:10:24 -0500 Subject: [PATCH 6/7] Adds example --- .../web-parts/guidance/getting-started-with-top-actions.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md index 9f22f0d0a..1b1c33c97 100644 --- a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md +++ b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md @@ -13,6 +13,9 @@ Today, users need to be aware of the web part property panels to find out the ad > At the time of writing this article, Top Actions only supports rendering a drop down and button command. + +![Top Actions Example](../../../images/webpart-top-actions.png) + ## Getting started > [!TIP] From 95f30309427b821eebb881e77a61d6849a1ba090 Mon Sep 17 00:00:00 2001 From: Jay Harris Date: Mon, 14 Nov 2022 11:13:23 -0500 Subject: [PATCH 7/7] misc changes --- .../web-parts/guidance/getting-started-with-top-actions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md index 1b1c33c97..2b7dc8485 100644 --- a/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md +++ b/docs/spfx/web-parts/guidance/getting-started-with-top-actions.md @@ -149,11 +149,11 @@ public getTopActionsConfiguration(): ITopActions | undefined { ``` ## Advanced configurations -For advanced configurations of your top action commands, checkout the type definitions from `@microsoft/sp-property-pane` and `@microsoft/sp-top-actions`. Currently, the two supported top action commands, button and drop down, can be defined using a subset of the types `IPropertyPaneChoiceGroupOption` and `IPropertyPaneButtonProps`. From here you can see how to use features like icons, aria labels, disable state, and more. +For advanced configurations of your top action commands, checkout the type definitions from `@microsoft/sp-property-pane` and `@microsoft/sp-top-actions`. Currently, the two supported top action commands, button and drop down, can be defined using a subset of the types `IPropertyPaneChoiceGroupOption` and `IPropertyPaneButtonProps`. -For `IPropertyPaneButtonProps`, currently supported properties are `icon`, `text`, `ariaLabel`, `disabled` +For `IPropertyPaneButtonProps`, the currently supported properties are `icon`, `text`, `ariaLabel`, `disabled` -For `IPropertyPaneChoiceGroupOption`, currently supported porperty is `options` and from that array we support `key`, `text`, `iconProps.officeFabricIconFontName`, `imageSize`, `checked`, `title` +For `IPropertyPaneChoiceGroupOption`, the currently supported porperty is `options` and from that array we support `key`, `text`, `iconProps.officeFabricIconFontName`, `imageSize`, `checked`, `title` > [!WARNING] > The APIs used for Top Actions are subject to change as the feature graduates to stable status.