Skip to content

Commit 9dc385a

Browse files
LauragraVesaJuvonen
Lauragra
authored and
VesaJuvonen
committed
Staging (SharePoint#845)
* Edit pass. * Updated TOC title. * One more change. * Edits.
1 parent 429f130 commit 9dc385a

File tree

1 file changed

+71
-69
lines changed

1 file changed

+71
-69
lines changed

‎docs/spfx/extensions/get-started/build-a-hello-world-extension.md

Lines changed: 71 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,153 @@
1-
21
# Build your first SharePoint Framework Extension (Hello World part 1)
32

4-
>**Note:** The SharePoint Framework Extensions are currently in preview and are subject to change. SharePoint Framework Extensions are not currently supported for use in production environments.
3+
>**Note:** SharePoint Framework Extensions are currently in preview and are subject to change. They are not currently supported for use in production environments.
54
6-
Extensions are client-side components that run inside the context of a SharePoint page. Extensions can be deployed to SharePoint Online, and you can also use modern JavaScript tools and libraries to build them.
5+
SharePoint Framework (SPFx) Extensions are client-side components that run inside the context of a SharePoint page. You can deploy extensions to SharePoint Online, and you can use modern JavaScript tools and libraries to build them.
76

8-
You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=0BeS0HukW24&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV).
7+
You can follow the steps in this article by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=0BeS0HukW24&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV).
98

109
<a href="https://www.youtube.com/watch?v=0BeS0HukW24&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV">
1110
<img src="../../../../images/spfx-ext-youtube-tutorial1.png" alt="Screenshot of the YouTube video player for this tutorial" />
1211
</a>
1312

1413
## Create an extension project
15-
Create a new project directory in your favorite ___location.
1614

17-
```
18-
md app-extension
19-
```
15+
1. Create a new project directory in your favorite ___location.
2016

21-
Go to the project directory.
17+
```
18+
md app-extension
19+
```
2220
23-
```
24-
cd app-extension
25-
```
21+
2. Go to the project directory.
2622
27-
Create a new HelloWorld extension by running the Yeoman SharePoint Generator.
23+
```
24+
cd app-extension
25+
```
2826
29-
```
30-
yo @microsoft/sharepoint
31-
```
27+
3. Create a new HelloWorld extension by running the Yeoman SharePoint Generator.
3228
33-
When prompted:
29+
```
30+
yo @microsoft/sharepoint
31+
```
3432
35-
* Accept the default **app-extension** as your solution name and press **Enter**.
36-
* Choose **Use the current folder** and press **Enter**
37-
* Choose **N** to require extension to be installed on each site explicitly when it's being used
38-
* Choose **Extension (Preview)** as the client-side component type to be created.
39-
* Choose **Application Customizer (Preview)** as the extension type to be created.
33+
4. When prompted:
4034
41-
The next set of prompts will ask for specific information about your extension:
35+
* Accept the default **app-extension** as your solution name, and press **Enter**.
36+
* Choose **Use the current folder**, and press **Enter**.
37+
* Choose **N** to require the extension to be installed on each site explicitly when it's being used.
38+
* Choose **Extension (Preview)** as the client-side component type to be created.
39+
* Choose **Application Customizer (Preview)** as the extension type to be created.
4240
43-
* Accept the default **HelloWorld** as your extension name and press **Enter**.
44-
* Accept the default **HelloWorld description** as your extension description and press **Enter**.
41+
5. The next set of prompts will ask for specific information about your extension. When prompted:
4542
46-
![Yeoman SharePoint generator prompts to create an extension solution](../../../../images/ext-yeoman-app-prompts.png)
43+
* Accept the default **HelloWorld** as your extension name, and press **Enter**.
44+
* Accept the default **HelloWorld description** as your extension description, and press **Enter**.
4745
48-
> Notice that if you use too long naming for the extension, that can cause issues. Provided entries are used to generate alias entry for the application customizer manifest json file. If alias is longer than 40 characters, you will have an exception when you are trying to serve the extension using `gulp serve --nobrowser`. You can solve this by updating the alias entry also afterwards.
46+
![Yeoman SharePoint generator prompts to create an extension solution](../../../../images/ext-yeoman-app-prompts.png)
4947
50-
At this point, Yeoman will install the required dependencies and scaffold the solution files along with the **HelloWorld** extension. This might take a few minutes.
48+
> **Note:** If you use a name for the extension that is too long, you might encounter issues. The entries provided are used to generate an alias entry for the application customizer manifest json file. If the alias is longer than 40 characters, you will get an exception when you try to serve the extension using `gulp serve --nobrowser`. You can resolve this by updating the alias entry afterward.
5149
52-
When the scaffold is complete, you should see the following message indicating a successful scaffold:
50+
At this point, Yeoman will install the required dependencies and scaffold the solution files along with the **HelloWorld** extension. This might take a few minutes.
5351
54-
![SharePoint client-side solution scaffolded successfully](../../../../images/ext-yeoman-app-complete.png)
52+
When the scaffold is complete, you should see the following message indicating a successful scaffold:
5553
56-
For information about troubleshooting any errors, see [Known issues](../basics/known-issues).
54+
![SharePoint client-side solution scaffolded successfully](../../../../images/ext-yeoman-app-complete.png)
5755
58-
Once solution scaffolding is completed, type the following into the console to start Visual Studio Code.
56+
For information about troubleshooting any errors, see [Known issues](../basics/known-issues).
5957
60-
```
61-
code .
62-
```
58+
6. When the solution scaffolding is complete, type the following into the console to start Visual Studio Code.
6359
64-
> Notice that because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension.
60+
```
61+
code .
62+
```
6563
66-
Notice how the default solution structure is like the solution structure of client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types.
64+
>**Note:** Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension.
6765
68-
![SharePoint Framework solution opened after initial scaffolding](../../../../images/ext-app-vscode-solution-structure.png)
66+
Notice how the default solution structure looks like the solution structure for client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types.
6967
70-
Open **HelloWorldApplicationCustomizer.manifest.json** at the src\extensions\helloWorld folder.
68+
![SharePoint Framework solution opened after initial scaffolding](../../../../images/ext-app-vscode-solution-structure.png)
7169
72-
This file defines your extension type and a unique identifier **“id”** for your extension. You’ll need this unique identifier later when debugging and deploying your extension to SharePoint.
70+
7. Open **HelloWorldApplicationCustomizer.manifest.json** in the src\extensions\helloWorld folder.
7371
74-
![Application customizer manifest json content](../../../../images/ext-app-vscode-manifest.png)
72+
This file defines your extension type and a unique identifier for your extension. You’ll need this ID later when you debug and deploy your extension to SharePoint.
7573
76-
## Coding your Application Customizer
74+
![Application customizer manifest json content](../../../../images/ext-app-vscode-manifest.png)
75+
76+
## Code your Application Customizer
7777
Open the **HelloWorldApplicationCustomizer.ts** file in the **src\extensions\helloWorld** folder.
7878
7979
Notice that base class for the Application Customizer is imported from the **sp-application-base** package, which contains SharePoint framework code required by the Application Customizer.
8080
81-
![import statement for BaseApplicationCustomizer from @microsoft/sp-application-base](../../../../images/ext-app-vscode-app-base.png)
81+
![Import statement for BaseApplicationCustomizer from @microsoft/sp-application-base](../../../../images/ext-app-vscode-app-base.png)
8282
8383
The logic for your Application Customizer is contained in the **onInit** method.
8484
8585
- **onInit()** is called when the client-side extension is first activated on the page. This event occurs after ```this.context``` and ```this.properties``` are assigned. As with web parts, ```onInit()``` returns a promise that you can use to perform asynchronous operations.
8686
87-
> Notice. The class constructor is called at an early stage, when ```this.context``` and ```this.properties``` are undefined. We do not support including custom initiation logic here.
87+
>**Note:** The class constructor is called at an early stage, when ```this.context``` and ```this.properties``` are undefined. Custom initiation logic is not supported here.
88+
89+
The following are the contents of **onInit()** in the default solution. This default solution writes a log to the Dev Dashboard, and then displays a simple JavaScript alert when the page renders.
8890
89-
Below is the contents of **onInit()** in the default solution. This default solution simply writes a log to the Dev Dashboard, and then displays a simple JavaScript alert when the page renders.
91+
![Default onInit method in the code](../../../../images/ext-app-vscode-methods.png)
9092
91-
![default onInit method in the code](../../../../images/ext-app-vscode-methods.png)
93+
If your application customizer uses the **ClientSideComponentProperties** JSON input, it will be deserialized into the **BaseExtension.properties** object. You can define an interface to describe it. The default template is looking for a property called **testMessage**. If that property is provided, it outputs it in an alert message.
9294
93-
> If your application customizer uses the ClientSideComponentProperties JSON input, it will be deserialized into the BaseExtension.properties object. You can define an interface to describe it. The default template is looking for a property called testMessage, and if it's provided, outputting it in an alert message.
95+
## Debug your Application Customizer using gulp serve and query string parameters
96+
You cannot current use the local workbench to test SharePoint Framework Extensions. You'll need to test them against a live SharePoint Online site. You don't have to deploy your customization to the app catalog to do this, which makes the debugging experience simple and efficient.
9497
95-
## Debugging your Application Customizer using gulp serve and query string parameters
96-
SharePoint Framework extensions cannot currently be tested using the local workbench, so you'll need to test and develop them directly against a live SharePoint Online site. You do not, however, need to deploy your customization to the app catalog to do this, which keeps the debugging experience simple and efficient.
98+
First, compile your code and host the compiled files from your local computer by running the following command.
9799
98-
First, compile your code and host the compiled files from your local machine by running this command:
99100
```
100101
gulp serve --nobrowser
101102
```
102103
103-
>**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. Stop currently running process in the console window, execute `gulp trust-dev-cert` command in your project directory console to install the developer certificate before running `gulp serve --nobrowser` command again.
104+
>**Note:** If you do not have the SPFx developer certificate installed, Workbench will notify you that it is not configured to load scripts from localhost. If this happens, stop the process that is currently running in the console window, run the `gulp trust-dev-cert` command in your project directory console to install the developer certificate, and then run the `gulp serve --nobrowser` command again.
105+
106+
You use the ```--nobrowser``` option because you don't need to launch the local workbench, since you can't debug extensions locally.
104107
105-
Notice that we used the ```--nobrowser``` option, since there's no value in launching the local workbench since you currently cannot debug extensions locally.
108+
When the code compiles without errors, it will serve the resulting manifest from http://localhost:4321.
106109
107-
Once it compiles the code without errors, it will serve the resulting manifest from http://localhost:4321.
110+
![Gulp serve](../../../../images/ext-app-gulp-serve.png)
108111
109-
![gulp serve](../../../../images/ext-app-gulp-serve.png)
112+
To test your extension, go to a modern list view page in your SharePoint environment and append the following query string parameters to the URL. Notice that you will need to update the ID to match your own extension identifier. This is available in the **HelloWorldApplicationCustomizer.manifest.json** file.
110113
111-
To test your extension, navigate to a modern list view page in your SharePoint environment and append the following query string parameters to the URL. Notice that you will need to update the id to match your own extension identifier available from the **HelloWorldApplicationCustomizer.manifest.json** file:
112114
```
113115
?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{"___location":"ClientSideExtension.ApplicationCustomizer","properties":{"testMessage":"Hello as property!"}}}
114116
```
115117
116118
More detail about the URL query parameters:
117119
118-
* **loadSPFX=true:** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Since no components are registered yet, we must explicitly load the framework.
120+
* **loadSPFX=true** - Ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework does not load unless at least one extension is registered. Because no components are registered,you must explicitly load the framework.
119121
120-
* **debugManifestsFile:** specifies that we want to load SPFx components that are being locally served. Normally the loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries).
122+
* **debugManifestsFile** - Specifies that you want to load SPFx components that are locally served. The loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries).
121123
122-
* **customActions:** this URL query parameter simulates a custom action. When we actually deploy and register this component in a site later in this lab, we’ll create this CustomAction object for real and describe all the different properties you can set on it.
123-
* **Key:** use the Guid of the extension as the key to associate with the custom action. This has to match on the id value of your extension available from the extension manifest.json.
124-
* **Location:** the type of custom action, use "ClientSideExtension.ApplicationCustomizer" for the Application Customizer extension
125-
* **Properties:** an optional JSON object containing properties that will be available via the this.properties member. In this HelloWorld example, it defined a ‘testMessage’ property.
124+
* **customActions** - Simulates a custom action. When you deploy and register this component in a site, you'll create this **CustomAction** object and describe all the different properties you can set on it.
125+
* **Key** - Use the Guid of the extension as the key to associate with the custom action. This has to match the ID value of your extension, which is available in the extension manifest.json file.
126+
* **Location** - The type of custom action. Use "ClientSideExtension.ApplicationCustomizer" for the Application Customizer extension.
127+
* **Properties** - An optional JSON object that contains properties that will be available via the **this.properties** member. In this HelloWorld example, it defined a ‘testMessage’ property.
126128
127129
128-
Navigate to a out of the box modern list in SharePoint Online. This can be a list or a library for the initial testing. Application customizers are also supported in modern pages and on the Site Contents page.
130+
Go to a modern list in SharePoint Online. This can be either a list or a library. Application customizers are also supported in modern pages and on the Site Contents page.
129131
130-
Extend the URL with the additional query parameters defined above. Notice that you'll need to update the GUID to match the ID of your custom Application Customizer available from **HelloWorldApplicationCustomizer.manifest.json** at the src\extensions\helloWorld folder.
132+
Extend the URL with the additional query parameters described. Notice that you'll need to update the GUID to match the ID of your custom Application Customizer.
131133
132-
The full URL should look similar to the following depending on your tenant URL:
134+
The full URL should look similar to the following:
133135
134136
```
135137
contoso.sharepoint.com/Lists/Contoso/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{"___location":"ClientSideExtension.ApplicationCustomizer","properties":{"testMessage":"Hello as property!"}}}
136138
```
137139
138140
![Allow Debug Manifest question from the page](../../../../images/ext-app-debug-manifest-message.png)
139141
140-
Click the "**Load debug scripts**" button to continue loading scripts from your local host.
142+
Choose "**Load debug scripts**" to continue loading scripts from your local host.
141143
142144
You should now see the alert message on your page.
143145
144-
![Allow Debug Manifest question from the page](../../../../images/ext-app-alert-sp-page.png)
146+
![Hello as property alert message](../../../../images/ext-app-alert-sp-page.png)
145147
146-
This alert is thrown by your SharePoint Framework Extension. Notice also that since we provided the testMessage property as part of the debug query parameters, it's included in the alert message. You can configure your extension instances based on the client component properties, which are passed for the instance also in runtime mode.
148+
This alert is thrown by your SharePoint Framework Extension. Note that because you provided the **testMessage** property as part of the debug query parameters, it's included in the alert message. You can configure your extension instances based on the client component properties, which are passed for the instance also in runtime mode.
147149
148-
> If you are having challenges in getting debugging to work, double check the URL query parameters used for the query. Some browsers tend to encode the parameters and in some scenarios this will impact the behavior.
150+
> **Note:** If you have issues with debugging, double-check the URL query parameters used for the query. Some browsers encode the parameters and in some scenarios this affects the behavior.
149151
150152
## Next steps
151-
Congratulations on getting your first SharePoint Framework Extension running! Now that your extension is running, you can continue building out your extension in the next topic, [Using page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md). You will use the same project and take advantage of specific content placeholders for modifying the UI of SharePoint. Notice that the ```gulp serve``` command is still running in your console window (or in Visual Studio Code if you are using the editor). You can continue to let it run while you go to the next article.
153+
Congratulations, you've gotten your first SharePoint Framework Extension running! To continue building out your extension, see [Using page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md). You will use the same project and take advantage of specific content placeholders for modifying the UI of SharePoint. Notice that the ```gulp serve``` command is still running in your console window (or in Visual Studio Code if you are using the editor). You can continue to let it run while you go to the next article.

0 commit comments

Comments
 (0)