Skip to content

TOC update to align with title update. #750

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 28, 2017
Merged

TOC update to align with title update. #750

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
943b57f
Edit pass.
Lauragra Jul 15, 2017
699f323
A few more edits.
Lauragra Jul 15, 2017
7bc6722
Fix TOC title to match updated topic title.
Lauragra Jul 27, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 51 additions & 49 deletions docs/spfx/extensions/guidance/using-custom-dialogs-with-spfx.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,29 @@
# Using Custom Dialogs with SharePoint Framework Extensions
# Use custom dialog boxes with SharePoint Framework Extensions

Custom dialogs are available from the **@microsoft/sp-dialog** package and can be used within the context of SharePoint Framework Extensions or client-side web parts.
You can use custom dialog boxes, available from the **@microsoft/sp-dialog** package, within the context of SharePoint Framework Extensions or client-side web parts.

This tutorial demonstrates the creation of a custom dialog and using it within the context of a ListView Command Set extension.
This article describes how to create a custom dialog box and use it within the context of a ListView Command Set extension.

> The SharePoint Framework dialog is currently in preview status and we are looking to collect feedback before it's officially released. Please provide feedback by using the [sp-dev-docs repository Issue list](https://github.com/SharePoint/sp-dev-docs/issues).
>**Note:** The custom dialog box feature is currently in preview. We are looking for your feedback before we release. To provide feedback, [file an issue in our GitHub repo](https://github.com/SharePoint/sp-dev-docs/issues).

> Please note that debugging Custom ListView Command Sets in SharePoint Online is currently only available from the modern list experience within classic team sites hosted in a **developer tenant**.

> The end result of this tutorial is available as source code at https://github.com/SharePoint/sp-dev-fx-extensions/tree/master/samples/react-command-dialog.

## Setup your Environment
You can access the sample code that this article is based on in the [](https://github.com/SharePoint/sp-dev-fx-extensions/tree/master/samples/react-command-dialog) repo.

Before you can complete this guide, you will need to ensure you have [setup your environment](https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment) for development
using the SharePoint Framework (SPFx) and that you are using the latest SharePoint Framework Yeoman templates.
## Set up your development environment

> You can update your SharePoint Framework Yeoman templates by running the following command:
> ```sh
> npm install -g @microsoft/generator-sharepoint`
> ```
To create a custom dialog box, you'll need to follow the steps in the [Set up your development environment](https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment). Make sure that you're using the latest SharePoint Framework Yeoman templates.

## Create a New Project
To update your SharePoint Framework Yeoman templates, run the following command:

Start by creating a new folder for the project using your console of choice:
```sh
npm install -g @microsoft/generator-sharepoint`
```

## Create a new project

Create a new folder for the project using your console of choice:

```sh
md dialog-cmd
Expand All @@ -34,7 +35,7 @@ Then enter that folder:
cd dialog-cmd
```

Then run the Yeoman generator for the SharePoint Framework:
Run the Yeoman generator for the SharePoint Framework:

```sh
yo @microsoft/sharepoint
Expand All @@ -59,17 +60,17 @@ When the scaffold is complete, you should see the following message indicating a

![SharePoint client-side solution scaffolded successfully](../../../../images/ext-com-dialog-yeoman-complete.png)

> For information about troubleshooting any errors, see [Known issues](../basics/known-issues).
>**Note:** For information about troubleshooting any errors, see [Known issues](../basics/known-issues).

Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots, but you can use any editor you prefer. To open the folder in Visual Studio Code use the following command in the console:
When the scaffolding is complete, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots, but you can use any editor you prefer. To open the folder in Visual Studio Code, use the following command in the console:

```sh
code .
```

![Initial Visual Studio Code structure after scaffolding](../../../../images/ext-com-dialog-vs-code-initial.png)

## Modify the Extension Manifest
## Modify the extension manifest

In the extension manifest, configure the extension to have only one button. In the code editor, open the **./src/extensions/dialogDemo/DialogDemoCommandSet.manifest.json** file. Replace the commands section with the following JSON:

Expand All @@ -85,24 +86,25 @@ In the extension manifest, configure the extension to have only one button. In t
}
```

## Adding the sp-dialog Package to the Solution
## Add the sp-dialog package to the solution

Return to the console and execute the following command to include the dialog API in your solution:
Return to the console and run the following command to include the dialog API in your solution:

```sh
npm install @microsoft/sp-dialog --save
```

Since we are using the `--save` option, this dependency will be added to the **package.json** file. This will ensure that it will be automatically installed when the `npm install` command is executed (this is important when restoring or cloning your project elsewhere).
Because you're using the `--save` option, this dependency will be added to the **package.json** file. This ensures that it will be installed automatically when the `npm install` command runs (this is important when you restore or clone your project elsewhere).

Return to Visual Studio Code (or your preferred editor).

## Creating a Custom Dialog
## Create a custom dialog box

Create a new file called **ColorPickerDialog.tsx** in the **./src/extensions/dialogDemo/** folder.

Add the following import statements at the top of the newly created file. We are creating our custom dialog using the [Office UI Fabric React components](https://dev.office.com/fabric#/components), so the implementation will be in React.
Add the following import statements at the top of the newly created file. You're creating your custom dialog box using the [Office UI Fabric React components](https://dev.office.com/fabric#/components), so the implementation will be in React.

> Currently the `DialogContent` component is coming from `@microsoft/sp-dialog`, but will be included as part of the Office UI Fabric React components soon, as mentioned in the code comments below.
> **Note:** Currently the `DialogContent` component is coming from `@microsoft/sp-dialog`, but it will be included as part of the Office UI Fabric React components soon.

```ts
import * as React from 'react';
Expand All @@ -121,7 +123,7 @@ import {
import { DialogContent } from '@microsoft/sp-dialog';
```

Add the following interface definition just below the import statements. This wil be used to pass information and functions between your ListView Command Set extension and your custom dialog.
Add the following interface definition just below the import statements. This will be used to pass information and functions between your ListView Command Set extension and your custom dialog box.

```ts
interface IColorPickerDialogContentProps {
Expand All @@ -132,7 +134,7 @@ interface IColorPickerDialogContentProps {
}
```

Add the following class just below the interface definition. This React class is responsible for rendering the UI experiences inside of the custom dialog. Notice that we use the Office UI Fabric React components for actual rendering and just pass the needed properties.
Add the following class just below the interface definition. This React class is responsible for rendering the UI experiences inside the custom dialog box. Notice that you use the Office UI Fabric React components for actual rendering and just pass the needed properties.

```ts
class ColorPickerDialogContent extends React.Component<IColorPickerDialogContentProps, {}> {
Expand Down Expand Up @@ -165,7 +167,7 @@ class ColorPickerDialogContent extends React.Component<IColorPickerDialogContent
}
}
```
Add the following class definition for our custom dialog under the just added `ColorPickerDialogContent` class. This is the actual custom dialog which will be called from the ListView Command Set button click and is inherited from the `BaseDialog`.
Add the following class definition for your custom dialog box under the `ColorPickerDialogContent` class that you just added. This is the actual custom dialog box that will be called from the ListView Command Set button click and is inherited from the `BaseDialog`.

```ts
export default class ColorPickerDialog extends BaseDialog {
Expand Down Expand Up @@ -195,32 +197,32 @@ export default class ColorPickerDialog extends BaseDialog {
}
```

## Associating the Custom Dialog with the ListView Command Set Button Click
To associate the custom dialog with your custom ListView Command Set, the code to initiate the dialog has to be added within the button click operation.
## Associate the custom dialog box with the ListView Command Set button click
To associate the custom dialog box with your custom ListView Command Set, add the code to initiate the dialog box within the button click operation.

In the code editor, open the **DialogDemoCommandSet.ts** file from the **./src/extensions/dialogDemo/** folder.

Add the following import statements under the existing **strings** import. These are for using the just created custom dialog in the context of your ListView Command Set.
Add the following import statements under the existing **strings** import. These are for using the custom dialog box in the context of your ListView Command Set.

```ts
import { Dialog } from '@microsoft/sp-dialog';
import ColorPickerDialog from './ColorPickerDialog';
```

Add the following `_colorCode` variable definition above the `onInit` function in the `DialogDemoCommandSet` class. This is used to store the color picker dialog result.
Add the following `_colorCode` variable definition above the `onInit` function in the `DialogDemoCommandSet` class. This is used to store the color picker dialog box result.

```ts
private _colorCode: string;
```

Update the `onExecute` function as follows. In this code we are doing the following:
Update the `onExecute` function as follows. This code does the following:

* Initiate our custom dialog
* Pass a message for the dialog, which will be used as the title
* Pass a color code for the dialog with a default value, if not yet set
* Show our custom dialog
* Receive and store the return value from the dialog
* Show the received value in an out-of-the-box dialog using the `Dialog.alert()` function
* Initiates the custom dialog box.
* Passes a message for the dialog box, which is used for the title.
* Passed a color code for the dialog box with a default value, if not yet set.
* Shows the custom dialog box.
* Receives and stores the return value from the dialog box.
* Shows the received value in a default dialog box using the `Dialog.alert()` function.

```ts
@override
Expand All @@ -242,44 +244,44 @@ Update the `onExecute` function as follows. In this code we are doing the follow
}
```

## Testing the Custom Dialog in your Tenant
## Test the custom dialog box in your tenant

Open the **DialogDemoCommandSet.manifest.json** file in **./src/extensions/dialogDemo/** folder and copy the **id** value, which will be used in the debug query parameter.
Open the **DialogDemoCommandSet.manifest.json** file in the **./src/extensions/dialogDemo/** folder and copy the **id** value, which will be used in the debug query parameter.

Return to the console and execute the following command:
Return to the console and run the following command:

```sh
gulp serve --nobrowser
```

Notice that we used the `--nobrowser` option, since there's no value in launching the local workbench since you currently cannot debug extensions locally.
Notice that you use the `--nobrowser` option. You don't need to launch the local workbench because you currently cannot debug extensions locally.

This will start the bundling of your solution and will serve the resulting manifest from the `localhost` address.

![Initial Visual Studio Code structure after scaffolding](../../../../images/ext-com-dialog-gulp-serve.png)

To test your extension, navigate to a site in your SharePoint Online developer tenant.
To test your extension, go to a site in your SharePoint Online developer tenant.

Navigate to an existing custom list within the site with some items or create a new list and add a few items to it for testing purposes.
Go to an existing custom list within the site that contains some items, or create a new list and add a few items to it for testing purposes.

Append the following query string parameters to the URL. Notice that you will need to update the **id** to match your own extension identifier as listed in the **DialogDemoCommandSet.manifest.json** file:

```
?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"8701f44c-8c81-4e54-999d-62763e8f34d2":{"location":"ClientSideExtension.ListViewCommandSet.CommandBar"}}
```

Accept the loading of Debug Manifests by clicking **Load debug scripts** when prompted:
Accept the loading of Debug Manifests by choosing **Load debug scripts** when prompted.

![Allow debug scripts warning](../../../../images/ext-com-dialog-debug-scripts.png)

Notice the new button is visible in the toolbar of the list with the text *Open Custom Dialog*.
Notice that the new button is visible in the toolbar of the list with the text *Open Custom Dialog box*.

![Allow debug scripts warning](../../../../images/ext-com-dialog-button-in-toolbar.png)

Click the *Open Custom Dialog* button to see your custom dialog rendered within the list view.
Choose the *Open Custom Dialog box* button to see your custom dialog box rendered within the list view.

![Allow debug scripts warning](../../../../images/ext-com-dialog-visible-dialog.png)

Choose a color in the *Color Picker* and click **OK** to test how the code is returning the selected value back to the caller. The selection is then shown using the out-of-the-box alert dialog.
Choose a color in the *Color Picker* and choose **OK** to test how the code is returning the selected value back to the caller. The selection is then shown using the default alert dialog box.

![Out-of-the-box alert dialog](../../../../images/ext-com-dialog-oob-alert-dialog.png)
![Default alert dialog box](../../../../images/ext-com-dialog-oob-alert-dialog.png)
2 changes: 1 addition & 1 deletion misc/SharePointDocumentationToc.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
<Item text="Build ListView Command Set" url="spfx/extensions/get-started/building-simple-cmdset-with-dialog-api" SEODescription="Build a ListView Command Set, which uses dialog API." />
</Item>
<Item text="Guidance" url="spfx/extensions/get-started">
<Item text="Using custom dialogs" url="spfx/extensions/guidance/using-custom-dialogs-with-spfx" SEODescription="Using Custom Dialogs with SharePoint Framework Extensions." />
<Item text="Use custom dialog boxes" url="spfx/extensions/guidance/using-custom-dialogs-with-spfx" SEODescription="Using Custom Dialogs with SharePoint Framework Extensions." />
</Item>
</Item>
<Item text="Web parts" url="spfx/web-parts" SEODescription="">
Expand Down