Wednesday 4 May 2016

The new SharePoint development model – client web parts, JavaScript frameworks, npm, Gulp, TypeScript etc.

In my end-user focused companion post Overview of the new SharePoint – modern team sites, pages, web parts and applications, I talked about the overall set of changes coming to SharePoint, but here I’m focusing on the new development model. I spent time with Microsoft engineers building the framework at a fantastic “dev kitchen” event earlier in the year, and have been playing with bits and forming thoughts since. I’ll cover an overview of the framework, and talk specifically about new building blocks – we’ll focus on client web parts, but will also touch on full page client applications that are also coming. To get started, even developers are visual people so take a look at what you’ll be working with in code terms in the editor (and note this is Visual Studio Code, the lightweight/free code tool that Microsoft now have):

SNAGHTML23253fb7

Whoah, that looks pretty different to SharePoint development as you’ve seen it before! A couple of quick observations before delving deeper:

  • That code is TypeScript code – these files have a .ts extension, and get compiled down to JavaScript by a tool.
  • The project structure is different – the “src” directory is where you edit your files, the “config” directory holds a bunch of config files (that we’ll walk through later) and so on.
  • We have lots of new files. There’s a new web part manifest file (the new equivalent of a .webpart file), new config files to control how bundling works, what happens in the build process, how the solution gets packaged and more.

This is SharePoint development, but not as you’ve known it before!

Key aspects for developers

I’m condensing a lot of information into this list, but I think these are the key takeaways:

  • Client web parts and client-side applications are the new building blocks. As discussed in the last post, these go along with the new page model.
  • It’s a JavaScript world baby! Config files are in JSON, and code is implemented in JavaScript on the client-side.
  • The packaging of artifacts is different! There are new manifest files to learn about (e.g. a web part manifest), and other files such as bundle.json, package-solution.json, upload-cdn.json and more. Gulp tasks are used for packaging.
  • Files for your web part or app can live anywhere (e.g. a CDN, or a website you host) - they don’t have to live in SharePoint. Anywhere that can be accessed on a URL by the end-user basically.
  • The “local development” model is very different – Gulp and node.js are used to host files locally, so you don’t need to use IIS on your local machine. A special “workbench.aspx” page is used to support this.
  • No particular JavaScript framework is mandated – you can use Angular, React, Knockout, Handlebars or whatever you like. The one thing to consider is that React will already be on the page as it’s used by some SharePoint components, so that’s one less file to download the first time users hit your site or customization – useful, but probably not a massive factor for intranets though.
  • You should consider learning TypeScript – at least the key parts such as modules, the type system and so on.
  • You no longer NEED to work in Visual Studio - if you prefer another tool (e.g. because you’re not a “career” SharePoint developer), that’s fine. Other lightweight code editors such as Visual Studio Code or Sublime are now 100% viable options because the packaging of artifacts is different. Even I (as a 10 year SharePoint developer) have started to prefer using VS Code, even if some bits are slightly painful initially.
  • SharePoint Webhooks – these are the new “event receivers”. This is a move towards a more standards-based approach to responding to changes in SharePoint/Office 365.
  • The App Catalog is used as a packaging and registration method – both client web parts and client-side applications are packaged in this way (moving away from the web part gallery we’re used to)
  • Page security needs some consideration – because anything on the page can theoretically access anything else (e.g. by scraping the DOM), that could raise some interesting questions when the user’s mail is shown (for example) and web parts from different sources/vendors are present. To counter this, some operations are blocked in the new framework but other governance may be required. More on this in the future.
Whoah, why all these changes? Do I have to use this new model?

The driver for the changes on the dev side is the new page and web part model. As discussed in Overview of the new SharePoint– modern team sites, pages, web parts and applications, the user experience of working with SharePoint pages and web parts has never been the slickest, and there was a lot of baggage from earlier SharePoint versions. So, since Microsoft were making big changes to the page model it also makes sense to move to modern web development approaches too. Yep, it’s interesting that things aren’t wholly based on MVC, but I’d argue most developers are choosing client-side approaches instead these days.

Do I have to use this new model?
 

No. This evolution of the development model doesn’t replace existing options (e.g. provider-hosted apps, use of JavaScript embed approaches etc.). However, if you choose to implement your solution using the new building blocks (especially the new pages and web parts), then you *do* need to adapt your skills and approaches.

What about TypeScript? Do I have to use that?
 

No, but at this stage I recommend it. The version of the dev tools used by those of us in the preview *is* oriented around TypeScript, and frankly things are just easier if you write TS code and allow it to be compiled down to JavaScript. There may be other options at the time of general availability, but there’s a lot of love about TypeScript once you get used to it. There is a learning curve, but I recommend getting into it personally.

Client web parts – a simple example

Let’s take an overview of a new web part solution. In my example here, I’ve created a client web part which displays the last 5 documents you have created or modified. It runs a search query using the Office Graph extensions (actors and edges) to do this. To keep things (relatively) simple, I’m choosing NOT to use React, Angular or another framework to build on for this first example. – I do use TypeScript though, and I also use TypeScript’s ability to do simple “JavaScript templating” with string literals and parameters though. Here’s the structure of my core files – the main bit to focus on is the “src” directory, since these are the files that get edited:

SNAGHTML17b59b5

I’ll provide a detailed walkthrough of files outside of the “src” directory and their purpose in a post coming very soon. The main code files in my example are:

File Purpose
CobRecentDocsWebPart.ts The core web part implementation (in TypeScript). Has a “render” method which is called by the page framework.
Search.ts Encapsulates the code needed to call the search REST API with the right parameters.
SearchResult.ts A simple class to represent the core properties of a search result that I’m interested in here – Title, Description, URL and file icon.

These files all get compiled down to JavaScript by a Gulp task provided by the developer tooling – this is the equivalent of MSBuild tasks used by Visual Studio to compile DLLs or build WSPs. Here’s what the core code looks like for my web part – from this you can get a heads-up of things like:

  • The TypeScript side of things
  • Referencing other TypeScript modules
  • The web part framework – interfaces and methods, how rendering can work etc.
  • Understanding context – whether the code is executing in the test workbench page or a real environment
  • How to define web part properties

But remember! This is preview code only, and some of these files and the surrounding “dev toolchain” may change between now and when the framework becomes generally available – all discussion at this point is partly just for illustrative purposes!

Once I’m ready to test/debug my code (and usually you’d do this WAY before you’ve added so much of your own code), you can see what things look like on your own machine by running “gulp serve” at the command line in the folder where your files are:

 gulp serve

This does a couple of things, all taken care of by the developer “toolchain” that Microsoft give you (so long as you have the prerequisites such as node.js installed):

  • Runs build tasks to package up your files for runtime – this includes pre-processing any TypeScript and/or React if you’re using those, processing web part manifests, running any JavaScript tests you have, and finally combining your JS and CSS files into one bundle.
  • Starts an instance of node.js to run the JavaScript files in a browser – no SharePoint or IIS needed for this, and there’s a “live reload” facility so that you can edit code and immediately see changes reflected in the browser (the page is automatically refreshed when you save a code file).

This launches a “workbench” page which hosts all your client-side files. So long as Gulp and Node are serving your JavaScript files, you’ll be able to add your custom web part to this page:

SP workbench - add client web part

Your web part will then appear on the page and you can use browser tools for debugging etc:

SP workbench - add client web part 2

You can edit web part properties in the new property pane (I’ve added some custom ones for my web part here):

COB client web part - recent docs - wp props

But I need “real” SharePoint!

Of course, the local workbench page helps you get up and running and build presentation code, but sooner or later you’re probably going to need to see your web part in the context of a real SharePoint environment (e.g. so you can access data, call search/user profiles/taxonomy, or whatever). As you might have noticed, it’s possible to write code to detect the host environment and use dummy data if you’re running on localhost. The Workbench.aspx file provided by the toolchain can simply be uploaded to an Office 365 tenancy though, and again, so long as your files are being served you can add your web part to that page. This time, you can interface with real SharePoint things such as search and test your web part with real data – now my web part finds files in my Office 365 sites:

COB client web part - recent docs

Deploying to production (e.g. deploy to CDN)

Once we’re ready to have our web part used in test or production, we need to move away from the locally-hosted model. Now the JavaScript, CSS and any other files needed at runtime need to live in a location which can be accessed by all users – this can be a CDN, a simple website such as an Azure web app, or any other location of your choosing. You *can* continue to deploy to SharePoint libraries (e.g. Site Assets) if you choose, but now we have an option which moves us away from needing key files deployed (and duplicated) in each site collection – woohoo! You are responsible for providing this location (unless you’re choosing SharePoint)

The preview developer tooling I’ve been playing provides some support for deploying to CDN – this is in the form of a Gulp task, which deploys to Azure BLOB storage/CDN based on a config file. Your manifest files need to be updated to point to your CDN URLs, but things basically are straightforward in terms of deploying assets to a production-ready location.

I’ll delve deeper in other blog posts, but remember that the framework isn’t available yet. You’ll be able to get your hands on things later this summer. 

Client applications 

As well as client web parts, let’s touch briefly on client applications. These are coming later in the year, and in the same way that client web parts offer a JavaScript-only version of web parts, client applications do a similar thing for full page apps. I summarized the flavors in my previous post like this:

  • Page-based apps – an alternative to provider-hosted apps (which remember, are implemented with server-side code).
  • List-based apps – think of these as an alternative to JSLink for transforming the display/edit/new experience around list items

Client applications are implemented purely in JavaScript, but have benefits such as having full “context” and using the Office 365 suite bar etc. There is a framework or scaffolding page in your SharePoint site/Office 365 tenancy, but the main page body is implemented in your JavaScript/HTML/CSS. It’s pretty easy to understand the page-based apps, but the list-based flavor is interesting too. Recently I’ve worked on several mini-applications which provide a custom interface, but store their data as items in a SharePoint list. We built a page which takes a URL parameter for the item ID, and then issued a REST call to fetch the data and build the page around that. One example was a “office locations directory”, where the locations were stored in the list but we provided a nice presentation with an embedded map, particular layout of the data elements and so on. You can consider list-based client applications as a formalisation of that – it will be quicker and easier to build such solutions, almost in a “JSLink on steroids but without the proprietary display template framework”-kinda way. Nice.

Summary and other resources

So, we now have a page and web part model that’s fast, lightweight, simple for end users, and nice to develop on. There are also new ways of solving common requirements around building mini-applications, but in a way which moves away from the very SharePoint-y building blocks such as JSLink and display templates that we had in the past, to a way where the implementer can choose how to build the UI using the approaches of their choice. Additionally, we now have an open development model more in line with the rest of the world, and great support for quick development without the need for Visual Studio and where much can be done without even having access to a SharePoint environment. Kudos Microsoft!

In future posts I’ll provide a more detailed walk-through of the framework and it’s key files.

Other resources:

16 comments:

Unknown said...

Developers everywhere are rejoicing. But I didn't see any mention of iframes. Are they still the delivery mechanism for the client web parts like app parts?

Chris O'Brien said...

@Lester,

Great question. The answer is....NO! IFrames are not used in client web parts (or client applications), and that was one of the drivers for the framework. They aren't necessary in this model, because it's basically a formalization of the "JavaScript embed" approach.

That said, app parts and their IFrames might STILL be the right choice sometimes. If you're developing something which can access sensitive data and you don't want to put that in the DOM where other (potentially untrusted) parts could access the data - well, that's exactly what the app parts/IFrame approach provides.

Cheers,

COB.

Unknown said...

very useful Chris, thanks!
What's the story in the SharePoint framework if you have a scenario that needs to run some code with elevated permissions and not current user? Is it a matter of hosting and consuming a web service (e.g. Asp.Net web api) and leverage CSOM under some elevated account or anything new? Will CSOM be still relevant in the future ? :)

Chris O'Brien said...

Hey Hrayr!

Yep, as you realise, it's just JavaScript running on the client so there is no elevation of privilege possible there. All client web parts and client applications will run in the context of the current user. If you need to call a service with higher permissions, it will generally need to be a server-side thing, like a call to a WebAPI service which uses a different identity (as you mention).

That's one option, but that's another scenario where you could feasibly choose to use the add-in model instead. This probably underlines the fact that the new framework doesn't replace the existing options, it just adds to them.

Cheers,

COB.

Shafqat Nawaz Balouch said...

Excellent Chris!

Nikolas Charlebois-Laprade said...

Chris, once again, thanls for putting out such a great article. Great work buddy!

George said...

Hi Chris, thanks for the great information. Is there a roadmap for this coming to on-prem? Many thanks.

anoop said...

Great post Chris. Can you please let us know if in future, by using this new model, we will be able to provision sites with pages having the client web parts in them? (Like a site template).

Chris O'Brien said...

@George,

So far, Microsoft have stated that the SharePoint framework *will* come to on-prem SharePoint in 2017 through "feature pack" updates. No doubt more detail will arrive between now and then.

Hope that helps,

COB.

Chris O'Brien said...

@Anoop,

It's a good question, but I'd expect so. There's *always* a need to add pages with pre-defined web parts after all, so I think it would be slightly crazy if there was no declarative or code-based way of doing this. Let's see!

Cheers,

COB.

Ova (Excuse My Reading) said...

Thanks for the article. A bit depressed that there is still SO MUCH to learn, but at least there is going to be more and more JScript. yay!

Unknown said...

Thanks Chris great post! Are master pages still used in conjunction with the new page / part model? I'm wondering how customers who implemented branded publishing portals (intranets?) using custom master pages will be impacted.

Chris O'Brien said...

@Jason,

Actually some of the details around the "next level up" from what happens on individual pages haven't really been announced yet. However, I think it's fair to assume that publishing sites will continue to use master pages and page layouts - or at least, something that provides that function.

Cheers,

COB.

Unknown said...

@Chris,

I feel they are going to repeat their usual mistake.
Make a seemingly cool function, promise the world, implement, leave out key functions.

A great example is Multi language.

Though I love that many Bloggers like you are giving us this valueable Information.
Microsoft should put some more effort into spreading the word themselves.

Aru said...

Hi Chris, thanks for the great post. Any update for the production tenant release dates?

Chris O'Brien said...

@Aru,

Should be around the end of the year I understand. Let's hope :)

Thanks,

COB.