Developing for Office 365 – thoughts on use of custom master pages and web templates etc.

As more and more organizations are choosing to deploy SharePoint workloads on Office 365, it’s interesting to see Microsoft change the guidance given to developers on how customizations should be implemented. If you’ve been following closely, you might be aware that the following messages have started to emerge in recent months:

• Avoid custom master pages
• Avoid using web templates
• Avoid using declarative XML (i.e. Feature XML) in a WSP (even a sandbox WSP – and remember, we already should not be using server-side code here either!)

These messages are mainly relevant to the Office 365/SharePoint Online space – but arguably have some relevance for on-premises SharePoint too. At the time of writing (Christmas 2014), these messages aren’t really on MSDN yet but will very soon be published in Microsoft Virtual Academy training. I have a lot of respect for the guys in Microsoft behind this thinking. I’ve had some great conversations with Vesa Juvonen, Steve Walker, Bert Jansen and so on about these topics, and these guys ultimately have to battle slightly opposing forces - “making Office 365 a good development platform WITHOUT making the service too difficult/expensive to run” would be a summary of that. Hopefully this doesn’t get me crossed off their Christmas card list (!), but in this post I’ll explain why I’m not sure that I agree with the guidance in all cases.

After all, these are BIG changes!! No custom master pages? No web templates? Really?? Web templates were the answer to world hunger not that long ago – after all, if you’ve got several hundreds/thousands of team or project sites to create, and they all should have some tools/widgets above the out-of-the-box team site, web templates are the tool in SharePoint way that Microsoft provided to do this! And custom master pages have long been the way to implement a reasonable level of branding in SharePoint – and that’s important to many organizations. So what is behind this guidance? Do you need to follow it? For our projects, I’m taking the view that we SHOULD be following it for collaboration/team site-based stuff compared, but NOT necessarily for highly-branded publishing intranets which are more communications-oriented. So to summarize this decision process:

I’ll explain my thinking later, but first let’s understand why Microsoft are giving this guidance.

Using custom master pages/web templates means you might not *automatically* get new Office 365 functionality

As we all know, Office 365 is an “evergreen” platform – it is regularly updated with new functionality for end-users (the “ripples, not waves” approach). To roll out these updates, Microsoft sometimes need to update out-of-the-box site templates and master pages. Some examples of this could be:

• New functionality added to SharePoint Online team sites (e.g. new lists or settings used) = Microsoft update to team site template (STS#0)
• New functionality added to SharePoint Online via new page controls = Microsoft update to OOTB master pages

Of course, if you’re using a custom web template and master page, you won’t receive these kind of changes.  That’s a pain because ultimately you WANT this stuff in many cases – it could be some high-value functionality that your end-users would really benefit from (and perhaps that you were thinking of building a customization for!). And indeed, you’re paying for this “service” in your Office 365 licenses; it seems a shame not to get the full benefits. As time goes by, it’s also true to say that your custom master page will become more and more out-of-sync with OOTB master pages, as depicted by this diagram from Microsoft training:

Of course, what you could do is manually copy over any master page updates to your custom master page(s) for example – but this comes with effort each time. Some level of analysis, code changes, testing, deployment through multiple environments and so on – all these tasks are needed for each Microsoft update. Microsoft refer to this as the “customization tax” that you must pay if you do use custom web templates/master pages in Office 365 – and I think that’s a good description.

The flip side – having control of updates

So, some extra effort is required if we do decide to use custom web templates or master pages. But on the flip side, it could give you more control over when and how Office 365 updates are applied to your environment, and this can be appealing. Certainly if you have 50,000 users on your Office 365 global intranet and a Microsoft update breaks the home page one day (and such “breaking” changes have occurred), that’s a lot of folks calling the helpdesk and a very unhappy business! That’s probably the worst case scenario here, and it’s true to say that Microsoft have improved communications around updates – but even less dramatic scenarios such as changes which don’t break anything but do change an intranet experience need to be managed properly. Compared to team/project sites, publishing intranets tend to have more “designed” user experiences, with custom branding/look and feel and potentially more customizations. And this means a greater chance of a Microsoft update causing an issue, perhaps some kind of conflict with a minor customization – usually you’d want the opportunity to test these things together before applying in production.

If nothing else, perhaps using a custom web template/master page is one layer of protection against uncontrolled updates for publishing intranets. It won’t cover all scenarios (depending on the type of update), but certainly will cover many. However, I do strongly feel that collaboration scenarios such as team sites and project sites generally should NOT use custom web templates/master pages. There’s way less benefit to heavy branding/look and feel customization in these areas (so less need for a custom master page), and I think you really want any updates which come from Microsoft here – it could be valuable new functionality that your business users will appreciate. Additionally, since you often have many collaboration site collections (but just one publishing intranet site collection), the idea of manually copying any updates from Microsoft to these areas has more complexity too. So, my starting position is a custom web template/master page for publishing scenarios but not for collaboration scenarios – obviously each implementation may then have further variables to consider, but that’s my default thinking.

Other layers of protection

As a slight aside, other things you could do around Microsoft updates to Office 365 include:

• Close monitoring of Microsoft communications around updates – particularly:
  • The Office 365 roadmap 
  • The Office 365 updates blog
  • The Office 365 Message Center in your tenancy
• Running other Office 365 tenancies for test purposes with “First Release” mode enabled
• Signing up to the NDA Preview program if possible

And just how much of a burden is the “customization tax” anyway??

For many organizations rolling out Office 365 (especially large enterprises), I can’t help but think this “customization tax” is often a drop in the ocean in many ways. Most of the clients I work with already have a team (or teams) handling other roll-out or customization tasks, and they know that it takes much more than switching the thing on and sending a couple of e-mails to get the most of the platform. Having to occasionally have a developer make some updates is perfectly fine in the overall running of the intranet.

All these factors feed into my thinking about using a different approach for collab vs. publishing intranet scenarios.

Alternative approaches to custom web templates and master pages

But let’s say you don’t want to use a custom web template or master page or both) - perhaps because you’re doing team sites, or for other reasons.  How can you get the same effect (and what do Microsoft suggest instead)?

If you need…	“Classic” approach	Alternative approach
To apply custom branding/look and feel	Custom master page	Use a Composed Look/theme/alternate CSS file for look and feel JavaScript injection to add custom page components/controls
To have a template to create many sites from	Custom web template	Site is based on an OOTB site type (e.g. team site) and.. ..use Remote provisioning code to configure content types, lists/libraries and so on after site creation. The two key approaches here are: Write C# CSOM code (using the OfficeDev Patterns and Practices library Microsoft provide to help) and host it in Azure or an IIS server Write JavaScript provisioning code (JSOM)

Obviously the alternative approaches need some thought during your implementation, and extra effort is usually involved – but you should find that they at least work well for non-publishing scenarios (e.g. team/collab sites), thus aligning somewhat with my thoughts of treating these implementations differently. You might find though, that NOT using a custom master page for a highly-bespoke intranet would be difficult anyway, particularly if aspects such as responsive design are involved. On the templating side, the steer from Microsoft is to use remote code approaches to apply customizations to out-of-the-box sites. This goes back to the other point in my opening bullet point list, which we haven’t discussed yet:

Avoid using declarative XML for provisioning (use imperative/code-based approaches instead)

So yes, whilst many of us have spent the last few years using Feature XML for provisioning, Microsoft would now prefer us NOT to use this approach in Office 365 even if it is still 100% supported. Certainly the “XML vs. code for provisioning” debate has been around for many years now, but Microsoft are now coming down on the code side heavily – and in SharePoint Online this means remote code (CSOM or JSOM). It’s interesting to pause and consider the types of things we’d commonly use XML for here:

• Provisioning fields and content types
• Provisioning lists and libraries
• Provisioning files (either “site infrastructure” files, such as master pages/page layouts/CSS/JavaScript/images etc., or default content such as pages or documents)
• Provisioning web parts
• Declaring templates – list templates and web templates (and site definitions before that)
• Adding a CustomAction (e.g. to link a JavaScript file, or to add a ribbon customization)
• Custom field controls
• Delegate controls
• Declaring event receivers
• Feature receivers

Only a couple of those (e.g. Feature receivers, custom field controls, delegate controls) can’t be used at all in the sandbox (and therefore SharePoint Online), but you can achieve the same thing in other ways.  The rest can, but Microsoft are starting to say we should use remote code where possible instead of XML. The reason for this is that inside SharePoint, the functionality becomes dependent on an XML file somewhere instead of purely being within “provisioned” items in the content database – and this could make some kinds of system upgrade more complex. Whilst this is an interesting SharePoint engineering “thing”, it’s somewhat hard to see this as our problem rather than the Office 365 engineering team’s – after all, these upgrades are mainly things that Microsoft will undertake as part of running SharePoint Online. The “content database upgrade” step as part of, say, upgrading Office 365 to use SharePoint 2015 (or whatever) would be an example. 

As someone who leads a group of 20 developers working in many SharePoint/Office 365 engagements at any one time, I currently have some reservations about the team switching entirely to imperative/c0de-based provisioning for all scenarios. I’ve mentioned this to Steve/Vesa etc. in the past – in the spirit of open discussion, here’s a slightly expanded list of my thoughts on the “don’t use declarative XML” message from that conversation:

Some quick thoughts from me are:

• Some aspects of switching to imperative provisioning are pretty inconvenient - my team (and SharePoint devs generally) are very efficient at declarative provisioning (~7 years experience ;)), and lots of the resources on the internet are heavily-oriented towards this.
• The declarative/XML approach has been pushed by Microsoft for 7 years and even now is still 100% supported in Office 365.
• I completely get that if all customers used imperative provisioning rather than declarative, certain things/upgrades would be simpler for Office 365 engineering. But frankly, I'm not sure I'm on board yet that this is my problem too! I know that in some places it *can* be very relevant to me as the initial implementor (e.g. initial deployment can be done declaratively, but changes/updates require code), but even with this in mind, often we *still* prefer declarative for initial provisioning!
• Imperative provisioning obviously doesn't cover some templating scenarios easily - list templates, site templates etc. Sure, I can implement some remote provisioning solution which does a similar thing, but even with the OfficeDev samples I’d say it's more effort than the declarative approach - AND, sometimes there's no easy way to have things appear in the expected place in the end-user UI (especially for list templates). Big gap here really.
• Providing a production-grade, resilient “remote code hosting” solution can be difficult for some clients (e.g. those not comfortable with Azure for this). 

It will be interesting to see how this area plays out in time. These are just my opinions obviously, and it’s certainly true that using code rather than XML can bring advantages (such as better debugging and logging). Still, it seems a shame to no longer have both options. Ultimately this sub-decision might now only be a consideration for publishing intranets and the like, if you’re happy to go with the thinking that collaboration-oriented sites should indeed use OOTB site types with remote provisioning code (in other words, you’ve already decided to use code here). But I’m certainly reluctant to abandon the declarative approach across the board just yet.

Summary

There’s quite a lot to think about with the new guidance, and what’s right in one situation may not be right in another. It’s up to you to consider the factors (alongside what you need to achieve), but as usual understanding the landscape as much as possible helps you make the best decision. My thoughts are to consider publishing intranets and collaboration sites differently – but hopefully this post at least helps you with some detail around what to think about!