Developing with the SharePoint Framework: Web Parts

In this lab you work with the SharePoint Framework to create a client-side web part and leverage different parts of the SharePoint Framework API.

In this lab

Creating a SharePoint Framework Client-Side Web Part
Testing with the local and hosted SharePoint Workbench
Exploring the SharePoint Framework API

Prerequisites

To complete this lab, you need the following:

Office 365 tenancy

If you do not have one, you obtain one (for free) by signing up to the Office 365 Developer Program.
Local SharePoint Framework development environment installed and configured
- Refer to the SharePoint Framework documentation, specifically the Getting Started > Set up development environment for the most current steps

Exercise 1: Creating a SharePoint Framework Client-Side Web Part

In this exercise you will create a SharePoint Framework client-side web part.

Open a command prompt and change to the folder where you want to create the project.
Run the SharePoint Yeoman generator by executing the following command:
```
yo @microsoft/sharepoint
```
Use the following to complete the prompt that is displayed:
- What is your solution name?: HelloWorld
- Which baseline packages do you want to target for your component(s)?: SharePoint Online only (latest)
- Where do you want to place the files?: Use the current folder
- Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites?: No
- Which type of client-side component to create?: WebPart
- What is your Web part name?: HelloWorld
- What is your Web part description?: HelloWorld description
- Which framework would you like to use?: No JavaScript framework
After provisioning the folders required for the project, the generator will install all the dependency packages using NPM.
When NPM completes downloading all dependencies, run the project by executing the following command:
```
gulp serve
```
The SharePoint Framework's gulp serve task will build the project, start a local web server and launch a browser open to the SharePoint Workbench:
Select the web part icon button to open the list of available web parts:
Select the HelloWorld web part:
Edit the web part's properties by selecting the pencil (edit) icon in the toolbar to the left of the web part:
In the property pane that opens, change the value of the Description Field. Notice how the web part updates as you make changes to the text:

1

Update the web part code

Next, update the code in the render() method to add a button that responds to an event.
1. If the local dev webserver is not running, start it by running gulp serve on the command line from the root folder of the project.
2. Open the project folder in Visual Studio Code.
3. Locate and open the file src/webparts/helloWorld/HelloWorldWebPart.ts.
4. Within this file, locate the render() method. Locate the following line:
```
<a href="https://aka.ms/spfx" class="${ styles.button }">
```
  ...and replace replace the URL with a simple hash symbol:
```
<a href="#" class="${ styles.button }">
```
5. Next, add the following code to the end of the render() method.
  
  This will wire up some code to the click event on the anchor tag and display an alert on the page.
```
this.domElement.getElementsByClassName(`${ styles.button }`)[0]
  .addEventListener('click', (event: any) => {
    event.preventDefault();
    alert('Welcome to the SharePoint Framework!');
  });
```
Go back to the browser to test your changes. The browser should have refreshed the changes you made.
Click the Learn More button.

Notice the button triggers a JavaScript alert displaying the message you added in the above code.
Close the browser and stop the local web server by pressing CTRL+C in the command prompt.

Update the web part's properties

Now make some changes to the web part's properties to give it a new name, description and icon.

The web part's metadata is found in it's manifest file.

Locate and open the file src/webparts/helloWorld/HelloWorldWebPart.manifest.json.

In the section preconfiguredEntries, locate the following lines:

"preconfiguredEntries": [{
  ...
  "title": { "default": "HelloWorld" },
  "description": { "default": "HelloWorld description" },
  "officeFabricIconFontName": "Page",
  ...
}]

Change the web part's title and description to something different.

The web part's icon is the name of one of the icons listed in the Office UI Fabric, located here: https://developer.microsoft.com/fabric#/styles/icons. Pick one and update the officeFabricIconFontName property:

"preconfiguredEntries": [{
  ...
  "title": { "default": "Hello SPFx" },
  "description": { "default": "My first SPFx web part" },
  "officeFabricIconFontName": "BirthdayCake",
  ...
}]

Start the local web server using the provided gulp serve task:
```
gulp serve
```
The SharePoint Framework's gulp serve task will build the project, start a local web server and launch a browser open to the SharePoint Workbench. This time when you hover the mouse over the web part in the toolbox, you will see the changes you applied to your web part:
Close the browser and stop the local web server by pressing CTRL+C in the command prompt.

Exercise 2: Testing with the local and hosted SharePoint Workbench

In this exercise you will work with the two different versions of the SharePoint Workbench, the local & hosted workbench, as well as the different modes of the built in gulp serve task.

Open Visual Studio Code and open the SharePoint Framework web part project you created in the previous exercise.
Start the local web server using the provided gulp serve task:
```
gulp serve
```
The SharePoint Framework's gulp serve task will build the project, start a local web server and launch a browser open to the SharePoint Workbench.
Add the web part to the page.
Now, with both the browser and Visual Studio code on the same screen, edit the HTML in the web part's render() method, located in the src/webparts/helloWorld/HelloWorldWebPart.ts file.
If you save the file (or let Visual Studio Code save it after a few seconds of inactivity), you will see the command prompt window execute a lot of commands and then the browser will refresh.

This is because the gulp serve task is monitoring all code files such as *.ts, *.html and *.scss for changes. If they change, it reruns the tasks that gulp serve ran for you. It then refreshed the browser as it is using a utility that allows the server to have some control over the local workbench.

This makes development very easy!

Testing with the SharePoint Online Hosted Workbench

Next, in the browser navigate to one of your SharePoint Online sites and append the following to the end of the root site's URL: /_layouts/workbench.aspx. This is the SharePoint Online hosted workbench.
Notice when you add a web part, many more web parts will appear beyond the one we created and was the only one showing in the toolbox on the local workbench. This is because you are now testing the web part in a working SharePoint site.

NOTE: The difference between the local and hosted workbench is significant. Consider a local workbench is not a working version of SharePoint, rather just a single page that can let you test web parts. This means you won't have access to a real SharePoint context, lists, libraries or real users when you are testing in the local workbench.
Let's see another difference with the local vs. hosted workbench. Go back to the web part and make a change to the HTML.

Notice after saving the file, while the console displays a lot of commands, the browser that is displaying the hosted workbench does not automatically reload. This is expected. You can still refresh the page to see the updated web part, but the local web server cannot cause the hosted workbench to refresh.

The different modes of the gulp serve task

The gulp serve task that you have run so far has automatically opened the local workbench. But there may be cases where you do not want to launch the local workbench and rather, you want to test with the hosted workbench. In these scenarios, you have two options.

Start the local web server using the provided gulp serve task:
```
gulp serve --nobrowser
```
In this case the gulp serve task will run just like normal and start the local webserver, but it will not launch the browser.
Open a browser and navigate to one of your SharePoint Online sites and append the following to the end of the root site's URL: /_layouts/workbench.aspx.
Notice the web part is appearing in the toolbox. Everything still works, you just don't get the default browser!

But what if you want the browser to open the hosted workbench automatically for you? In that case, you can use a configuration setting to tell the gulp serve task what to do.

Locate and open the file config/serve.json

In the serve.json file, add the following JSON to the end of the JSON file:

"serveConfigurations": {
  "default": {
    "pageUrl": "https://contoso.sharepoint.com/sites/mySite/_layouts/workbench.aspx"
  },
  "myConfig": {
    "pageUrl": "https://contoso.sharepoint.com/sites/mySite/_layouts/workbench.aspx"
  }
}

The resulting file would look like the following:

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "initialPage": "https://localhost:5432/workbench",
  "api": {
    "port": 5432,
    "entryPath": "node_modules/@microsoft/sp-webpart-workbench/lib/api/"
  },
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/_layouts/workbench.aspx"
    },
    "myConfig": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/_layouts/workbench.aspx"
    }
  }
}

NOTE: Ensure you enter the proper URL of a SharePoint Online site collection you have access to.

Now, run either of the following two commands to start the local web server and navigate to the hosted workbench:
```
gulp serve
# or
gulp serve --config myConfig
```
Notice the browser will now load, but it will also navigate to you to your hosted workbench in SharePoint Online.

You can use multiple configurations for different sites if you like. This will be useful when you test SharePoint Framework extensions.

Exercise 3: Exploring the SharePoint Framework API

In this exercise you will explore a few different APIs available to you in the SharePoint Framework that are useful in many scenarios.

Open the web part project from the first exercise.
Remove the gulp serve configurations you created in the previous exercise:
1. Locate and open the config/serve.json file.
2. Locate the section serveConfigurations and remove it.
3. Save you changes and close the file.

Checking the current page mode and state

Locate the web part file src/webparts/helloWorld/HelloWorldWebPart.ts.

At the top of the file, locate the following line:

import { Version } from '@microsoft/sp-core-library';

Update this line to the following to import a few additional objects and enumerations into the file:

import { 
  Version,
  DisplayMode, 
  Environment, 
  EnvironmentType
} from '@microsoft/sp-core-library';

Now locate the render() method and add the following two lines to the top of it, right after the method declaration:
```
const pageMode : string = (this.displayMode === DisplayMode.Edit)
  ? 'You are in edit mode'
  : 'You are in read mode';
const environmentType : string = (Environment.type === EnvironmentType.Local)
  ? 'You are in local environment'
  : 'You are in SharePoint environment';
```
These two lines determine the current mode of the page and environment the web part is running in. These can prove to be useful for the web part to render either mock data in the case of running in the local web server or real SharePoint data from a SharePoint list if you are running the web part in a SharePoint environment such as the hosted workbench or in a real SharePoint page.
Display the values in these two members by adding the following two lines to the HTML that is added to the <div> element that contains the rendered web part. Add these lines just after the Welcome to SharePoint message:
```
<p class="${ styles.subTitle }"><strong>Page mode:</strong> ${ pageMode }</p>
<p class="${ styles.subTitle }"><strong>Environment:</strong> ${ environmentType }</p>
```
Let's test the web part to see what we get. Start the local web server using the provided gulp serve task:
```
gulp serve --nobrowser
```
When the browser loads the local workbench, add the web part to he page. Notice the values of the page mode & environment type:
Now, open a new browser tab and navigate to one of your SharePoint Online sites and append the following to the end of the root site's URL: /_layouts/workbench.aspx.
Add the web part to the page.
Notice the values of the page mode & environment type:

Leverage the SharePoint Framework Logging API

The SharePoint Framework also provides a way log messages to the console with additional information than the traditional console.log() method provides.

Locate the web part file src/webparts/helloWorld/HelloWorldWebPart.ts.

At the top of the web part file, locate the following lines:

import { 
  Version,
  DisplayMode, 
  Environment, 
  EnvironmentType
} from '@microsoft/sp-core-library';

Add an additional reference to Log the existing list so it looks like this:

import { 
  Version,
  DisplayMode, 
  Environment, 
  EnvironmentType, 
  Log 
} from '@microsoft/sp-core-library';

Add the following lines to the end of the render() method, immediately before it closes. These will look different messages to the browser's console window:

Log.info('HelloWorld', 'message', this.context.serviceScope);
Log.warn('HelloWorld', 'WARNING message', this.context.serviceScope);
Log.error('HelloWorld', new Error('Error message'), this.context.serviceScope);
Log.verbose('HelloWorld', 'VERBOSE message', this.context.serviceScope);

Go back to the browser and open your browser's developer tools.
Open the Console tab (it may have a slightly different name depending on the browser you are using).
There will be a lot of messages logged to the console, so use the filter technique to filter based on the name of your web part, HelloWorld.
Notice in the following image that each message is prefixed with the unique name of the web part.

Addressing delayed loading web parts

At times your web part may have a number of calculations to perform or have a delay in fetching data before it renders the first time. Thankfully the SharePoint Framework provides an API you can use to address this.

Locate the web part file src/webparts/helloWorld/HelloWorldWebPart.ts.
Locate the following line in the render() method:
```
this.domElement.innerHTML = `
```

Add the following lines just before the this.domElement.innerHTML line:

this.context.statusRenderer.displayLoadingIndicator(this.domElement, "message");
setTimeout(() => {
  this.context.statusRenderer.clearLoadingIndicator(this.domElement);

Locate the closing quote for the HTML written to the web part's <div> innerHTML property:
```
</div>`;
```
Add the following line just after the above line:
```
}, 5000);
```

The code you just added displays the string message in a loading indicator for 5 seconds before clearing it out and writing HTML to the page.

The resulting code should look similar to this:

public render(): void {

  const pageMode : string = this.displayMode === DisplayMode.Edit ? 'You are in edit mode' : 'You are in read mode';
  const environmentType : string = Environment.type === EnvironmentType.Local ? 'You are in local environment' : 'You are in sharepoint environment';

  this.context.statusRenderer.displayLoadingIndicator(this.domElement, "message");
  setTimeout(() => {
    this.context.statusRenderer.clearLoadingIndicator(this.domElement);

    this.domElement.innerHTML = `
      <div class="${ styles.helloWorld }">
        <div class="${ styles.container }">
          <div class="${ styles.row }">
            <div class="${ styles.column }">
              <span class="${ styles.title }">Welcome to SharePoint!</span>
              <p class="${ styles.subTitle }"><strong>Page mode:</strong> ${ pageMode }</p>
              <p class="${ styles.subTitle }"><strong>Environment:</strong> ${ environmentType }</p>
              <p class="${ styles.description }">${escape(this.properties.description)}</p>
              <a href="#" class="${ styles.button }">
                <span class="${ styles.label }">Learn more</span>
              </a>
            </div>
          </div>
        </div>
      </div>`;
  }, 5000);

  this.domElement.getElementsByClassName(`${ styles.button }`)[0]
    .addEventListener('click', (event: any) => {
      event.preventDefault();
      alert('Welcome to the SharePoint Framework!');
    });

  Log.info('HelloWorld', 'message', this.context.serviceScope);
  Log.warn('HelloWorld', 'WARNING message', this.context.serviceScope);
  Log.error('HelloWorld', new Error('Error message'), this.context.serviceScope);
  Log.verbose('HelloWorld', 'VERBOSE message', this.context.serviceScope);
}

Go back to the browser and if it hasn't reloaded, refresh the page.
When the web part initially loads, it displays the loading message:
After five (5) seconds, notice the web part is rendered as it was before because the timeout concludes.
Close the browser and stop the local web server by pressing CTRL+C in the command prompt.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Lab.md

Lab.md

Developing with the SharePoint Framework: Web Parts

In this lab

Prerequisites

Exercise 1: Creating a SharePoint Framework Client-Side Web Part

Update the web part code

Update the web part's properties

Exercise 2: Testing with the local and hosted SharePoint Workbench

Testing with the SharePoint Online Hosted Workbench

The different modes of the gulp serve task

Exercise 3: Exploring the SharePoint Framework API

Checking the current page mode and state

Leverage the SharePoint Framework Logging API

Addressing delayed loading web parts

Files

Lab.md

Latest commit

History

Lab.md

File metadata and controls

Developing with the SharePoint Framework: Web Parts

In this lab

Prerequisites

Exercise 1: Creating a SharePoint Framework Client-Side Web Part

Update the web part code

Update the web part's properties

Exercise 2: Testing with the local and hosted SharePoint Workbench

Testing with the SharePoint Online Hosted Workbench

The different modes of the gulp serve task

Exercise 3: Exploring the SharePoint Framework API

Checking the current page mode and state

Leverage the SharePoint Framework Logging API

Addressing delayed loading web parts