Tuesday, 11 April 2017

Speaking at SUGUK London on SPFx dev – April 20, 2017

Next week the UK SharePoint user group (SUGUK) is holding a developer evening at Microsoft Paddington. I’m looking forward to taking part, and will be giving my “Pitfalls in SharePoint Framework (SPFx) development” talk. It will be nice to have a developer focus to the event – there’s a lot of change in the dev landscape at the moment, between Azure Functions, Teams extensibility, modern sites and pages, to the overall shift that the SharePoint Framework brings with it’s emphasis on npm, gulp, TypeScript and so on. My esteemed fellow northerner Bill Ayers is giving the other session – he will open with “Welcome to the brave new world of SharePoint and Office 365 development”. This should be a good intro to the overall topic of the SharePoint Framework, which will lead into my deeper-dive into real world pitfalls and how to avoid them.

The details for the evening are:

SUGUK developer evening

When: 20/04/2017 from 6:30 pm - 9:00pm
Where: Microsoft, Paddington (https://www.microsoft.com/en-gb/about/ukoffices/london-paddington/)
Agenda:

  • 6:00pm – Welcome/registration etc.
  • 6:30pm – Bill Ayers : “Welcome to the brave new world of SharePoint and Office 365 development”
  • 7:30pm – break
  • 8:00pm – Chris O’Brien : “Pitfalls in SharePoint Framework (SPFx) development”
  • 9:00pm – finish/SharePint

You can sign up here – http://uk.communities.tech/events/sharepoint-user-group-london-developer-night/

Topics I’ll be covering include npm, dependencies, re-use of existing JS code using modules, SPFx security, bundling and more.

image

Unfortunately the event doesn’t have recording or streaming facilities, but if you’re in the area it would be great to see you!

Wednesday, 5 April 2017

An intro to Power BI for the Office 365 developer – slide deck

I’ve been working with Power BI a bit recently, and it’s a really interesting world when you come at it from a dev perspective. You can accomplish things quickly that would take a LOT of code, and it’s pretty impressive that way. For a long time I felt somewhat guilty that I had a skills gap with Power BI (“call yourself an Office 365 architect, you can’t even configure a slicer!”), but happily I’ve now gained some knowledge and now sleep better on that front ;) I think it’s easy to overlook Power BI and assume that you need to do custom dev work to meet some client requirements around presenting data – but often it’s possible to flip things around and say “what if we gave you something like this, and it would have benefits X, Y and Z?”

The key highlights for me are:

  • A decent grid control, with sorting/filtering, mobile support etc. – with no code needed to fetch data and bind to the grid
  • Easy charts – and lots to choose from
  • Easy maps
  • Great mobile support
  • Can embed within a web page (e.g. via the SPFx Power BI web part)

To work out whether Power BI is a good fit for your requirements, I summarise it with this slide:

image

The lessons you learn – visuals, filters, slicers…and publishing to a SharePoint page

I felt like I learnt a few lessons as I got started. I even managed to burn 2 or 3 hours fiddling around with the wrong bits after downloading the wrong thing (hint – it’s Power BI desktop you need, not the app in the Windows store!) It also took me a while to get to grips with the basic process of adding visualizations to the report, and getting the controls to work with each other (e.g. selecting an item in a pie chart to filter rows from my data). I tried to capture some of these learnings for a “lunch and learn” chat with my team, but hopefully the slide deck might be useful to others starting out with Power BI.

It’s also particularly interesting now that it’s so easy to embed a Power BI report to a SharePoint page. In case you didn’t know, Microsoft have a new web part which supports this, although it can only be used on modern pages:

image

Just remember that all users need to be licensed appropriately to view the report (i.e. they need an E5 license or a Power BI Pro add-on license, as things currently stand). If that doesn’t work for you, there’s always the “publish to web” option if you’re OK with an anonymous access “everyone can see my data” approach:

image 

The presentation

Anyway, here’s the slide deck in case it’s of use:

 
Happy data presenting!

Tuesday, 14 March 2017

Provisioning modern pages and SPFx web parts

So the SharePoint Framework (SPFx) is now available in all Office 365 tenants, and using SPFx for web parts you’re developing now is a sensible option. After all, we now have “modern” SharePoint sites and pages to consider, and the matrix of what can be used where looks like this:

  • SPFx web part – classic pages AND modern pages
  • Classic web part – classic pages only

That alone should tell you that most new development should be done using SPFx. As a reminder, any SharePoint site that is attached to an Office 365 Group is a modern site, and any old SharePoint Online site that has existed for a long time now has modern pages (it’s the default now when a new page is created). Some time in 2017, I think we can also expect a new framework for publishing sites, and so the overall message is that any web parts you develop with “classic” approaches will have fewer and fewer places they can be used.

However, SPFx initially had a few things missing on the provisioning side:

  1. Ability to add a custom SPFx web part to a page programmatically (or in some other provisioning sense e.g. PnP provisioning XML)
  2. Ability to add one of Microsoft’s out-of-the-box SPFx web part to a page programmatically (or with PnP provisioning XML)
  3. Ability to automatically add an app to a site, so that any SPFx web parts (or other artifacts) are available
  4. Ability to create modern pages programmatically
  5. Ability to create modern site collections programmatically

So, lots of site templating scenarios had gaps in the new world.

The good news is that Microsoft have taken the first steps in closing these. Effectively, items 1, 2, 4 and 5 are now possible. Yes, there are still things that may get in the way of meeting client requirements for SharePoint team sites, but things are progressing and hopefully these will be closed soon.

Specifically, the bad news is that as far as I can see, the lack of item number 3 in the list above means it’s still not possible to provide a template for a SharePoint site which has a home page with certain modern web parts. That’s a shame because that’s a common requirement for us – most collaboration solutions we develop involve team sites which are lightly customized, but that would usually include tweaking the home page to have the most appropriate set of web parts. Here’s a summary of what happens:

Provisioning custom SPFx web parts to pages
At the time of writing (March 2017), any *custom* SPFx web parts you build only become available when the app is *installed to the current site*. I was hoping this wouldn't be the case, and my understanding is that "soon" there will be other options for rolling out web parts across a tenant (to avoid the need to install the app). At least, this should be possible for web parts which don't provision other artifacts, such as a supporting list. But for now, you must install the app to the site, once the app itself has been made available by uploading the .sppkg file to the App Catalog. There is currently no API to facilitate app installs, and the traditional approach to tenant-scope deployments does not work.
 
Additionally, PnP does not currently support provisioning SPFx web parts to pages using an XML template. For now, you have to write code.

So, depending on your requirements you might need to do some “post-processing” of sites once they have been created to get to where you need to be.

Getting started with PnP methods for provisioning modern pages and web parts

All of the code in this article uses Microsoft’s Patterns and Practices methods for provisioning. It’s possible to “code direct” against SharePoint Online, but you’ll find the code is less simple and gives you little/no benefit in doing so – the PnP abstraction here is generally what you want. If you find a scenario where you *do* need more control (one example might be setting “PromotedState=1” to create a news page), then Microsoft’s Customizing "modern" site pages article shows you both code approaches. Effectively in this post I want to supplement that article a bit with some extra info and screenshots, but I recommend being aware of it. In general, you'll need to follow this process to get started:

  1. Get ready with some .NET code (e.g. a console app, Azure Function or something else) - the PnP core library we'll use is based on C# CSOM
  2. Install the https://www.nuget.org/packages/SharePointPnPCoreOnline NuGet package, using a version which is later than 2.13.1703 (March 2017):

    SNAGHTMLd3a2852

When you install the NuGet package you'll also get the right version of the SharePoint CSOM library as a dependency. Once those are installed, you're ready to start coding with the PnP methods. It’s now easy to create a modern site programatically (see https://msdn.microsoft.com/en-us/pnp_articles/modern-experience-customizations-provisioning-sites) or manipulate pages in a site, which is what I’m focusing on here.

Creating a new page vs. modifying an existing page

First things first, note the difference between creating a new page vs. getting a reference to an existing page and modifying that – the code sample below shows both. Also note that a modern page is simply a page set to a particular content type and with some specific properties – it’s this that makes it modern. The PnP methods abstract you from these details, but see the MSDN page at the previous link for the info. With PnP creating or modifying an existing modern page is as easy as:

Provisioning a page with an out-of-the-box modern web part

Thanks to PnP, there’s nothing complex about getting your web part onto the page. A nice method is provided which knows about the out-of-the-box modern web parts –ClientSidePage.InstantiateDefaultWebPart():

That will get you to the point where the web part has been added to the page with the default properties:

SNAGHTML137b5e9a

Incidentally, that method allows you to choose between all of the currently-available out-of-the-box web parts using an Enum:

SNAGHTML137dca4a

Just in case you ever need to know what the underlying web part IDs are, here you go:

Web part ID Web part name
daf0b71c-6de8-4ef7-b511-faae7c388708 ContentRollupWebPart
e377ea37-9047-43b9-8cdb-a761be2f8e09 BingMapWebPart
490d7c76-1824-45b2-9de3-676421c997fa ContentEmbedWebPart
b7dd04e1-19ce-4b24-9132-b60a1c2b910d DocumentEmbedWebPart
d1d91016-032f-456d-98a4-721247c305e8 ImageWebPart
af8be689-990e-492a-81f7-ba3e4cd3ed9c ImageGalleryWebPart
6410b3b6-d440-4663-8744-378976dc041e LinkPreviewWebPart
0ef418ba-5d19-4ade-9db0-b339873291d0 NewsfeedWebPart
a5df8fdf-b508-4b66-98a6-d83bc2597f63 NewsreelWebPart
c70391ea-0b10-4ee9-b2b4-006d3fcad0cd PinnedItemsWebPart
58fcd18b-e1af-4b0a-b23b-422c2c52d5a2 PowerBIReportEmbedWebPart
91a50c94-865f-4f5c-8b4e-e49659e69772 QuickChartWebPart
eb95c819-ab8f-4689-bd03-0c2d65d47b1f SiteActivityWebPart
275c0095-a77e-4f6d-a2a0-6a7626911518 EmbeddedVideoWebPart
31e9537e-f9dc-40a4-8834-0e3b7df418bc YammerEmbedWebPart

 

Setting property values on web parts

Things get a little trickier when it comes to setting properties, but only because discovering the actual property names for each web part currently needs some digging. Here are a couple of examples, using the video embed web part and the Yammer embed web part:

Now I have my web parts properly configured as they land on the page:

SNAGHTML13864eb6

Right now, it’s a little tricky to discover the property names for each web part – but the PnP guys mentioned that in future the SPFx workbench page will help out with this (i.e. add web part to page, then use see the property structure somewhere in the workbench), and that will be nice. For now, I found a couple of options - you can dig around the collection returned from ClientSidePage.AvailableClientSideComponents() in the debugger (more on this method later):

SNAGHTML1389c697

..or an easier way can be to instantiate the web part first using the PnP method, and look at that in the debugger:

SNAGHTML138befa1

Another option is to analyze the “CanvasContent1” page property on your page’s list item (e.g. in the SharePoint Online Client Browser or similar tool). Anyway, once you have the property names you can set them accordingly.

Provisioning a custom SPFx web part

Provisioning a custom web part makes use of a different method in the PnP stack – ClientSidePage.AvailableClientSideComponents(). The process is slightly different in that:

  • The app needs to be installed to the current site, as noted earlier (at least for now)
  • You need to obtain the ID/name of your web part from the manifest, or by analyzing the available web parts collection on the page (once the app has been installed and the web part is indeed available)

Here’s what a method to add a named custom web part to a page might look like – it’s a matter of identifying the item in the collection that represents your custom web part :

The ID and name can be found in the web part’s original manifest file, as shown below:

SNAGHTML1256879f

These values just need to match up with whatever you’re using to identify the web part in your code e.g:

var webPartToAdd = components.Where(wp => wp.ComponentType == 1 && wp.Name == wpName).FirstOrDefault();

SNAGHTML12a2fda8

..anyway, now my custom web part is provisioned to the page (with my truly beautiful color theme in this case!):

SNAGHTML13aa72e8 

Other notes

  • The ClientSidePage.AvailableClientSideComponents() method is an abstraction on the [site]/_api/web/GetClientSideWebParts endpoint. It’s worth taking a look at that.
  • If you look at the full collection returned by these methods, you’ll find there are lots of additional items that I’m not listing in the table above. These are non-web part components such as “SPFilepicker”, “SPHtmlEmbed” and “SPPageContext” – these are other bits of SPFx code which are registered with the framework so that they are allowed to run. I think we can expect that other forms of arbitrary JavaScript we implement will be registered in this way (e.g. JSLink replacement).
  • If you wish, you can add an out-of-the-box web part using ClientSidePage.AvailableClientSideComponents() (since it contains both custom and stock web parts). Just be aware that for out-of-the-box Microsoft web parts the name is always the same as the ID, which is slightly confusing and means you can’t easily reference the part by name in your code. I checked, and this isn’t a PnP bug but is how they come from [site]/_api/web/GetClientSideWebParts:

    SNAGHTML129f4543

    Contrast that screenshot with the one above for a custom web part (where the ID and name are different) - just one to be aware of.

Summary

Adding a modern/SPFx web part to a page is simple with the PnP methods, so long as you're happy to write your own code rather than depend on a PnP provisioning template - but hopefully XML support is coming soon too. Similarly, it’s also easy to create new pages or add to existing pages with those methods. I've run through some scenarios here, but the MSDN article Customizing "modern" site pages has some *great* information, and I highly recommend being aware of it (and the companion articles linked from there). Good job PnP team :) Happy coding!

Monday, 13 February 2017

Web part properties in the SharePoint Framework – part 2

In this post I continue looking at the out-of-the-box controls you can use for web part properties in SPFx. I think the team have done a good job on how web part properties work – in terms of controls, you can always create your own but it’s good to know you often don’t have to. You can represent most things as a web part property - we have dropdowns, checkboxes, sliders, toggles and so on. And as we’ll see here, even the humble button has lots of options.

NOTE – in these articles I provide a description of most important properties of each control (partly based on specific nuances I observe when using them), but be sure to also reference the official docs for those. The main point of my posts is to show the visual screenshot of each control and add some extra tips/info, rather than duplicate the documentation.

Buttons (PropertyPaneButton)

If you need to use a button in the web part property pane, the good news is there are lots to pick from!

What it looks like:

SNAGHTML2e77658e

By the way, those lines between each button are there just because I’m using a horizontal rule (PropertyPaneHorizontalRule control) to separate each one – another useful control you can use to help present your web part properties as you like.

Code:

Buttons all share some common properties which are fairly self-explanatory, but note that some properties only apply to some button types. Here are some key ones, but also see ipropertypanebuttonprops for some extra details on the 'aria' properties for use with screen readers.

Properties:

Property

Description

text Text displayed on the button.
buttonType

Specifies the type of button to show, from PropertyPaneButtonType enum:

  • Normal
  • Primary
  • Hero
  • Compound
  • Command
  • Icon
onClick Pointer to a function to execute when button is clicked. N.B. There are some additional options in terms of interacting with web part properties and context, see the ‘Buttons and bound properties’ and ‘Context – ‘this’ in click handler’ sections for more details.
icon Used for Hero and Icon buttons only. Specify a value that matches up with the name of an icon in the Office UI Fabric icon set - https://dev.office.com/fabric#/styles/icons#icons
description Used for Compund buttons only – displays as the secondary text
disabled Specifies if the control is disabled.

Other aspects of buttons

Buttons and bound properties

Buttons can be bound to properties of your web part – this is optional, and is done by specifying a value for the first parameter which matches up with a property you have defined (notice it’s an empty string for most buttons in my sample above). I see it as a nice way to hook into state/properties for the web part itself. This can be useful if you need to set a web part property when a button is clicked – perhaps you want to track if the button has ever been clicked so that other controls can be enabled/disabled or some other similar scenario. You could update a property ‘manually’ yourself in code, but the nice thing is that the old value is passed to your onClick handler, and returning a value from the function sets the new value, which makes things simple. The pattern is shown below:

private heroButtonClick(oldVal: any): any {
    if (oldVal === "Something old") {
      // do something..
    }
    return "Something new";
  }

In the larger code sample above showing button declarations, you can see that most buttons are not bound to a property (first parameter is an empty string), but the hero button is bound to a web part property named ‘btnHero’. This is defined in my manifest.json file, and like any web part property, I can set a default value there. If you just need a simple button click handler, you can declare the function without a parameter, and without returning a value.

Context – ‘this’ in click handler

If you specify the click handler in the normal way (e.g. onClick: this.cobWPPropButtonClick), then inside the function ‘this’ will represent the button. This is useful if you want to know which button fired the handler, perhaps because you have multiple buttons sharing the same callback. If for any reason you want ‘this’ to represent the overall web part class, you can bind with onClick: this.wpPropButtonClick.bind(this).

Summary:

  • if you want context of button, bind with onClick: this.wpPropButtonClick
  • if you want to stay in context of overall class/web part bind with  onClick: this.wpPropButtonClick.bind(this)
Icons

To use one of the button types which use an icon (Hero or Icon button), you reference a named icon in Office UI Fabric. These can be found at https://dev.office.com/fabric#/styles/icons#icons, and there are lots to pick from:

SNAGHTML353fe5

Indeed, I spent a happy 10 minutes amusing myself by creating buttons with some of the more unusual icons Smile

SNAGHTMLeb041

Haha! Anyway, there’s quite a lot of flexibility there and it’s definitely possible to create buttons which lead to a nice user experience. Just don’t go too crazy Winking smile

Toggle control (PropertyPaneToggle)

The Toggle control is fairly simple, and suits anything boolean-like that can be on or off, enabled or disabled.

What it looks like:
SNAGHTMLd65894d SNAGHTMLd6630a9

Notice that there are separate labels for the on state and the off state, which show appropriately. If you need some code to execute when the toggle changes state, note that your entire getPropertyPaneConfiguration() method runs at this time – in fact, it does whenever a control changes state in a reactive property pane (but not otherwise). That should be a reminder that you need to keep this method lean, and only do async lookups when absolutely needed, not on every execution.

Code:
Properties:

Property

Description

label Text displayed next to the control.
onText

Specifies the text to show when in the ‘on’ state.

offText

Specifies the text to show when in the ‘off’ state.

checked Used to set the state of the toggle.
key A unique key to identify the control.
disabled Specifies if the control is disabled.

Slider control (PropertyPaneSlider)

The slider control is perfect when you want to allow a user to select within a range of values (min/max). It’s quite flexible in that you can choose the ‘step’ value, e.g. to go up in increments of 5, 10, or whatever you need.

What it looks like:
SNAGHTML9c6b7ad
Code:
Properties:

Property

Description

label Text displayed next to the control.
min

Specifies the minimum value (lower bound).

max

Specifies the maximum value (upper bound).

step Specifies the increment that the value can be increased by when the slider is dragged or clicked.

showValue

If the current value should be shown next to the control (enabled in my image).
value Specifies the initial value.
disabled Specifies if the control is disabled.

Choice Group control (PropertyPaneChoiceGroup)

This control allows the user to make a selection, but with radio buttons instead of a dropdown list. It works similar to the DropdownList control in that it takes an array of options. One notable difference here is that if you don’t want plain radio buttons, images can be used too.

What it looks like (radio buttons):
SNAGHTMLeea9bf7
Code (for radio button options shown above):
What it looks like (radio buttons):
SNAGHTML112bb4d7

Note you can actually specify a different image for when the option is selected compared to when it is not.

Code (for images shown above):
Properties:

Property

Description

label Text displayed next to the control.
options The set of IPropertyPaneChoiceGroupOption items to use as the choices.
Properties of the IPropertyPaneChoiceGroupOption:

Property

Description

key Unique key for the item.
text Text for the item.
imageSrc URL of the image to use, when using images rather than radio buttons. (I only tested with absolute URLs so far)
imageSize An object containing height/width properties to specify the size of the image.
checked Used to specify if this item is selected.
disabled Specifies if this item is disabled (not available for selection).

Link control (PropertyPaneLink)

A simple control which allows you to put a link in the web part property pane - could be used to provide a link to some help or guidance for example.

What it looks like:
SNAGHTML1af5543
Code:
Properties:

Property

Description

text Text for the link.
href Hyperlink destination.
target Window to use – options include _self (default), _parent, _top and _blank.
popupWindowProps An object specifying the width, height, title and position of a pop-up window (IPopupWindowProps).
disabled Specifies if the link is disabled.

Summary

There are lots of out-of-the-box controls you can use when implementing web part properties in the SharePoint Framework. In this post we looked at the Button, Slider, Toggle, ChoiceGroup and Link controls – but there are others too, including Textbox, Dropdown and Checkbox controls which I wrote about earlier. A big part of providing a usable web part is often the care taken around how the user will set properties, so knowing what’s in the toolbox is important for SharePoint developers.

Thursday, 19 January 2017

Avoiding dependency issues in SharePoint Framework (SPFx) development

One area I talk about in my “Avoiding pitfalls when developing with the SharePoint Framework” talk is dependencies, and the problems you can run into. Whether you depend on jQuery, Angular, React or other JS libraries is up to you, but there will always be some – and npm is typically the way to bring these libraries into your SPFx solution. Using a TypeScript/JavaScript-based code stack and npm packages is completely different from .NET, and I think most SharePoint developers are fairly new to this world. There’s quite a lot to learn with npm itself, but this is important for successful team development with SPFx. Of course, npm, gulp and node.js might be familiar territory if you’ve already done lots of modern JS-focused web development (by which I don’t mean jQuery!), but there are deep topics here beyond just the coding aspect.

To get the development and ALM process right with SPFx, some of the answers lie in use of commands like npm shrinkwrap, having a solid understanding of the package.json file and how developers specify different types of dependencies. But before we get to that in detail, let’s start by talking about the problems and some general background to understand.

I use the slide below to summarise some key pitfalls in this area, splitting them into “dev” and “shipping” considerations:

clip_image002

What are caret dependencies (never mind why they can be a pitfall)? What does –save do on the npm install command? If those are questions you’re asking right now, then my companion post SPFx - an overview of node_modules, package.json and other node concepts might be useful.

Otherwise, let’s get to the detail.

Not specifying --save on npm install

This is a newbie pitfall for teams/developers not very familiar with npm. When a developer adds a package with npm install, the package is downloaded from the npm repository and installed to your application – at least, in the machine and folder that the command is run on. Adding the --save flag ensures the dependency is also recorded in package.json – thereafter, when any dev runs npm install or npm update for this application, npm will again ensure the appropriate package is downloaded and installed locally (because the package.json file is shared via source control). It’s the equivalent of adding a .NET dependency via NuGet, compared to just adding a local file reference. As ever, checking the full set of packages themselves into source control is usually a bad idea. So, the pitfall is simple - if the dev forgets to use the --save flag when installing a package, no entry in package.json is made and code may fail due to a missing library on other machines. You’ll see a TypeScript compile error like “Cannot find module” when another developer tries to build or run the code (e.g. with gulp serve):

clip_image004

Recommendation – always track your dependencies by specifying the --save parameter (or one of the options such as –save-exact) when running npm install.

You might also consider a custom .npmrc file for your team here, which can automatically specify certain parameters (e.g. --save or --save-exact) without the dev having to remember them. I talk about how a custom .npmrc file works in the other post.

N.B. if you do fall into the trap of using a dependency without it being properly stored in package.json, simply install it again *with* the --save (or similar) flag. Then have each dev run an npm update to ensure everyone is using the same version.

Pitfall - using caret dependencies without thinking about it

When adding an npm package, the default is to use a caret dependency. However, both caret and tilde dependencies bring an element of risk to the dev process (but can have benefits too). If you’re not familiar with version numbers which use carets or tildes, read either my background post or semantic versioning (semver) in the npm docs.

Briefly, the caret character (^) denotes that any version up to (but not including) 4.0.0 is acceptable. Caret dependencies like this are the default with npm, but can lead to danger because there can be all sorts of changes within that version range, potentially including breaking changes, depending on how the package author handles things. Not everyone plays by the semver rules. So, that means that in team development, one person on the team can be using 3.1.1 and another 3.9.9 (i.e. releases of the same major version, but different minor versions), depending on how when each last ran the npm update command. So, there can be lots of variability from caret dependencies like these.

Tilde dependencies (~) are similar, except here the range is more narrow – so ~3.1.1 would allow any version up to (but not including) 3.2.0 (i.e. releases of the same major/minor version, but different patch versions).

Note also that I’m simplifying things here slightly, since npm deals with things differently when a zero is used in the version number. See the semver page for more details.

So are caret and tilde dependencies always bad?

Well no, not really. You might decide that you DO want the latest and greatest of libraries you are using during the dev process, without the hassle of managing each individually. Often you do indeed want those minor bug fixes and performance enhancements – and avoiding “exact” dependencies gives you that (so long as you npm update regularly).

Recommendation – make an explicit decision about whether you want “floating” dependencies in dev.

If NO, consider these options:

  • Ensure all developers always use the –save-exact flag instead of the –save flag
    • This will have the effect of writing in an exact reference into package.json, rather than a caret or tilde dependency
    • Use a custom .npmrc file across the team to have the same effect (without developers having to remember –save-exact every time they install a package)
  • Again, see my SPFx - an overview of node_modules, package.json and other node concepts for details on this technique

If YES, then:

  • Stick with caret dependencies, but consider becoming “tighter” as you approach releasing your web part – ensure all devs are running npm update regularly, and perhaps switch to exact dependencies just before shipping.

Whether you use exact dependencies in dev or not, there’s something that I recommend you always do to freeze dependencies at ship time of each release, and that’s to run npm shrinkwrap. We’ll talk about that next..

Pitfall – not locking down dependencies when you make a release

In SPFx and node.js development, it’s crucial to remember that the node_modules folder is an entire tree of dependencies. First level dependencies that you know about have their own dependencies, which are stored in child node_modules folders – that’s why the node_modules folder can be big in size and go quite deep. The steps we’ve talked about so far, such as considering use of --save-exact to avoid caret/tilde dependencies, only get you so far – and that’s because they deal with your first level dependencies only. Consequently, you’ll find it difficult to recreate the *exact* build you shipped as v1 because you can’t restore the exact node_modules folder you had at the time of this build. Sure, you could if you always checked the entire mode_modules folder into source control for every build, but yuck!

What you need is for the entire tree of dependencies to be frozen for each release – the npm shrinkwrap command gives you this. It creates a JSON file containing details of which version was resolved of every package used:

SNAGHTML9f2fa0f

Thereafter, if the npm install or npm update commands are used against a folder containing such a file (named npm-shrinkwrap.json), npm will look to it to restore the packages. This is different to the default behaviour which will use any caret or tilde dependencies (etc.) specified in the package.json file. Thus, with this approach you can restore the entire build as it happened at a certain time, without having the node_modules folder in its state at that time.

Recommendation – run npm shrinkwrap every time you release a version of your code. Store the npm-shrinkwrap.json in source control.

Summary

Creating SharePoint Framework solutions effectively involves more than just learning the new APIs. You need to build a good understanding of the underlying web stack, and arguably some elements are more important than others – modules, packages and npm is a combined area that I recommend spending time on. Without this, it’s easy to fall into some pitfalls when developing or shipping your SPFx solution. Overall I recommend:

  • Taking care when developers add libraries – ensure they are tracked in package.json
  • Deciding on whether you’re happy with floating dependencies during dev, or whether you prefer to use exact dependencies
  • Running npm shrinkwrap each time you release a version of your solution, and checking the npm-shrinkwrap.json file into source control. This will allow you to rebuild the app properly later on, when never versions of your dependencies have been released

SPFx - an overview of node_modules, package.json and other node concepts

N.B. this is a companion post to Avoiding dependency issues in SharePoint Framework (SPFx) development

Any SharePoint Framework (SPFx) solution that does something useful will use external JavaScript libraries – whether bigger frameworks such as React or Angular, or smaller, more focused libraries such as LoDash, moment.js or something else. Since SPFx is based on a node.js-based web stack, the best way to integrate such libraries into your solution is usually to add them from npm, the internet-based package manager for JavaScript. Npm is effectively an equivalent of NuGet in the .NET world. Once you’re set up with npm, a developer simply runs npm install jquery [or whatever] and the source code for the package will be added to your application’s files. As is normal with node development, the library is added under the “node_modules” subfolder, and it can now be referenced in your code.

The role of the node_modules folder

So the node_modules folder stores all your dependencies. But it also stores any dependencies of those, and so on and so on. So, it’s a tree structure which can be quite deep. An app which uses jQuery and React for example, could look like this:

clip_image002

In this example, jQuery has a dependency on “cache-swap”, which also has its own dependencies in its node_modules folder. And so on..

Modules which are actually used by your code are distributed with your app, so everything works at run time. The bundling mechanism built into the SharePoint Framework tooling takes care of this using webpack.

Ensuring dependencies are tracked with package.json

If the --save flag is also specified when adding a package with npm install, an entry is written into the package.json file in the application’s directory. This goes into the “dependencies” section of the file, and will look something like this:

"jquery": "^3.1.1"

Here’s an example of full package.json file:

clip_image004

Notice the caret (^) in that version number above. I’ll talk about tilde and caret dependencies later. But the purpose of that –save flag is is to ensure that the dependency is recorded. The node_modules folder itself is typically *not* checked-in to source control (in the same way all NuGet packages would not be), partly because it is large and unwieldy. Instead, each developer has a local copy on their machine, and the shared package.json file plays a critical role in ensuring all devs have the same files. When another developer subsequently obtains the files from source control, running the npm install or npm update commands will ensure all dependencies are restored on his/her machine, based on what’s stored in the package.json file.

As I detail in Avoiding dependency issues in SharePoint Framework development, if the developer forgets to track the dependency (with the --save flag or similar), then other devs are likely to be missing the module on their machines and the code will not work for them – they’ll get a missing module error. However, even if developers do always remember to specify the --save flag, you can run into problems in dev because npm uses caret dependencies by default, and these are a form of “floating version” dependency. I won’t discuss the pitfall further here, since we’re all about the fundamental concepts in this post – but related to all this is the whole topic of semantic versioning (known as semver).

A brief summary of semantic versioning

Semver refers to the different kinds of version numbers which can be used by npm packages. The semver page in the npm docs is recommended reading, but I’d say the core things you need to understand are:

  • The 3 part version number format i.e. MAJOR.MINOR.PATCH, and the rules for when each number should be updated – see http://semver.org
  • The different forms of version number used in package.json

Version number forms include:

Type

Example

What it does

Caret dependency

^3.1.1

Allows any version on the same major version, i.e. anything below 4.0.0

Tilde dependency

~3.1.1

Allows any version on the same minor version, i.e. anything below 3.2.0

However, my table above is a simplification because npm deals with things differently if there is a zero in the version number. Additionally, npm supports other forms too such as pre-release versions like “1.0.0-alpha.1” and tags. I recommend spending time in the npm docs, but there are LOTS of simplified posts on the internet too if you prefer another format e.g. https://nodesource.com/blog/semver-tilde-and-caret

Setting npm defaults to get consistency across devs

Elsewhere we’ve talked about parameters to pass to npm commands, such as the --save or--save-exact flags used with npm install. However, a useful approach with a dev team can be to set defaults across the team so that each developer does not need to remember a certain flag each time a command is run. This can be done in a couple of ways:

  • Setting environment variables on each machine
  • Using a .npmrc file – at the project, user or global level

I like the idea of using the .npmrc file at the user level (e.g. C:\users\chris\.npmrc on my machine), and ensuring all team members have this in place. By creating/editing this file, I can specify for example that all dependencies should be saved into package.json with *exact* version numbers, rather than caret or tilde dependencies. I can do this by adding the following to my file:

save = true
save-exact = true

Now, when any dev installs a package, the following differences to the default behaviour will occur:

  • The dependency will automatically be added to package.json, even if the dev accidentally forgets the --save flag
  • The dependency will be added with an exact version number, not a caret version number

This is useful, as devs won’t accidentally fall into some of the pitfalls that can come about from the npm defaults.

Also check out the save-prefix config flag as an option to override caret dependencies (e.g. to change to tilde dependencies).

Summary

Hopefully this is some useful background information to concepts underneath the SharePoint Framework. It can seem a whole new world in some respects, but at the same time I don’t think you have to be a complete expert in npm, modules, webpack etc. to be productive. A little extra digging around sub-topics like these is recommended though I think. Have fun!

Thursday, 5 January 2017

Changes to Custom Actions and handling of JavaScript in SharePoint Online

Recently our Custom Actions stopped working in modern document libraries in Office 365. We were surprised at this, because as far as we were aware we weren’t doing anything that went against “new” guidance for working with modern team sites and modern document libraries. Since the beginning of modern doc libs, Custom Actions which use ScriptSrc or ScriptBlock have not been supported (same with JSLink customizations). But we weren’t doing any of these things – our specific details were:

  • A Custom Action using a URL-based action which opened a modal dialog (pop-up) – in our case, to show a custom options page to the user
  • Use of “EditControlBlock” as the location, so our menu item appears on the context menu for each document
  • Registered on our “base document” content type which is used in our document libraries

And for a while everything was great - as expected, our menu item showed up in both the classic and modern document library experience. However, in early December (2016) our menu item disappeared from the modern experience, across all our tenancies (eventually). These images show our menu item (named “Actions”) visible in the classic view but not modern:

Classic:

Classic_

Modern:

Modern_

New rules for Custom Actions

Essentially, Microsoft have made changes in exactly what is supported with Custom Actions. I guess you could say this doesn’t align 100% with previous guidance on the topic – or at least, some low-level details were ambiguous or open to interpretation. For example, the Update on Modern Document Libraries and Extensibility blog post says this:

“We’ve already made some good progress here.  Theming, global navigation links, and URL-based custom actions that extend the ribbon and context menus are already supported in the modern document library experience.  This ensures that customers and partners taking advantage of these features can use the modern document library experience without compromising their customizations.”

For our part, we figured that we should be fine because we’re using a URL (rather than ScriptSrc or ScriptBlock). However, talking with the Office 365 engineering team, it became clear that a URL which contains JavaScript (e.g. Url=’javascript:OpenDialog()’) is no longer permitted – although this did work until early December. Additionally, targeting by content type no longer works – the only option currently is to target by list template type, for example:

  • 100 – custom list
  • 101 – document library
  • ..and so on

UPDATE – targeting by content type now works again. So you can once again target by content type or list template type..

I appreciated the help from folks in the product group who helped me understand what their code is currently doing, and where things might head in the future – thanks guys.

Anyway, we had to make some changes. In our case, since we can no longer open a dialog from the menu (since that requires some JavaScript), we’re changing our experience to navigate the user to a full page instead. Also, we need to change the targeting from content type to list template type – that’s mainly OK, but in truth does give us a slightly different scope to what we really wanted.

Could any of these changes affect you? If so, you’ve probably noticed already – but either way, it’s definitely worth SharePoint developers becoming clear on the latest developments in this space. Overall, there is a longer list of these kind of things which are no longer supported on modern lists and libraries, including:

  • Custom master pages
  • JSLink (field and view types)
  • AlternateCssUrl
  • Custom Actions which use ScriptLink to add JavaScript to the page

On the bright side, there is now some official documentation in the form of MSDN articles which provide more detail than I’m including here. I highly recommend going through these:

Using the classic experience as a workaround

Remember of course that these changes don’t affect the classic experience. You have the choice of continuing to use that (e.g. by setting it at the tenant level) if you’re happy with that. We weren’t unfortunately, because we want our uses to have the benefits of the new document library UX (better mobile experience, improved metadata editing, new summary panel, sorting/filtering enhancements and so on).

Looking to the future (especially around JavaScript in Office 365)

Microsoft have noted in several places that new mechanisms will come to SharePoint Online to match many of the previous capabilities. They may not take exactly the same form as the previous mechanisms, but it should be possible to achieve the same overall result. These include:

  • Custom master pages --> some other “deep branding” controls (which may or may not provide the ability to control the full HTML)
  • JSLink --> some other mechanisms to control the rendering of list views and fields
  • CustomAction + ScriptLink --> some other mechanism to add JavaScript to pages

Thinking specifically about JavaScript, I think it’s clear that there will be increased controls around administrator approval of scripts – the idea is to provide more governance so that arbitrary scripts cannot be added by a developer without wider approval. After all, that’s why Microsoft have made some of the recent changes to pull back on previously supported approaches – they did leave holes which could result in trouble for some organizations. Despite the occasional pain on the journey, I think we all need to accept that these changes are for the better and the resulting position should be better overall.

Friday, 2 December 2016

We’re starting to write production code on the SharePoint Framework now. Should you?

I’ve been writing and speaking on the SharePoint Framework (SPFx) for a while now, but in many ways it’s all been a bit theoretical so far. After all, SPFx is still in preview at the time of writing (early December 2016) with General Availability expected soon. However, I’ve started to realize that some web parts we are specifying and building for clients now actually need to be done in the Framework. The principal reason for this is that we need them to work in modern pages – and web parts developed using previous approaches way will not work there. On this, I’ve been using this slide recently to explain what works where:

image

Essentially, a modern (SPFx) web part can work in both modern and classic pages. But a classic web part can only work in classic pages.

Let’s be clear on what we mean by that:

Modern pages use modern web parts
Modern pages cannot use any “classic” web part, including the Content Editor web part, Script Editor web part, Content Search web part, Content Query web part, or any custom web part based on one of these. This means that all the out-of-the-box web parts we’re used to in SharePoint cannot be used in these pages. Microsoft provide a new family of OOTB web parts which meet many common needs, and also address newer scenarios too (e.g. a Power BI web part to embed a Power BI report).
 
It also means that any “cloud-friendly” custom web part which uses the common “Script Editor/Content Editor web part + JavaScript” embed approach will not work in it’s current form – however, I’d expect Microsoft to at least provide an equivalent way to easily add JS to a page e.g. a new Script Editor-like web part). Maybe they’ll even go further and provide a zero-friction way of migrating such web parts?

So, this is kind of a big deal. Of course, the other aspect to consider is how much of a problem all this is..

How prevalent are modern pages? Which pages are modern?

As I mentioned in my previous article Modern SharePoint pages and team news pages - how to query/search for them, the new team news feature uses modern pages and it’s now the default when a new page is created. A more complete list of modern pages might be:

  • Any new page created with the “Add page” menu item (from now)
  • Any team news page
  • Modern list/library pages (but currently not extensible – web parts cannot be added)
  • The Office 365 profile page (but currently not extensible – web parts cannot be added)
  • Delve blog pages, though these are a slightly different (earlier) flavour

You can identify a modern page quite easily – it has the site logo displayed, slim toolbar and then the tall banner containing the page title:

SNAGHTML26d35183

Of course, Microsoft might update this look and feel at some point, but that’s how it is for now.

The new web part picker

At the heart of the matter is the new web part picker. When you edit a modern page and go to add a web part, you’ll see this and it’s a much simpler experience than before – no wrestling with the ribbon, no navigating through lots of categories of web parts you never use:

image

image

Of course, where I’m getting to with this is that only Microsoft’s new web parts and our web parts developed in the SharePoint Framework will show up here. It’s worth becoming familiar with these web parts because they are the new building blocks – but note that more will be added soon, such as the Power BI web part (which might just be awesome, if authentication works in a simple or automatic way). Consider also the new Highlighted Content web part – this is a modern version of something approaching the Content Search web part, but it doesn’t quite have the same power. It *is* easier to use though (much), and based on my experience with end-users I think it really is the direction Microsoft had to head in.

Another thing to think about is that with a new web part picker, the previous requirements of needing web parts to be added to the web part gallery of the current site collection doesn’t necessarily still need to be the case. In the SharePoint Framework, the requirement is currently that the app package must be installed to the App Catalog and for the app to be installed to the site – nothing goes in the web part gallery. But SPFx is still in preview, and Microsoft have some options here - it will be interesting to see where things end up once it hits General Availability.

Summary

So, a new page and web part model. We’re seeing new pages mainly be applied to SharePoint team sites so far, but I think it’s clear that publishing sites will receive similar updates in the future. At that point, it’s fair to expect that, again, only Microsoft’s new web parts and SPFx web parts will work in those pages. The main message here is that modern pages are starting to become prevalent (and the default), and users are using them – so if you’re customizing SharePoint or adding new functionality based on web parts, you might run into problems soon if your web part will not work here. This is driving us to create new web parts using SPFx, and maybe it should for you too. Just make sure you have a fall-back plan in case timelines don’t align – for example, you need to make your web part available in full production mode (and be fully supported) before Microsoft get to SPFx General Availability in non-First Release tenants.

Thursday, 24 November 2016

Modern SharePoint pages and team news pages - how to query/search for them

Modern pages are now in SharePoint team sites in Office 365, and this includes the new “team news” facility. This is a simple way of creating news articles within a team site - it’s no replacement for an organization-wide intranet news facility, but it is useful for teams to convey news or other information within their group. And whilst it’s called “news”, of course the pages themselves could be anything – reminders for the team, current priorities/focus areas, policies and procedures, and anything else. One key element is that users can easily submit these articles from their mobile device – specifically the SharePoint mobile app. But it’s just a page with text, images, and any other web parts that the author adds (though that bit needs the PC experience).

I spent a little time looking at how all this works, and how developers and power users can query and search for such pages. Just to set the context since this is all shiny and new at the time of writing, this is what a display of team news looks like:

(By the way, excuse the horrible branding in this tenant - I use it to clearly tell me which of my test tenants this is!)

News page

In the context of a group site (i.e. a modern site attached to an Office 365 Group), things look a little different in terms of the page header/banner, but largely the same:

News page - Group

..and then to zoom in a little on the “News headlines” control:

News headlines

..or as an alternative, the “News list” control:

News list

Both of those are new web parts that you can add to a modern page – and since new-style web parts developed with the SharePoint Framework can be used in “classic” pages, it should be possible to use these new web parts everywhere. However, since classic pages use the old web part gallery and picker, it could be that we need to export and import one of these web parts to add them to a classic page.

General notes on news:

  • When a news page is created, it gets displayed on the site *immediately* in the “News headlines” and “News list” controls – no waiting for a search crawl
  • It’s important to click the “Add” button next to news to create a news page. Otherwise you’ll get a modern page, but it won’t show up as news - because it isn’t a news page. As Elio points out in What makes a page be a news page in SharePoint Online?, news pages have a field called Promoted State and the value gets set to 2. So that PromotedState=2 is the thing that identifies news pages
    • Note that this isn’t exposed in the UI, so there’s no easy way (outside of code/PowerShell/tool) to update this once a page has been created (at least for now)
  • Images uploaded during news page creation go into Site Assets/Site Pages/[escaped page name], like this:

     SNAGHTMLf13e9a2

So that’s a sense of how team news works in team sites. But what if you want to search/query for these pages as a developer or power-user?

Searching for modern pages and news pages

Searching for news pages

The main thing I wanted to say here is to extend Elio’s message and say that there is also a Managed Property with the same name (“PromotedState”), and so we can use search to find these pages too (e.g. if we wanted to roll-up team news from many sites):

image

..and so with a Content Search web part or similar, we can use this in a simple query to find results:

SNAGHTML16154ef2

For now it seems only news pages use this property, but it might be wise to add a filter on say, content type, in case Microsoft decide to use it elsewhere in the future.

Other notes:

  • The content type is the same for standard modern pages and news pages – here are the details:
    • ContentType (name) = “Site Page”
    • ContentTypeId = 0x0101009D1CB255DA76424F860D91F20E6C411800D294F66E48650D4DB0D1477463DC0B51
  • Data for all web parts is stored in one page field in the content type, and that translates to one managed property in search – here are the details:
    • Field name = “CanvasContent1”
    • Managed property = “CanvasContent1OWSHTML”
    • Sample data:

      SNAGHTML16253821

So, this idea that everything is stored in one field can potentially be a challenge with modern pages. It’s not going to be easily possible to query/filter on something that’s stored in the page because the data isn’t broken out into separate fields on the content type as we might normally do in a publishing scenario (e.g. show me news articles where category = ‘Politics’). That’s just a trade-off that comes with the flexibility and simplified page editing experience of modern pages I guess – I’m not sure Microsoft had too many options there.

The JSON response from the _api/sitespages/pages/feed endpoint (which the news headlines/news list controls use behind the scenes) looks like this:

Summary

The new modern pages are here, and the "team news" feature in team sites is one example of their use. Developers and power-users will find it useful to understand what things look like underneath, and for news pages it's the PromotedState=2 field value (and managed property) that identifies them. Thanks to Elio for pointing out the field value, and consider also the managed property which may be useful to you in search.

Tuesday, 1 November 2016

Pitfalls when developing with the SharePoint Framework–my talk at Unity Connect, Amsterdam

UnityConnectIn a few weeks I’ll be speaking at the Unity Connect conference in Amsterdam, 17-18 November 2016. I’m looking forward to this event! There are some great speakers there such as Waldek, Spence, Dan Holme, Scot Hillier, Marc Anderson, Neil Hodgkinson and many others, and I think now is a great time to be talking about SharePoint and Office 365 – regardless of which aspect of it you work with. Certainly for developers it’s pretty good – many of us have got past the initial learning experiences of working with the SharePoint Framework (SPFX), but at the same time it’s a deep topic, and there’s lots still to learn and preferred approaches to work out.

In my session, I want to convey some of the mistakes you can easily make when getting started with SPFX. Between the coding side and the packaging/deployment side, there are definitely a few little traps in there – some articles which I think are great have been published so far, but I think it’s an evolving list and there a couple of things on my mind for sure. I’m also delivering a 20 minute “innova” session on developing a web part in the SharePoint Framework.

Here are the details of my sessions:

Avoiding common pitfalls when developing with the new SharePoint framework - Thursday, Nov 17, 13:20

Getting started with the new SharePoint framework can be a challenge initially. Whether you choose to use every JavaScript framework under the sun, or keep things as simple as possible, there's a reasonable amount to learn. Inevitably you'll fall into a few gotchas, and this session discusses the common ones to ensure you get to productivity fast. From adding JavaScript libraries to dealing with async code, from implementing TypeScript modules to dealing with npm, this session tries to smooth over your learning path.

INNOVA (20 minute session) : Developing a Client Web Part in the SharePoint Framework – What You Need to Know - Friday, Nov 18, 11:45

Creating a client web part in the new model is *very* different to the classic SharePoint web part experience that developers are used to. From creating the initial files with the Yeoman Generator, to adding your code in TypeScript, and then packaging for deployment – there are new things to learn at every turn! But there are huge advantages to the new approach – a better experience for users working with the web part, better performance, and freedom to develop using modern web technologies. Your JavaScript code can also be hosted wherever you like (e.g. a CDN), and this opens up some new options which are very welcome in the SharePoint world. This discussion and demo session looks at the fundamentals of client web parts so you can get an accelerated start on this important developer topic.

The conference

Anyway, there’s still time to register for the conference if you’re interested. Looking at the sessions and the price (€699), I think it’s a bargain personally. Go to https://www.unityconnect.com/2016/Registration to find out more