Recently Microsoft have released the new Client Side Web Part technology with the new SharePoint Framework (AKA SPFx).
In this article I’m going through the steps on
- How to create a Client Side Web Part
- How to create a CDN in Azure
- How to add the Client Side Web Part to your new modern pages
- How to add the Client Side Web Part to your traditional SharePoint pages.
I’m starting with creating a folder on my PC called SPFx
Then I’m adding a folder for my Web Part project “MyClientSideWebPart”
Create the base project
Table of Contents
Now it’s time to pick up the base project structure. This is done using Yeoman. Within the same Command prompt simply type:
yo @microsoft/sharepoint
I’m looking forward to the moment that all of this can be done within Visual Studio. Although you will probably find that by the end of this post that there isn’t a need for the full blown Visual Studio at all. Simply use Visual Studio Coded instead. You can even use Visual Studio code for all your debugging.
Anyway, better continue with the creation of the project. So in the above prompt I’m going to hit return. I’m happy with the suggested project name. Isn’t it magic? Yoeman looks at the parent folder name and suggest a project name.
You can create a new folder for the project, however I’m going to stick to the root folder
Now there is a choice to make. Do you want to use React, Knockout or neither of these. I’m going for the default No JavaScript web framework.
Now I’m asked to supply the web part name. So I type: MyClientSideWebPart
And then the description
Once I’ve supplied the description the magic is all starting:
A lot of files are created and a successful message will appear. The many warning messages can be ignored. At least I ignored them and they don’t seem to be reporting any major issues.
So what have we got?
As stated in the successful message I now started by running
gulp serv
This opens a browser pointing at
https:/ /localhost:4321/temp/workbench.html
Workbench is a page that in this case lives locally on my PC that looks like a modern Office 365 page and lets me add web parts.
So I click on the plus sign to add a web part and select my MyClientSid… web part. So in future I might want to think of nice short names for my web parts.
Once the web part is added my page looks like this:
Ok, that is nice but I would like to add this web part to a real SharePoint page and I don’t want to run this from https:/ /localhost:4321
Creating the CDN
I’m going to create CDN in Azure. I must say that I find Azure extremely confusing and it is difficult to find the right options. So I’m going to document all the little steps that are needed here. First I logged on to portal.azure.com
I’m starting by creating a storage account.
I click on the big green +
Then in Storage I select Storage account – blob, file , table, queue.
Then I complete the little form that appears. starting with a name. Not that you can only use small letter s here.
So I’m going for myclientsidewebpart, for the rest I’m going to leave everything to the defaults.
Although not absolutely needed I tick the box Pin to Dashboard. It just helps finding things back.
After a while you should get the details of the storage account to appear:
The Blobs button (or whatever it is) already seems to be selected. This is the one to click.
Then in the top menu I added a container.
In the form that appears I supply the name and select Container:
Aahhh again, only lowercase characters. So after correcting the above I got the right result. Even thought the container is n’t listed immediately in the overview.
Going back to the Storage account overview, there is an option to get the access keys:
Simply copy one of these keys as we will need these later.
I go back to the big green +. Select Web + Mobile and then click on CDN
This gives me a small form to fill in:
then within my CDN profile I add an endpoint
for the name I use : myclientsidewebpart
The origin type has to be storage.
and in the Origin host name I’m selecting the myclientsidewebpart.blob.core.windows.net as I supplied earlier in my storage account.
After a few minutes the end point will be available ( at least in my case it is)
Ok, so now all the Azure work has been done! Now we can go back to our web part code.
I’ll start by having a quick look at the folder structure that was created by Yeoman earlier:
Hmm, no project or solution file. Time to start Visual Studio Code and open the folder:
We’re now going to look at a few files in this project starting with the deploy-azure-storage.json
{“workingDir”: “./temp/deploy/”,“account”: “<!– STORAGE ACCOUNT NAME –>”,“container”: “my-client-side-web-part”,“accessKey”: “<!– ACCESS KEY –>”}
Loading the web part from the CDN
Next file in the config folder is write-manifests.json. This file contains the location the the web part.
{“cdnBasePath”: “<!– PATH TO CDN –>”}
Now we need to supply the url of the CDN endpoint
https:/ /myclientsidewebpart.azureedge.net/myclientsidewebpart/
Note that the last part of the above url (myclientsidewebpart) is the blob container name.
That’s it! All the Azure configurations within the project are sorted out.
Deploying the web part to Azure
To dpeloy the solution to Azure there are two steps:
- prepare to ship
- deploy
Now we have to go back to the Command prompt:
running
gulp –ship
Then
gulp deploy–azure–storage
So far we have completed all the azure configurations and made the web part available in the CDN.
But, how do we now add the web part to SharePoint?
Like in the olden days, we need to create a package file. This is done using:
gulp package-solution --ship
If you want to run the webpart using https:/ /localhost for debugging purposes you can run gulp package-solution without the –ship option
I now have a package file created within my project folder -> sharepoint -> solution
This is the package file that needs to be added to my SharePoint app catalog:
Then I drag this into the store and accept the trust:
Ok, so now SharePoint knows about my web part.
Time to visit my SharePoint site and add the web part to the page. Starting by adding the app to my site:
And the web part can be added to the web part page:
[…] my adventures with the new web parts I ran into the following error when I added my web part to a […]