Getting started with modern client-side development in the SharePoint Framework (SPFx)
At the Future of SharePoint event Microsoft introduced the next generation of SharePoint which ushers a new way of developing customizations for SharePoint using the SPFx Framework. Many concepts in this framework will be new to power users as well as traditional developers as they were taken directly from the cutting edge of client-side modern web development. As a non-developer with many years of experience customizing the SP UI, I will walk you through the required concepts for getting up and running with creating custom functionality in the new SPFx framework. While not a deep dive on modern development in SharePoint, I will include several demos to get you started on your journey.
In this session you will learn:
- Introduction to Gulp, Yeoman, & Typescript
- Introduction to the SPFx Framework
[00:00:01] Welcome to getting started with the client site development in the SharePoint framework, I’m Randy Drisgill I work for Rackspace as a product engineering manager which means that I work with SharePoint Exchange Office 365 on a daily basis trying to make our offerings better for Rackspace customers consume and actually use.
00:00:29] Use the products more effectively. I’m also a Microsoft MVP for SharePoint server, and if you want to check out my Twitter or my blog or my LinkedIn they’re all over there on the right underneath of the 6-year-old photo of me back when I had different glasses and shorter hair and I was younger than the video that you see blut. So, what are we going to cover in this session. Hopefully, I’d like to give you an overview of the SharePoint framework and introduce how you get started working with the client side code in the new tooling that’s involved with the SharePoint framework, and basically just walk you through how to get your machine set up how to get a tenant set up and put together a Hello World web part.
[00:05:09] Back when I was doing in you know development for SharePoint 2007, you know 2010, 2013, we had a little external drive with VM ware on it that I was running a gigantic VM with all of this development environment that you would need including visual studio and everything. Gone are those days. Now you will be able to work on this whether you have a Mac or PC using common tools that are up and coming in the industry, and you can work offline with it. So, what can you do with the framework. Obviously, you could build client side parts in an office 365 developer tenant. That’s how it can be used today. Right now, it only works in an office 365 developer tenant you can’t use it on premises, you can’t even use it in office 365 in a first release Tenant it’s got to be a developer tenant. But that’ll change over time. At some point, they’ll release the code or they’ll push the code out to first release tenants all of them and then they’ll go out to all the tenants, and then someday in the future they say that they will have a way of pushing out the updates to SharePoint 2016 on premises as well so that the developer tenant part of that is just a temporary requirement. The web parts that you build with it will work in both the modern UI in office 365 as well as the classic UI, and the web parts are not meant to be used in production right now. You know the, that’s why they’re forcing you to use a developer Tenet.
[00:08:53] We start with understanding node.js which you can check out at.
[00:10:53] So worth learning a little bit about how NPM works to install things, but you don’t have to dive super deep into that. Yeoman is really a key aspect of the how the SharePoint framework was created by Microsoft, essentially Yeoman is a, it’s a tool that allows you allow someone to create templates for generating code and projects. And so, Microsoft uses Yeoman. They’ve created a template for what they feel is the best practices for starting a SharePoint framework web part. And so you don’t have to worry about setting up folders, and naming structures, and downloading you know parts of the framework things like that essentially when you want to start a new SharePoint web part you’re just going to type [email protected]/SharePoint and that all, kick off a whole cascade of activities you’ll see when I demo it that ends up with you having a project that has everything you need to get started with. You don’t even understand how yeoman works at all. The only reason why you would need to understand how a human works is if you ever wanted to create your own co-generation tool. And so, since you won’t be doing that, Microsoft has already done that literally all you need to do is you’re going to type [email protected]/SharePoint. Gulp is the next important tool in the tool chain. Gulp is a build a system that helps automate dev workflows so you can think of, gulp almost as if you used to come if you’re used to developing in other languages, it’s almost like compiling your code. You’ll use gulp throughout using the framework, it would help you to understand some of how gulp works but you don’t need to be an expert at it to use the framework, at all.
[00:18:46] Code editors. Microsoft did an excellent job, this go around with the framework of making sure that you can use a variety of very popular cross-platform Windows Mac Linux code editing IDs. Microsoft recommends either visual studio code, submit Adam web storm or visual studio 2015. They spent most of their time developing and testing the framework using Visual Studio code. I’ve started using Visual Studio code, I used to be a notepad plus, plus guy I was never a big visual studio 2015 fan. I thought it was too bloated and heavy and did way too many things. I find the visual studio code is pretty neat. It’s pretty lightweight. It’s got a good UI, you can bring in extensions. I think you’ll like it too. You could use it on a Mac, you can use it on PC. I recommend that for getting started with the framework you should try visual studio code, because that’s what Microsoft tested it with and that’s what the examples are built around, so check that out. That’s all I’ll be using in this, in the demos in this session. Probably the other biggest thing when it comes to using the new framework that you’re going to have to get used to is using a console prompt terminal window whatever you want to call it. You know get used to typing things like we used to back in the good old days of DOS in OSX and then all those type of things. You know feel sometimes like you’re in the matrix, that’s why I put this background on the slide but this is the way that modern web development has gone.
[00:20:36] People like the ability to have a lightweight typing based console, that they can spin up and spin down services and develop in etc. And so, that’s what this is all based around it’s not the, not really so much double clicking in windows and things like that. It’s more of typing in a in a console prompt. And so, there’s two tools that I recommend that can help with that, rather than just using the DOS prompt or the terminal on OSX. There is Commander ACMD are for Windows and there’s I term two for Mac. Sure, there’s hundreds of other options out there that you could use for this as well. Those are just a couple that I found to be really handy. I’ll be using the term two in my demos on my Mac so. So, what do you need to get started with your framework development. You’re probably going to need an office 365 tenant, since this you know you can get by with a local workbench but once you actually want to work with SharePoint you’re going to need to test it somewhere. And as it doesn’t work in on Prem SharePoint 2016 currently, doesn’t even work in a first release Office 365 tenant. You’re going to have to go set yourself up with an Office 365 developer tenant. It doesn’t even work in a regular tenant, it doesn’t even work in a regular tenant that you create a developer site and you have to go create a developer tenant. And so, there is a link here on the page bittleySPFX/devTenant which you could click on to start to request a definite they’re free.
[00:22:20] Anyone can create them you can create probably several of them if you have multiple email addresses.
[00:22:25] Go create one and then what you’re going to want to do once you have a dev Tenant is you’re going to want to create a app catalog which you which can be done from your Tennent dash admin SharePoint dot com.
[00:22:40] And then once you go into their go to apps app catalog and then you’re also going to run or create a developer site collection. So, from inside of SharePoint Online you’re going to want to go to ribbon new private site collections and you’re going to want to pick a developer site. So essentially all we’re doing is recreating or making it develop or Tennent we’re creating a developer site collection and we’re creating an app catalog for you to put your friend for you to put your web framework your shipment frame or code into. So inside of your developer Tennent inside of the document library there’s some work you have to do at this point to use the framework. These are things that you probably won’t have to do in the future once it rolls out to all the other frameworks. Essentially, you’re going to need to customize the document library and add a column called client side application ID. I’m not really sure why you have to do that but that’s in the instructions for getting started with the framework. The other thing you need to do is you need to download workbench SBX from get hub.
[00:23:57] Here is the URL to the Microsoft’s get help project essentially just right click on the wrong button and get hub. Save locally as workbench that SBX and then the next step you’re going to do is upload workbench.aspx to the document library in your developer tenant and you’re going to use that workbench in order to test new framework code inside of SharePoint and I’ll show you that in a demo a little bit. And then what you want to do once you get your tenant set up you’re going to want to set up your machine. You can use Mac or PC you can use Linux if you’d like but I don’t really know the steps for setting it up. In Linux, there’s extra steps you have to do. You can find those in the Microsoft docs for the SharePoint framework. You’re going to want to install node. Yes. You use the long-term support or LTE version. You’re probably going to want to install visual studio code to get started when you install node. It’s going to come with NPM and it might not come with the latest version of NPM. And so from a command prompt once you have all this installed Gillan’s you’ll type in NPM dash g to install something globally and then type install NPM at next and that’ll bring you to the latest version of NPM and just a bit of warning if you’re on a Mac you’ll probably need to type sudo before NPM and then type in your password. Otherwise it’s not going to run properly.
[00:25:35] At least have two on my Mac maybe my Mac is locked down more than more than yours is I don’t know. The other thing you’re going to have to install if you’re on Windows. You’ll need to install Windows build tools you can install that with NPM as well. NPM install dash dash global dash dash production windows dash billed dash tools build tools for Linux. You can click on the wiki link there later to get those if you need to. And then you’re also going to need to install Yeoman and gulp so you can install those both in the same shop with NPM. I dash G. Yo. Gulp. That will install both human and Gallio is for Yeomen Colpus for gulp and then lastly, you’ll want to install the yo the Youmen SharePoint generator templates that Microsoft created. You do that by typing NPM I dash G at Microsoft slash generator dash SharePoint that’ll get you the templates that you need to run in yeomen.
[00:26:44] And then once you have all that set up then you’re ready to go actually create some client side web parts. So, what does the devolvement workflow look like for the SharePoint framework. These are pretty much the steps that I’m going to walk you through in the demos for this session. You’ll start by creating a project folder that’s pretty easy then you’re going to change directory into that folder and you’re going to start your web but your web part by typing into the console window you know at Microsoft’s SharePoint that’ll kick off a huge process that installs a bunch of stuff. Including a hello world web bar and then you’re going to edit that web part with typescript in Visual Studio code then you’re going to test locally in the SharePoint workbench. Then after that works you’re going to test in an actual SharePoint tenant in your in your dev tenant of office 365 and you’re going to test it in the modern pages and as well as the classic pages. And once all of that works you’ll at that point everything is still loading from your personal machine even though it’s in office 365. In order to actually make your web part production ready and have the ability to give it to other people or put it in the actual SharePoint server you’ll need to deploy your assets to a CVN with a gulp.
[00:28:19] There’s some other options there you can do but that’s by far the most well documented option at this point. And then at that point you’re going to test your app using the Cdn based assets. And then at that point you’re done. You know that’s why I have the square there for fame and fortune and money. Assuming you make a good web part.
[00:28:42] So let’s jump in to a demo for starting a SharePoint framework where part so we’ve gone through the steps that I talked about in this slides where we set up our machine and we’ve set up gulp we set up Node and NPM and yeomen and we’ve installed the Microsoft human templates used all visual studio code and so we’re all ready to do some work. And so, what we’re going to do is we’re going to create a folder and we’re going to you know put our Sarto Web site part in it. And so, I’m on a Mac here. I could use the terminal but I’m going to instead use this term program that I really like which is I think is pretty handy.
[00:29:28] I’m going to do make dher in I’m going to say a new demo. I’m going to go see the new demo. It.
[00:31:04] So we’re going to pick that and then humans are going to go off and do a bunch of stuff that’s going to take a little bit of time depending upon how fast your machine is. I’ve seen some people’s machines go slow and some people’s machines go really fast on this but needless to say it’s doing a lot of stuff it’s fetching metadata it’s grabbing things from node package libraries it’s downloading them it’s making folders and file names and it’s adding gulping instructions all sort of to Microsoft’s best practices standards for creating a framework where part which is nice we don’t have to go download things from get help and do all that ourselves. Human is going to do it because they made a template for yeoman. And so, we kind of just sit back and watch and you’ll see there’s some warnings that come by on mine. The warnings are concerning. So, I mean that things have been deprecated and are needed and are out of sync or it ever. But as long as there’s not an error we’re good to go if you do get an error. Chances are you’ve got something set up wrong on your machine. I suggest you go back and reread the previous dabster or check out Microsoft’s get help project go through the tutorials and maybe even ask for help in one of the forums or something like that but chances are they should. After a little while come back with a success for you.
[00:32:32] So we’ll wait for that to happen.
[00:32:36] And get ready to hit the final part. NEARY Now I think.
[00:32:44] Yes. OK. And so, you see there’s a nice ASCII SharePoint logo says congratulations. New demos created it. Culp’s serve to play with it. I’m not going to do gulp serve just yet because I want to show you what got created if I hit LS You could see that a bunch of folders and files got created. If I type code dot it’s going to open Visual Studio code because we’ve already installed that and it’s going to open it up to the local directory that I’m in. So, I hit enter and upcoming Visual Studio code. I’m going to increase the zoom in so you can see things a little bit better. Here’s all the folders that were created and you could see that there’s a root folder with various config files. But the key folder is the source holder source web parts new web part demo. That is our typescript file which we can work with to actually code our web part. But let’s go ahead and run gulps her and see if we get on when that happens. So, if I type gulp serve it’s going to start up a web server and it’s going to bring up my web browser already loaded to the page and it’s going to show us what the web part looks like. It got serve you can see it spinning up some finishing some task is going to spin a web server. It’s going to bring up my local workbench which you may get a warning up here a little shield you can click on it and say you know go past the warning.
[00:37:17] And so here you can see some of these things are being imported from Microsoft SP client preview. So, that’s coming from the Microsoft’s good hub repository and bringing in libraries and then we’re importing styles from that style folder that style that I just showed you and we’re importing some strings that can be used to keep typing constants. And then we’re import importing part properties and then we have an export where we’re taking new demo apart and it’s extending based client side web part which is something that’s in the framework and then we have a public constructor that is also saying it’s inheriting from part context and then really Here’s where you have to start actually looking and stuff. Here is the public render function. This is where each L and variables are pumped out that show up on the screen right here you can see where it says welcome to SharePoint. It shows up right here welcome to SharePoint as well. I’ll type in something else right there. Just so you can see if I type. Welcome again to SharePoint. If I hit save on this conge option as can command us. You’ll notice that because the whole gulp runs as soon as I hit save the web page will recompile and reload for me and I’ll say welcome again to SharePoint so you can see our changes right away in the browser which is actually pretty darn cool. We used to have to like upload a web part somewhere and refresh and do all this stuff. Well not necessarily anymore.
[00:38:44] And so if we look down here there’s also some areas in the code where it’s bringing in properties that description which is where I typed into this box here and I said one two three and it showed up in their properties description is coming from the properties pane. This is what defines the property pane Here’s the header for the property pane where it says description. And here’s the group. And here’s the group name right here. You see group name. And then here is the description field where we have a label of a string and a description field label. And so, you see here this set up properties that description is bringing in whatever you put into this right here this description field. So, that’s how this part works. Basically, if we wanted to add some functionality to this we could what we could do is we could go in here and we can make a quick change to the page and we could say I’m going to Ticken this description line I’m going to copy it and paste an any of it and I change the color to yellow so that we can really notice it right away. And I’m going to type a string right here in this from. And then instead of property you start description though I’m going to bring in some other text I’m going to say context which is like the context of the page I say Doc when I say page context which is getting me the page context and you could see we’re getting some help here in Visual Studio. Code is telling me brings back the SharePoint page context when we hit dot. You can see I’ve got some options here I can bring back site user web.
[00:40:20] In this case I’m going to bring back the web and the web is the site that the page lives in. And I want to grab the title of the site that the page lives in. And so I hit enter there so I’m getting the title from the web of the page that we’re currently in and the dollar sign brackets is telling us to interpret that and put it on the page.
[00:40:41] So when I hit command s again it’s going to refresh my browser and you’ll see it’s coming from the local workbench which is pretty neat.
[00:40:51] And so it tells us that the name of this site that it’s running in his local workbench So next let’s test that same code in the actual office 365 SharePoint Online developer Tennent I have a developer tenant that we can try some things out on here and in my instructions before I said you had to go to get hub and you’re going to have to grab the workbench out asap x from the get hub project and uploaded into the document library. And so, that’s what we’ve got here. When I click on this it’s actually working very similar to what we had in our local work bantling now it runs in SharePoint. Again, you might get a warning and you see a shield up here I’ve already accepted mine. So, I don’t you don’t see it on mine but if you do get one just go ahead and accept it. And so just like before we can go in here hit plus and now we see all the web parts that are actually inside of my SharePoint site and the new framework we’re part that we just created right here called new demo. So, when I click that. We get the new web part on the page and it works very similarly. Now look it says developer site right there and that’s showing that it’s actually reading the site name. That’s what I called my site was developer site. So, that’s pretty neat We can test web parts right here and see changes immediately as well again.
[00:42:15] So like if I go in here and I get rid of the word again in the welcome to SharePoint and I hit save on that you’ll see here in a few seconds if I delete this. Yes, and I re add it to the page actuate of fresh maybe let’s say there we go. Welcome to SharePoint. So, this framework this workbench doesn’t automatically update but you can hit the refresh and see it. The interesting thing to note though is that this is still coming from my local machine. And so, if I go into gulp servanthood control to cancel hit refresh on this. You’ll see that I get an error. It’s because it can’t hit my local machine anymore. So, I go back here and I reload Gulp serve.
[00:43:07] And enter. Does a little bit of thinking.
[00:43:10] And it’s going to bring up the local workbench in a new tab I can close that. But if I go back over to this page that aired it refresh.
[00:43:21] You see our web part is in there again. So, next let’s check out a demo of testing that same part in a classic SharePoint page. We can do that the way parts the framework parts work in classic mode or to get into classic mode if we go over to our site and we go to site content.
[00:43:41] You can see if you go to the top you’ll see a paintbrush right there that I’ll tell you that your motter view you could click this to return to classic SharePoint. I’m not going to do that right here I have another window open in which I can show you know a classic mode site if I could site content here it’ll show you. The old view. So, in order to add our web part to classic view we are going to have to do some work.
[00:44:07] We’re going to have to make Lauretta deplore package’s solution into an espie app and add it to the App Catalog. And so, in the slides I talked about creating an App Catalog in your tent.
[00:44:20] I have one here in mine and if I click on apps for SharePoint normally you would probably have none there. I’ve already added an app to mine just to make this demo easier for showing but yours will be blank probably the way that you make one though is you go into the terminal. You break out of gulp serve again and you type gulp package Dasch solution. And that’s going to create a SharePoint app file. You could see right here created a file SharePoint up slash new demo espie app. And so, if we go over to Visual Studio code and we look at the SharePoint folder you’ll see new demo SB apps sitting there I can right click on it and say reveal in Finder and then there is the file. If I drag it into here I’m not going to do it in mine but in yours you just drag it in there and then it will say it will install it and I’ll say do you trust this app and if you do you click the diploidy and that deploys it to your answer and then to go into your classic page that actually use it you go into site contents here and you’ll go to add and add and then I’ve already done mine. And so, it doesn’t show up the same way as yours.
[00:45:40] For years it’ll show up here in apps you can add or you can look in apps from your org and it will be there you could say see here that mine says you can’t app the at the premiere and that’s cool I’ve already added it in your case you’re just going to click on it and then it’s going to go back to site contests and instead of just saying it’s ready to go here it’ll say installing the app and it takes about five to 10 minutes for it to install which can be very annoying. And so, that’s why I’ve already installed it here. And so, you just kind of have to sit back and wait. That’s how the cloud works these days sometimes. But once it stops saying that it’s loading and it refreshes and is fully coloured in here it’s ready to go.
[00:46:19] And so then we can add it to a classic page by going to add a page and I can say test page 2 here.
[00:46:30] Create a test page and then I go insert web part and then under custom is where all of your framework apps will be and you can see I have a few out there already. The one that we created is called new demo. And when I click that and click and you’ll see that it adds to the page and I just realized I forgot a step because you can see it’s not working like I expected to here and that’s because it still hits the local server.
[00:46:55] I have to type gulp serve again in order for it to load my local server. So, it’s going to do that really quick. They’re bring up a new tab. We can close that tab. But now what we could do is let’s delete this part and re-add it real quick. If we go in the search part custom new demo, click add and now we’ll see what part is working.
[00:47:20] And so how do you get to the properties panel you hit this little thing here and hit it. Web part and you’ll see this button come up that says configure when you click that you get the new view where you can start typing things in and see it over on the left just like you did before. And so, that’s pretty neat. That’s how we test a web part in a classic page. And then lastly, we will build that part for production so that we don’t have to have gulps Serb running all times on our local machine in order for our web or to work in production.
[00:47:54] We’re going to have to put our files somewhere on the web in a place where SharePoint can access them. And the easiest place to do that at this moment is to put them in a as your storage account into a. And use a CDN in azure to bring it up in.
[00:48:11] So that’s the way the docs tell you to do it at this point. And I’m sure there’s other ways to do it eventually but that’s the way we’re we would do it here. And so, to set some of that up it takes a little bit of effort and it takes going into it as your portal and setting some things up I already have mine set up. I’ll show you real quick kind of what it looks like before we go do it.
[00:48:35] This is my Azure dashboard here. The first thing you’d want to do is set up a storage account which is under you go New.
[00:48:45] And then you go data storage and then you would go storage account and you’d go and set up these options here to get a storage account.
[00:48:56] The next thing you’d want to do is set up a media and CDN and go to Cdn and create a CDN in the same resource group. And then once you have a CDN in the same resource group then you would go in and you would create go to the city any created endpoint in the way and then you’d go through here you pick some of these options you create an endpoint.
[00:49:23] I already have an endpoint created here you can see waffle CDN Azure edge dot net which points back to my storage group which is right here.
[00:49:34] And then in the storage group they’ll be storage blobs and then you all you could go into your access keys and that’s where you would get an access key.
[00:49:41] So you need to know you’re as your CDN and your access keys and you use those.
[00:49:49] You put those into your project and then you can upload it to your CDN. And so, the way we do that. Is. We go in here and we go to deploy as your storage and you’ll see here there’s a place to put your storage account name. And there’s a place to put your access key. So, for me I named mine waffle CDN and that my access key which. You guys don’t steal from me I’ll try to blur it out and I hit save on this and that sets up by. Has your deployment file. And then what I’m going to do is I’m going to go to the terminal I’m going to break out again and this time I’m going to type call.
[00:50:54] Gulp dash dash ship.
[00:51:01] That’s going to set some stuff up for shipping mode and then I’m going to do gulp deploy as your storage, and that’s going to do some work and push that up to the storage Tennet that I just created. And so now if we go over to back to the azure view here we click on Blob’s you’ll shit you’ll see one for do demo that was created in there and so you can see the info on it. Here is the URL for it. We’re going to we’re going to use that information in in one of the files in our project to set that up as well. We’re going to go into the right manifest file and we’re going to put the path in there.
[00:51:58] So here is the form that takes.
[00:52:00] It’s actually your L to your CDN that you created at Azure edge dot net and then slash the name of your project save that file and then what we’re going to do is we’re going to go through and we’re going to re compile the project one more time and move that out to the App Catalog.
[00:52:27] And so that we can we can see that change take place and hopefully it’ll pull from our CDN at that point.
[00:52:34] So go back to the terminal. We’re going to type gulp this timer type bundle. Dashed at ship so we’re going to make a shipping bundle of it.
[00:52:47] And then we’re going to type gulp packaged Dasht solution dash dash ship as well.
[00:52:58] That’s going to recreate our espie app file.
[00:53:01] That must be app. We already had out there if you remember correctly. We can find it by going right here and saying reveal and finder. We’re going to push step back up to the app catalogue. So, we’re going to go in here and we’re going to re upload it.
[00:53:17] We’re going to say replace it.
[00:53:22] At that point I should be able to go back over to the classic mode site that we just used. And we should be able to refresh the page.
[00:53:33] And if all went well our web park shows up in there. But notice that gulp is not running great here at the terminal free at this point. It’s hitting our seat in if we want to make updates to it we’re going to have to update those files that are in the CD and every time. But that’s how you would get a framework where part working in production without having to have your local server in the mix. So, what do you do from here. Next steps. You could learn how to import libraries like Jake Query or Jay a UI and you can learn more about that.
[00:55:53] Hopefully you learned how to get started with the framework. We just barely scratched the surface but there was a lot to cover and so you know you’ve got a hello world app that’s work in. Next steps would be to learn how to work with lists and Jake queries and things like that so good luck with that. I’ll check on all of you later. See
This session was delivered at the Collab365 Global Conference 2016 and was presented by Randy Drisgill.