You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Build your first SharePoint Framework Extension (Hello World part 1)
3
3
4
-
>**Note:** The SharePoint Framework Extensions are currently in preview and is subject to change. SharePoint Framework Extensions are not currently supported for use in production environments.
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.
5
5
6
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.
7
7
8
8
>**Note:** Before following the steps in this article, be sure to [Set up your development environment](../../set-up-your-development-environment). Notice that extensions are currently **ONLY** available from Office 365 developer tenants.
9
9
10
-
## Create a extension project
10
+
## Create an extension project
11
11
Create a new project directory in your favorite ___location.
12
12
13
13
```
@@ -28,14 +28,14 @@ yo @microsoft/sharepoint
28
28
29
29
When prompted:
30
30
31
-
* Accept the default **app-extension** as your solution name and choose**Enter**.
32
-
* Choose **Extension (Preview)** as client-side component type to be created.
33
-
* Choose **Application Customizer (Preview)** as they extension type to be created.
31
+
* Accept the default **app-extension** as your solution name and press**Enter**.
32
+
* Choose **Extension (Preview)** as the client-side component type to be created.
33
+
* Choose **Application Customizer (Preview)** as the extension type to be created.
34
34
35
35
The next set of prompts will ask for specific information about your extension:
36
36
37
-
* Accept the default **HelloWorld** as your extension name and choose**Enter**.
38
-
* Accept the default **HelloWorld description** as your extension description and choose**Enter**.
37
+
* Accept the default **HelloWorld** as your extension name and press**Enter**.
38
+
* Accept the default **HelloWorld description** as your extension description and press**Enter**.
39
39
40
40
41
41
@@ -47,21 +47,21 @@ When the scaffold is complete, you should see the following message indicating a
47
47
48
48
For information about troubleshooting any errors, see [Known issues](../basics/known-issues).
49
49
50
-
Once solution scaffolding is completed, type the following into console to start Visual Studio Code.
50
+
Once solution scaffolding is completed, type the following into the console to start Visual Studio Code.
51
51
52
52
```
53
53
code .
54
54
```
55
55
56
56
> 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.
57
57
58
-
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.
58
+
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.
59
59
60
60
61
61
62
62
Open **HelloWorldApplicationCustomizer.manifest.json** at the src\extensions\helloWorld folder.
63
63
64
-
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.
64
+
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.
@@ -72,71 +72,71 @@ Notice that base class for the Application Customizer is imported from the **sp-
72
72
73
73
74
74
75
-
The logic for your Application Customizer is contained in the two methods onInit and onRender.
75
+
The logic for your Application Customizer is contained in the two methods **onInit** and **onRender**.
76
76
77
-
-**onInit()** is where you should perform any setup needed for your extension. This event occurs after this.context and this.properties are assigned, but before the page DOM is ready. Like with web parts, onInit() returns a promise that you can use to perform asynchronous operations; onRender() will not be called until your promise has resolved. If you don’t need that, simply return super.onInit().
78
-
-**onRender()** is where your extension can interact with the UI. This event occurs after the application’s initial page DOM structure has been created (although some parts of the UI may not have finished rendering yet).
77
+
-**onInit()** is where you should perform any setup needed for your extension. This event occurs after ```this.context``` and ```this.properties``` are assigned, but before the page DOM is ready. As with web parts, ```onInit()``` returns a promise that you can use to perform asynchronous operations; ```onRender()``` will not be called until your promise has resolved. If you don’t need that, simply return ```super.onInit()```.
78
+
-**onRender()** is where your extension can interact with the UI. This event occurs after the application’s initial page DOM structure has been created (although some parts of the UI may not have finished rendering yet).
79
79
80
-
> 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.
80
+
> 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.
81
81
82
-
Below are the contents of **onInit()** and **onRender()** 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.
82
+
Below are the contents of **onInit()** and **onRender()** 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.
83
83
84
84
85
85
86
-
> 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. Default template is looking for property called testMessage and is outputting that in alert message, if it's provided.
86
+
> 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.
87
87
88
88
## Debugging your Application Customizer using gulp serve and query string parameters
89
-
SharePoint Framework extensions cannot be currently tested just by using local workbench, so you'll need to test and develop them directly against live SharePoint Online site. You do not however need to deploy your customization to app catalog, to be able to do this, which will keep the debugging experience simple and efficient.
90
-
91
-
First, compile your code and host the compiled files from the local machine by running this command:
89
+
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.
92
90
91
+
First, compile your code and host the compiled files from your local machine by running this command:
93
92
```
94
93
gulp serve --nobrowser
95
94
```
96
-
Notice that we used the `--nobrowser` option, since there's no value for starting local workbench, since you cannot debug extensions locally currently.
95
+
96
+
Notice that we used the ```--nobrowser``` option, since there's no value in launching the local workbench since you currently cannot debug extensions locally.
97
97
98
98
Once it compiles the code without errors, it will serve the resulting manifest from http://localhost:4321.
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:
103
-
104
103
```
105
104
?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"d03ae0c2-bbbf-4cf5-9ff7-0986904553da":{"___location":"ClientSideExtension.ApplicationCustomizer","properties":{"testMessage":"Hello as property!"}}}
106
105
```
106
+
107
107
More detail about the URL query parameters:
108
108
109
-
***loadSPFX=true:** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework normally is not loaded unless at least one extension is registered. Since no components are registered yet, we must explicitly load the framework.
109
+
***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.
110
110
111
-
***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).
111
+
***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).
112
112
113
-
***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.
113
+
***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.
114
114
***Key:** use the Guid of the extension as the key to associate with the custom action
115
115
***Location:** the type of custom action, use "ClientSideExtension.ApplicationCustomizer" for the Application Customizer extension
116
116
***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.
117
117
118
118
119
-
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 in Site Contents page.
119
+
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.
120
120
121
-
Extend the URL with the additional query parameters defined above. Notice that you'll need to update the GUID to match ID of your custom Application Customizer available from **HelloWorldApplicationCustomizer.manifest.json** at the src\extensions\helloWorld folder.
121
+
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.
122
122
123
-
Full URL should be looking somewhat follows depending on your tenant URL.
123
+
The full URL should look similar to the following depending on your tenant URL:
124
124
125
125
```
126
126
contoso.sharepoint.com/Lists/Contoso/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"5fc73e12-8085-4a4b-8743-f6d02ffe1240":{"___location":"ClientSideExtension.ApplicationCustomizer","properties":{"testMessage":"Hello as property!"}}}
127
127
```
128
128
129
129
130
130
131
-
Click "**Load debug scripts**" button to continue loading scripts from your local host.
131
+
Click the "**Load debug scripts**" button to continue loading scripts from your local host.
132
132
133
-
You should now see the alert message in your page.
133
+
You should now see the alert message on your page.
134
134
135
135
136
136
137
-
This alert is thrown by your SharePoint Framework Extension. Notice also that since we provided 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.
137
+
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.
138
138
139
-
> If you are having challenges for making the debugging to work, double check the URL query parameters used for the query. Some browsers tend to encode the parameters in some scenarios, which will impact the behavior.
139
+
> 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.
140
140
141
141
## Next steps
142
-
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 place holders, 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 using the editor). You can continue to let it run while you go to the next article.
142
+
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.
Copy file name to clipboardExpand all lines: docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md
+4-4Lines changed: 4 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -135,14 +135,14 @@ Append the following query string parameters to the URL. Notice that you will ne
135
135
136
136
***loadSPFX=true:** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework normally is not loaded unless at least one extension is registered. Since no components are registered yet, we must explicitly load the framework.
137
137
***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).
138
-
***customActions:** this URL query parameter simulates a custom action. There are many properties you can set on this CustomAction object that affect the look, feel, and ___location of your button; we’ll cover them all later.
138
+
***customActions:** this URL query parameter simulates a custom action. There are many properties you can set on this *CustomAction* object that affect the look, feel, and ___location of your button; we’ll cover them all later.
139
139
***Key:** guid of the extension
140
140
***Location:** where the commands are displayed. The possible values are:
141
141
***ClientSideExtension.ListViewCommandSet.ContextMenu:** The context menu of the items
142
142
***ClientSideExtension.ListViewCommandSet.CommandBar:** The top command set menu in a list or library
143
143
***ClientSideExtension.ListViewCommandSet:** Both context menu and also command bar
144
144
(Corresponds to SPUserCustomAction.Location="CommandUI.Ribbon")
145
-
***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.
145
+
***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.
146
146
147
147
Full URL should be something like following, depending on your tenant URL and the ___location of the newly created list.
148
148
@@ -299,7 +299,7 @@ To ensure that our newly added **element.xml** file is taken into account while
299
299
300
300
## Deploy field to SharePoint Online and host JavaScript from local host
301
301
302
-
Now you are ready to deploy the solution to SharePoint site and to get the CustomAction automatically associated on the site level.
302
+
Now you are ready to deploy the solution to SharePoint site and to get the *CustomAction* automatically associated on the site level.
303
303
304
304
In the console window, enter the following command to package your client-side solution that contains the extension, so that we get the basic structure ready for packaging:
305
305
@@ -337,7 +337,7 @@ gulp serve --nobrowser
337
337
338
338
Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package.
339
339
340
-
Chose the gears icon on the top nav bar on the right and choose **Add an app** to go to your Apps page.
340
+
Chose the gears icon on the top navigation bar on the right and choose **Add an app** to go to your Apps page.
341
341
342
342
In the **Search** box, enter '**command**' and choose *Enter* to filter your apps.
0 commit comments