Develop a client web part in the SharePoint Framework - a walk-through

I covered an intro to the SharePoint Framework in my previous article The new SharePoint development model – JavaScript frameworks, npm, Gulp, TypeScript, client web parts etc., so now let’s now take a closer look at developing a client web part (something most developers will do commonly). We’ll walk through the web part creation process and start to look at the various config files, and also cover things like bringing in a JavaScript library such as jQuery, incorporating CSOM code, and dealing with async operations such as fetching data and so on. I’ll link to separate articles for many of those, since they deserve some decent coverage. We’ll also consider the “what now?” moment, when you have the default code running and need to start adding your own.

Remember – this is simply *sample guidance* at this point to help you prepare. Some details WILL change before release!

I can’t emphasize enough that you shouldn’t take anything in this post as gospel. At this time (May/June 2016), the framework is still not in official preview and things WILL change before most folks get their hands on things. The Framework pieces shown here come from working with the product group at a private “dev kitchen” event. Still, I think there is benefit of having a heads-up of what the development process looks like – most developers I know like to see the moving parts to understand a technology stack, so hopefully this helps folks prepare. Even if only mentally!

Getting started - creating a client web part “project”

Seasoned SharePoint developers are used to opening Visual Studio and doing File > New > Project > and selecting one of the SharePoint templates, even if just an empty SharePoint project, or adding an item to an existing project using Add > New item > SharePoint > Empty element or similar. However, in the SharePoint framework we don’t need to use Visual Studio and the Yeoman Generator is used to get us started with the right files. This works from the command-line, and isn’t tied to a particular code editor such as Visual Studio. So, we need the following installed:

• The Yeoman Generator itself
• A template for a SharePoint client web part – this will become available when the tools are released

We open a command line in the directory we want to use, and we will run the Yeoman Generator to drop the right files into this directory. We tell it the name of the generator to use – I have one called “@ms/sharepoint” (from the preview bits I have access to – final names might change). This is effectively a “templated set of files”, and these templates will be supplied by Microsoft (but the community will add additional ones no doubt):

The generator will ask me some questions in order to provide the right scaffolding (and note the dev kitchen references illustrating that these are preview tools), and then starts unpacking some files into the directory – especially the “node_modules” folder used for JS dependencies:

I am then asked if I want to create a client-side web part or full page application  – I’ll select the first option here:

After some further information gathering on my web part name and description (highlighted with red box below), some core files are created in the directory (see yellow box):

The generator completes, and now I have some boilerplate files in my folder, including some “Hello World” code in the main web part file. I can now open these in a code editor, examine them, and start implementing some real code. To open this folder in Visual Studio code (and remember it’s just a folder, not a VS project or anything), I can type “code .” – the dot tells VS Code to open in the current folder:

Now we see our files. The main sub-folders to be interested in are the “config” and “src” folders, highlighted below:

x

Usefully, this is a working sample and as shown in the last post, I can run this in the local “workbench” environment which has no dependency on SharePoint. To do this, I run “gulp serve” from the command-line:

This will execute the Gulp task named “serve”. This is defined in the tooling, and it’s job is to spin up node.js on your local machine to allow the files to be served (as an alternative to IIS) – the default URL is based off http://localhost:4321. A browser window is also opened onto the workbench page, and all this is logged in the console:

In the browser window which opened, you should see an instance of your web part added to one of the the new style pages. The content displayed will match the boilerplate HTML code which was shown earlier:

If we go to edit the web part properties, we see the single property which the boilerplate code defines to help us get started:

Here's what the boilerplate code looks like for the web part:

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

Early challenges when adding your code

So we now have some boilerplate code and we’ve tested that in the browser. But now the fun starts, and we really need two things:

• To understand how to start adding code, to implement the specific functionality we plan to build in this web part
• To understand the various folders and files provided by the SharePoint Framework – in other words, understanding the SharePoint Framework  development model

Adding code

Looking at the boilerplate code, you can see the main entry point to a client web part is the public render() method provided by the SharePoint Framework. A DOM element representing the web part’s container on the page is passed as a parameter, and it’s up to you to output your content in there – using whatever approach you choose. You can see then, that this is a massive formalization of the “JavaScript embed” approach that many of us have been using via a Content Editor web part or Script Editor web part – where basically the web part emits a DIV onto the page, and some companion JavaScript then populates that DIV. The big difference, of course, is that things are baked-in and we now have proper framework support. We get all the things long-time SharePoint developers would expect from a web part framework – support for web part properties, a web part manager object to help manage web parts on a page, context data such as whether the page is in edit or display mode and so on. But we also get other things - support for loading resources such as CSS, a logging framework, and various helpers for common needs (such as making a GET/POST request).

So, it comes down to whatever we build around that render() method. For non-trivial web parts, usually you’ll create additional TypeScript modules so that your core implementation of fetching data (or whatever) isn’t in presentation code, and if you’re new to TypeScript even that can be “fun” the first time! As I was creating my first client web parts, I hit challenges such as these as I was building out my code:

• How to add additional TypeScript modules to better structure your code (and consuming this code in your web part class)
• How to add jQuery or other JavaScript libraries to your web part (including TypeScript typings for code completion)
• How to add CSOM to your web part (again, with TypeScript typings so that CSOM is easier to write)

I plan to cover all those in future articles.

Understanding the SharePoint Framework files and folders – an overview

At this point it’s worth thinking about the files and folders we are working with:

Here’s a cut-down version of a table from my next post – I’ll go into more detail there, but here’s an overview of the folder structure used:

Folder	Purpose
src	The place where you add/edit code files
lib	Contains “processed” code files which are ready to move into the bundle which is distributed with the app.
dist	Contains the final code files which are distributed with your application. The most important file is the final JavaScript bundle file  [MyWebPart].bundle.js
config	Contains a set of JSON files used by the tooling for the build process. In particular to control how your app is packaged - in terms of the .spapp file, JavaScript/CSS bundling and so on.
node_modules	Contains JavaScript modules used by your code or the SharePoint Framework. Some may be loaded at run time, but others may be used at design time only (e.g. by TypeScript code).
typings	Contains TypeScript typings files – these are used to give you auto-complete (IntelliSense) against JavaScript libraries you are using (e.g. jQuery).

 

Summary

There are a few things to get used to when developing in the new SharePoint Framework. The process to create custom code is different (and doesn’t even need to involve Visual Studio!), and the files and folders SharePoint developers will work with are different. I’ll continue digging into things in my next post Understanding the web part manifest, bundle.json and other key files and folders in the SharePoint Framework (published soon!)