Skip to content

Commit 0a6a6a9

Browse files
manishgarg1manishgarg1
authored
Create web-part-to-web-part-communication
1 parent f4c12a1 commit 0a6a6a9

File tree

1 file changed

+369
-0
lines changed

1 file changed

+369
-0
lines changed

‎docs/spfx/web-parts/get-started/web-part-to-web-part-communication

Lines changed: 369 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,369 @@
1+
# Build your first SharePoint client-side web part (Hello World part 1)
2+
3+
Client-side web parts are client-side components that run inside the context of a SharePoint page. Client-side web parts can be deployed to SharePoint Online, and you can also use modern JavaScript tools and libraries to build them.
4+
5+
Client-side web parts support:
6+
7+
* Building with HTML and JavaScript.
8+
* Both SharePoint online and on-premises environments.
9+
10+
>**Note:** Before following the steps in this article, be sure to [Set up your development environment](../../set-up-your-development-environment).
11+
12+
You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=QbDtsMg88Js&list=PLR9nK3mnD-OXvSWvS2zglCzz4iplhVrKq).
13+
14+
<a href="https://www.youtube.com/watch?v=QbDtsMg88Js&list=PLR9nK3mnD-OXvSWvS2zglCzz4iplhVrKq">
15+
<img src="../../../../images/spfx-youtube-tutorial1.png" alt="Screenshot of the YouTube video player for this tutorial" />
16+
</a>
17+
18+
19+
## Create a new web part project
20+
Create a new project directory in your favorite ___location.
21+
22+
```
23+
md helloworld-webpart
24+
```
25+
26+
Go to the project directory.
27+
28+
```
29+
cd helloworld-webpart
30+
```
31+
32+
Create a new HelloWorld web part by running the Yeoman SharePoint Generator.
33+
34+
```
35+
yo @microsoft/sharepoint
36+
```
37+
38+
When prompted:
39+
40+
* Accept the default **helloworld-webpart** as your solution name and choose **Enter**.
41+
* Select **Use the current folder** for where to place the files.
42+
43+
The next set of prompts will ask for specific information about your web part:
44+
45+
* Accept the default **No javascript web framework** as the framework you would like to use and choose **Enter**.
46+
* Accept the default **HelloWorld** as your web part name and choose **Enter**.
47+
* Accept the default **HelloWorld description** as your web part description and choose **Enter**.
48+
49+
![Yeoman SharePoint generator prompts to create a web part client-side solution](../../../../images/yeoman-sp-prompts.png)
50+
51+
At this point, Yeoman will install the required dependencies and scaffold the solution files along with the **HelloWorld** web part. This might take a few minutes.
52+
53+
When the scaffold is complete, you should see the following message indicating a successful scaffold:
54+
55+
![SharePoint client-side solution scaffolded successfully](../../../../images/yeoman-sp-complete.png)
56+
57+
For information about troubleshooting any errors, see [Known issues](../basics/known-issues).
58+
59+
### Using your favorite Code Editor
60+
Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your web part, such as:
61+
62+
* [Visual Studio Code](https://code.visualstudio.com/)
63+
* [Atom](https://atom.io)
64+
* [Webstorm](https://www.jetbrains.com/webstorm)
65+
66+
SharePoint Framework documentation uses Visual Studio code in the steps and examples. Visual Studio Code is a lightweight but powerful source code editor from Microsoft which runs on your desktop and is available for Windows, Mac and Linux. It comes with built-in support for JavaScript, TypeScript and Node.js and has a rich ecosystem of extensions for other languages (such as C++, C#, Python, PHP) and runtimes..
67+
68+
## Preview the web part
69+
To preview your web part, build and run it on a local web server. The client-side toolchain uses HTTPS endpoint by default. However, since a default certificate is not configured for the local dev environment, your browser will report a certificate error. The SPFx toolchain comes with a developer certificate that you can install for building web parts.
70+
71+
To install the developer certificate for use with SPFx development, switch to your console, make sure you are still in the **helloworld-webpart** directory and enter the following command:
72+
73+
```
74+
gulp trust-dev-cert
75+
```
76+
77+
Now that we have installed the developer certificate, enter the following command in the console to build and preview your web part:
78+
79+
```
80+
gulp serve
81+
```
82+
83+
This command will execute a series of gulp tasks to create a local, Node-based HTTPS server on 'localhost:4321' and launch your default browser to preview web parts from your local dev environment.
84+
85+
![Gulp serve web part project](../../../../images/helloworld-wp-gulp-serve.png)
86+
87+
SharePoint client-side development tools use [gulp](http://gulpjs.com/) as the task runner to handle build process tasks such as:
88+
89+
* Bundle and minify JavaScript and CSS files.
90+
* Run tools to call the bundling and minification tasks before each build.
91+
* Compile SASS files to CSS.
92+
* Compile TypeScript files to JavaScript.
93+
94+
If you are new to gulp, you can read [Using Gulp](http://docs.asp.net/en/latest/client-side/using-gulp.html) which describes using gulp with Visual Studio in conjunction with building ASP.NET 5 projects.
95+
96+
Visual Studio Code provides built-in support for gulp and other task runners. Choose **Ctrl+Shift+B** on Windows or **Cmd+Shift+B** on Mac to debug and preview your web part.
97+
98+
### SharePoint Workbench
99+
SharePoint Workbench is a developer design surface that enables you to quickly preview and test web parts without deploying them in SharePoint. SharePoint Workbench includes the client-side page and the client-side canvas in which you can add, delete and test your web parts in development.
100+
101+
![SharePoint Workbench running locally](../../../../images/sp-workbench.png)
102+
103+
To add the HelloWorld web part, choose the **add** button. The add button opens the toolbox where you can see a list of web parts available for you to add. The list will include the **HelloWorld** web part as well other web parts available locally in your development environment.
104+
105+
![SharePoint Workbench toolbox in localhost](../../../../images/sp-workbench-toolbox.png)
106+
107+
Choose **HelloWorld** to add the web part to the page:
108+
109+
![HelloWorld web part in SharePoint workbench](../../../../images/sp-workbench-helloworld-wp.png)
110+
111+
Congratulations! You have just added your first client-side web part to a client-side page.
112+
113+
Now, choose the pencil icon on the far left of the web part to reveal the web part property pane.
114+
115+
![HelloWorld web part property pane](../../../../images/sp-workbench-helloworld-pp.png)
116+
117+
The property pane is where you can define properties to customize your web part. The property pane is client-side driven and provides a consistent design across SharePoint.
118+
119+
Modify the text in the **Description** text box to **Client-side web parts are awesome!**
120+
121+
Notice how the text in the web part also changes as you type.
122+
123+
One of the new capabilities available to the property pane is to configure its update behavior, which can be set to reactive or non-reactive. By default the update behavior is reactive and enables you to see the changes as you edit the properties. The changes are saved instantly as when the behavior is reactive.
124+
125+
## Web part project structure
126+
You can use Visual Studio Code to explore the web part project structure.
127+
128+
* In the console, go to the **src\webparts\helloWorld** directory.
129+
* Enter the following command to open the web part project in Visual Studio Code (or use your favorite editor):
130+
131+
```
132+
code .
133+
```
134+
135+
![HelloWorld project structure](../../../../images/helloworld-wp-vscode-project-structure.png)
136+
137+
If you get an error, you might need to [install the code command in PATH](https://code.visualstudio.com/docs/editor/setup).
138+
139+
TypeScript is the primary language for building SharePoint client-side web parts. TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. SharePoint client-side development tools are built using TypeScript classes, modules, and interfaces to help developers build robust client-side web parts.
140+
141+
The following are some key files in the project.
142+
143+
### Web part class
144+
**HelloWorldWebPart.ts** defines the main entry point for the web part. The web part class **HelloWorldWebPart** extends the **BaseClientSideWebPart**. Any client-side web part should extend the **BaseClientSideWebPart** class in order to be defined as a valid web part.
145+
146+
**BaseClientSideWebPart** implements the minimal functionality that is required to build a web part. This class also provides many parameters to validate and access to read-only properties such as **displayMode**, web part properties, web part context, web part **instanceId**, the web part **domElement** and much more.
147+
148+
Notice that the web part class is defined to accept a property type **IHelloWorldWebPartProps**.
149+
150+
The property type is defined as an interface in a separate file **IHelloWorldWebPartProps.ts**.
151+
152+
```ts
153+
export interface IHelloWorldWebPartProps {
154+
description: string;
155+
}
156+
```
157+
158+
This property definition is used to define custom property types for your web part, which is described in the property pane section later.
159+
160+
#### Web part render method
161+
The DOM element where the web part should be rendered is available in the **render** method. This method is used to render the web part inside that DOM element. In the **HelloWorld** web part, the DOM element is set to a DIV. The method parameters include the display mode (either Read or Edit) and the configured web part properties if any:
162+
163+
```ts
164+
public render(): void {
165+
this.domElement.innerHTML = `
166+
<div class="${styles.helloWorld}">
167+
<div class="${styles.container}">
168+
<div class="ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}">
169+
<div class="ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1">
170+
<span class="ms-font-xl ms-fontColor-white">Welcome to SharePoint!</span>
171+
<p class="ms-font-l ms-fontColor-white">Customize SharePoint experiences using Web Parts.</p>
172+
<p class="ms-font-l ms-fontColor-white">${escape(this.properties.description)}</p>
173+
<a href="https://aka.ms/spfx" class="${styles.button}">
174+
<span class="${styles.label}">Learn more</span>
175+
</a>
176+
</div>
177+
</div>
178+
</div>
179+
</div>`;
180+
}
181+
```
182+
183+
This model is flexible enough so that web parts can be built in any JavaScript framework and loaded into the DOM element.
184+
185+
#### Configure the Web part property pane
186+
The property pane is defined in the **HelloWorldWebPart** class. The **propertyPaneSettings** property is where you need to define the property pane.
187+
188+
When the properties are defined, you can access them in your web part using `this.properties.<property-value>`, as shown in the **render** method:
189+
190+
```ts
191+
<p class="${styles.description}">${escape(this.properties.description)}</p>
192+
```
193+
194+
Notice that we are performing a HTML escape on the property's value to ensure a valid string.
195+
196+
Read the [Integrating property pane with a web part](../basics/integrate-with-property-pane) article to learn more about how to work with the property pane and property pane field types.
197+
198+
Lets now add few more properties - a checkbox, dropdown and a toggle - to the property pane. We first start by importing the respective property pane fields from the framework.
199+
200+
Scroll to the top of the file and add the following to the import section from `@microsoft/sp-webpart-base`:
201+
202+
```ts
203+
PropertyPaneCheckbox,
204+
PropertyPaneDropdown,
205+
PropertyPaneToggle
206+
```
207+
208+
The complete import section will look like the following:
209+
210+
```ts
211+
import {
212+
BaseClientSideWebPart,
213+
IPropertyPaneConfiguration,
214+
PropertyPaneTextField,
215+
PropertyPaneCheckbox,
216+
PropertyPaneDropdown,
217+
PropertyPaneToggle
218+
} from '@microsoft/sp-webpart-base';
219+
```
220+
221+
Save the file.
222+
223+
Next, update the web part properties to include the new properties. This maps the fields to typed objects.
224+
225+
Open **IHelloWorldWebPartProps.ts** and replace the existing code with the following code.
226+
227+
```ts
228+
export interface IHelloWorldWebPartProps {
229+
description: string;
230+
test: string;
231+
test1: boolean;
232+
test2: string;
233+
test3: boolean;
234+
}
235+
```
236+
237+
Save the file.
238+
239+
Switch back to the **HelloWorldWebPart.ts** file.
240+
241+
Replace the **getPropertyPaneConfiguration** method with the code below which adds the new property pane fields and maps them to their respective typed objects.
242+
243+
```ts
244+
protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
245+
return {
246+
pages: [
247+
{
248+
header: {
249+
description: strings.PropertyPaneDescription
250+
},
251+
groups: [
252+
{
253+
groupName: strings.BasicGroupName,
254+
groupFields: [
255+
PropertyPaneTextField('description', {
256+
label: 'Description'
257+
}),
258+
PropertyPaneTextField('test', {
259+
label: 'Multi-line Text Field',
260+
multiline: true
261+
}),
262+
PropertyPaneCheckbox('test1', {
263+
text: 'Checkbox'
264+
}),
265+
PropertyPaneDropdown('test2', {
266+
label: 'Dropdown',
267+
options: [
268+
{ key: '1', text: 'One' },
269+
{ key: '2', text: 'Two' },
270+
{ key: '3', text: 'Three' },
271+
{ key: '4', text: 'Four' }
272+
]}),
273+
PropertyPaneToggle('test3', {
274+
label: 'Toggle',
275+
onText: 'On',
276+
offText: 'Off'
277+
})
278+
]
279+
}
280+
]
281+
}
282+
]
283+
};
284+
}
285+
```
286+
287+
288+
After you add your properties to the web part properties, you can now access the properties in the same way you accessed the **description** property earlier:
289+
290+
```ts
291+
<p class="ms-font-l ms-fontColor-white">${escape(this.properties.test)}</p>
292+
```
293+
294+
To set the default value for the properties, you will need to update the web part manifest's **properties** property bag:
295+
296+
Open `HelloWorldWebPart.manifest.json` and modify the `properties` to:
297+
298+
```ts
299+
"properties": {
300+
"description": "HelloWorld",
301+
"test": "Multi-line text field",
302+
"test1": true,
303+
"test2": "2",
304+
"test3": true
305+
}
306+
```
307+
308+
The web part property pane will now have these default values for those properties.
309+
310+
### Web part manifest
311+
The **HelloWorldWebPart.manifest.json** file defines the web part metadata such as version, id, display name, icon, and description. Every web part should contain this manifest.
312+
313+
```json
314+
{
315+
"$schema": "../../../node_modules/@microsoft/sp-module-interfaces/lib/manifestSchemas/jsonSchemas/clientSideComponentManifestSchema.json",
316+
317+
"id": "922a9623-f92f-4971-8574-185b31554e44",
318+
"alias": "HelloWorldWebPart",
319+
"componentType": "WebPart",
320+
"version": "0.0.1",
321+
"manifestVersion": 2,
322+
323+
"preconfiguredEntries": [{
324+
"groupId": "922a9623-f92f-4971-8574-185b31554e44",
325+
"group": { "default": "Under Development" },
326+
"title": { "default": "HelloWorld" },
327+
"description": { "default": "HelloWorld description" },
328+
"officeFabricIconFontName": "Page",
329+
"properties": {
330+
"description": "HelloWorld",
331+
"test": "Multi-line text field",
332+
"test1": true,
333+
"test2": "2",
334+
"test3": true
335+
}
336+
}]
337+
}
338+
```
339+
340+
Now that we have introduced new properties, make sure that you are again hosting the web part from the local developement environment by executing following command. This will also ensure that the above changes were correctly applied.
341+
342+
```
343+
gulp serve
344+
```
345+
346+
### Preview the web part in SharePoint
347+
348+
SharePoint Workbench is also hosted in SharePoint to preview and test your local web parts in development. The key advantage is that now you are running in SharePoint context and that you will be able to interact with SharePoint data.
349+
350+
Go to the following URL: 'https://your-sharepoint-site/_layouts/workbench.aspx'
351+
352+
>**Note:** If you do not have the SPFx developer certificate installed, then Workbench will notify you that it is configured not to load scripts from localhost. Execute `gulp trust-dev-cert` command in your project directory console to install the developer certificate.
353+
354+
![SharePoint Workbench running in a SharePoint Online site](../../../../images/sp-workbench-o365.png)
355+
356+
Notice that the SharePoint workbench now has the Office 365 Suite navigation bar.
357+
358+
Choose **add icon** in the canvas to reveal the toolbox. The toolbox now shows the web parts available on the site where the SharePoint workbench is hosted along with your **HelloWorldWebPart**.
359+
360+
![Toolbox in SharePoint Workbench running in SharePoint Online site](../../../../images/sp-workbench-o365-toolbox.png)
361+
362+
Add **HelloWorldWebPart** from the toolbox. Now you're running your web part in a page hosted in SharePoint!
363+
364+
![HelloWorld web part running in SharePoint Workbench running in a SharePoint Online site](../../../../images/sp-workbench-o365-helloworld-wp.png)
365+
366+
Because you are still developing and testing your web part, there is no need to package and deploy your web part to SharePoint.
367+
368+
## Next steps
369+
Congratulations on getting your first Hello World web part running! Now that your web part is running, you can continue building out your Hello World web part in the next topic, [Connect to SharePoint](./connect-to-sharepoint). You will use the same Hello World web part project and add the ability to interact with SharePoint List REST APIs. Notice that the `gulp serve` command is still running in your console window (or in Visual Studio Code if you using the editor). You can continue to let it run while you go to the next article.

0 commit comments

Comments
 (0)