Find file
110cad7 May 26, 2016
@roharp @SPDoctor @VesaJuvonen @Lauragra
271 lines (169 sloc) 36.2 KB

Branding and site provisioning solutions for SharePoint 2013 and SharePoint Online

The introduction of the Cloud Add-in Model and add-ins for SharePoint provides alternatives to existing, established ways of branding and provisioning SharePoint sites.

Applies to: Office 365 | SharePoint 2013 | SharePoint Online

Up to now, you might have used the SharePoint feature framework, site templates, web templates, and site definitions to provision your sites and site collections. The remote provisioning pattern shows you how to create custom add-ins for SharePoint that provision site branding and perform other site provisioning tasks. The articles in this section provide information about using add-ins for SharePoint to provision and manage site branding, a pattern that is sometimes referred to as remote provisioning.

What you need to know about SharePoint

To use the branding and site provisioning capabilities in SharePoint, you'll need to be familiar with the following:

  • Key SharePoint terms and concepts.

  • The hierarchy of SharePoint structural elements.

  • Types of SharePoint sites and why you would use them.

  • The file system and content databases, and how they work together.

  • File customization states and their long-term impact on upgrades.

  • add-ins for SharePoint.

  • Client-side programming in SharePoint with the .NET client-side object model (CSOM) and REST APIs.

Key SharePoint terms and concepts

The following table lists terms and concepts that are useful to know as you start to work with SharePoint site provisioning and branding with the remote provisioning pattern.

SharePoint terms and concepts

Term or concept Description For more information
app for SharePoint Lightweight web applications that integrate popular web standards and technologies to extend the capabilities of a SharePoint website by using the Cloud Add-in Model. Build add-ins for SharePoint
App web The website from which an add-in is deployed. Host webs, add-in webs, and SharePoint components in SharePoint 2013
Approval workflow Workflows specific to publishing sites that specifies who approves the publication of a page and when. SharePoint 2013 approval workflow, Get started with workflows in SharePoint 2013
ClientContext A central object that serves as a "center of gravity" for all SharePoint CSOM and JSOM operations. T:Microsoft.SharePoint.Client.ClientContext
Cloud Add-in Model add-ins for SharePoint are self-contained pieces of functionality that extend the capabilities of a SharePoint website. You can use the Cloud Add-in Model to author and deliver secure, reliable, flexible, and consistent add-ins for SharePoint. Overview of add-ins for SharePoint
Content database Content databases store all content for a site collection, including the following:
  • Site documents and files in document libraries

  • List data

  • Web Part properties

  • User names and rights

Database types and descriptions
CSOM Client-side object model. A model for writing client-side code for SharePoint using the .NET Framework. Get started using the client object model with external data in SharePoint 2013
[MS-CSOM]: SharePoint Client Query Protocol
SharePoint 2013 .NET Server, CSOM, JSOM, and REST API index
Hive SharePoint's physical files; the files in the file system. These files are distinct from content stored in a content database. The following is the location of the hive. %program files%/Common Files/Microsoft Shared/Web Server Extensions/15/
Host web The website on which an add-in is installed. Host webs, add-in webs, and SharePoint components in SharePoint 2013
OneDrive for Business A personal library for storing and organizing work documents that are shareable within your organization. OneDrive for Business is different from OneDrive OneDrive for Business is different from your team site
Remote provisioning A model that provisions sites by using templates and code that runs outside SharePoint in a provider-hosted add-in. Site provisioning techniques and remote provisioning in SharePoint 2013
Self-service site provisioning using add-ins for SharePoint 2013
REST A stateless architectural style that abstracts architectural elements and uses HTTP verbs to read and write data from webpages that contain XML files. How to: Set custom permissions on a list by using the REST interface
Root web The first web inside of a site collection. The root web is also sometimes referred to as the "Web Application Root."
SharePoint Online Cloud-based SharePoint offering in Office 365. SharePoint Online General Reference
Site A group of sites that share the same owner and administrative settings, such as permissions. T:Microsoft.SharePoint.Client.Web
Site collection A group of sites that share the same owner and administrative settings, such as permissions. Create a site collection in SharePoint 2013
Site provisioning A process for equipping sites with the features, structure, brand, and other functionality. Site provisioning techniques and remote provisioning in SharePoint 2013 Self-service site provisioning using add-ins for SharePoint 2013
Subsite A single SharePoint site in a SharePoint site collection. A subsite can inherit navigation and permissions from a parent site, or it can have unique permissions and navigation. You can create subsites that are based on the root site collection, or sites based on other site collections. You can choose to inherit permissions from the site collection or specify unique permissions for the subsite.

Hierarchy of SharePoint structural elements

Conceptually, the hierarchy of SharePoint objects is expressed in terms of containers: the types of objects and the type of the hierarchy contain all the types of objects below them in the hierarchy. Table 2 lists the hierarchy of SharePoint structural elements.

Table 2. SharePoint structural elements

Object type (in hierarchical order) Description
Web applications Applications that exist on a server and respond to requests from a browser. Web applications are the central structure in Internet Information Services (IIS). In SharePoint, a web application is a website with a unique URL and a separate content database stored in SQL Server.
Site collections Containers of sites that define permissions, and that can define some aspects of branding, depending on the configuration, for all sites within the container.
Sites A collection of lists, libraries, structure, navigation, and look and feel elements usually organized around a central topic or theme. Sites that are children of other sites in the same site collection are sometimes called subsites. A subsite is a site that is stored in a subfolder of the parent website. A subsite can inherit permissions and navigation structure from its parent site, or administration and authoring permissions might be unique for the subsite. Subsites can have child subsites.
Apps, lists, and document libraries Containers of content and data that are organized into specific structures. The Master Page Gallery is a special document library in SharePoint 2010 publishing sites where all branding elements - master pages, page layouts, JavaScript files, CSS, and images - are stored by default. Every site has its own Master Page Gallery. In Team sites, the master page comes from the site, not the site collection.
Items Individual pieces of content or data that are contained in add-ins, lists, and document libraries.

add-ins for SharePoint

add-ins for SharePoint are lightweight solutions that don't install on the SharePoint host server, which means they don't make excessive API calls to the host server. You can build add-ins for SharePoint by using the Cloud Add-in Model. Users can discover and download add-ins from the Office Store or from the enterprise's App Catalog. For more information, see Overview of add-ins for SharePoint.

File system and content databases, and how they work together

To understand your branding options and the implications that site customization can have on upgrade and migration, you'll need to understand the SharePoint file system and content databases.

File system

SharePoint stores files in the file system ("hive"). In SharePoint 2013, this location is called the "15-hive". The following is the path to the 15-hive.

`%program files%/Common Files/Microsoft Shared/Web Server Extensions/15/`

The 15-hive includes several subfolders that store files you'll use when branding and provisioning sites.

Content databases

Content databases store SharePoint content objects, such as site collections. A content database is automatically installed for every site collection when you deploy SharePoint 2013. All the content for a site collection is stored in one content database on one server. However, a content database can be associated with more than one site collection, and you can attach content databases to a SharePoint web application. You might need to move content from one content database to another, for example when the size of the content will soon exceed the size of the content database.

Some characteristics of a content database vary depending on how the site collection is used. For example, sites are often write-intensive, while other types of content, such as read-only documents, are read-intensive. How content is used affects aspects of the content database, such as size and performance.

File customization states and their effects on upgrade

The state of SharePoint files and content affects how easy it is to apply updates, and controls whether SharePoint serves the file from the content database or the file system. By default, all SharePoint files are uncustomized and ghosted, and reside in matching states in the SharePoint file system and in the content database. When a file, a content database entry, or both are used in specific ways or changed, the state of that content might be affected.

Table 3. File and content states

File or content state Definition Comment
uncustomized An attribute associated with a file that indicates that it hasn't been modified. More than one copy of a file can point to the same source. This makes it easier for designers to implement changes.
customized An attribute associated with a file that indicates that it has been modified. After a file becomes customized, it becomes more difficult to apply broad updates.Be very careful about what you customize. As a general rule, it's better to use the default SharePoint files and functionality than to customize system files or introduce customizations that need to be manually updated.
ghosted A file with a source that is stored outside the content database. A pointer in the content database (the ghost of the file) still exists that tells SharePoint to look for the file's source on the server's file system.
unghosted An uncustomized version of the source file resides in the content database. Example: The SharePoint 2013 Design Manager creates a sandboxed solution to package branding files. It's never added to the file system of the server, therefore by definition its files are considered ghosted. But, the files it deploys are still in an uncustomized state.

Note If a file has been customized, it won't be updated when you install new service packs or the SharePoint Online service is updated.

Site branding and provisioning with the Cloud Add-in Model

In SharePoint 2013, you can use custom CSOM code in add-ins for SharePoint to provision SharePoint site collections, sites, and subsites with branding elements. This site provisioning pattern is called remote provisioning. SharePoint is increasingly focused on cloud-based deployments, so this pattern was created to help you use SharePoint's out-of-the-box capabilities to provision site branding in a way that reduces complexity and long-term operational costs.

What can I do with the Cloud Add-in Model?

Sometimes, there is no correlation between features in full-trust code and the Cloud Add-in Model. When developing a customization based on add-ins for SharePoint and the Cloud Add-in Model, consider an alternative approach rather than a direct conversion, and strive to keep customizations as simple as possible. Here are some examples:

  • Replace event receivers with remote event receivers (see How to: Create a remote event receiver).

  • Replace site templates, web templates, and site definitions with remote provisioning. This works for both subsites and site collections.

  • Replace timer jobs with Microsoft Azure or on-premises worker roles.

Some things, such as HTTP modules and HTTP handlers can not be built with the Cloud Add-in Model. Before you try to replicate an existing customization in the Cloud Add-in Model, first consider why these customizations were built and whether an out-of-the-box SharePoint feature can work.

Remote provisioning pattern

Remote provisioning uses new add-in patterns to move provisioning logic outside of the SharePoint farm entirely. This approach eliminates the need to use the feature framework or other customizations in the SharePoint farm, and instead enables you to control customizations outside of SharePoint. This approach makes it possible to update and change the provisioning engine without affecting SharePoint availability. For more information about the feature framework, see Site Definitions and Provisioning: the Feature Framework. Aspects and implementations of the remote provisioning pattern are documented in detail in this section. You may find it useful to get started with the following introductions to the pattern:

In the simplest implementation of the remote provisioning pattern, provisioning requirements are stored in a SQL Server or SQL Azure database or XML file; then, an add-in for SharePoint reads requirements from the data source, reads branding elements from their source location, and applies branding elements to the target site based on the provisioning requirements.

The branding and provisioning code samples follow this sequence of events to show the remote provisioning pattern.

Table 4. Basic remote provisioning sequence and associated samples

Step Description Samples Article
1 The user requests a change to the site through a form, which kicks off an approval workflow. The data that the user submits via the request form are stored using potentially any data storage format (SQL, SQL Azure, XML).

SharePoint 2013: Use workflow to provision a SharePoint site (host web)

SharePoint 2013: Use workflow to provision a SharePoint site (app web)

SharePoint 2013 site provisioning
2 If the workflow is approved, the add-in for SharePoint calls the stored data and provisions the site according to the metadata that user submitted in step 1.

Provision sites in batches with the add-in model

SharePoint 2013: Use workflow to provision a SharePoint site (host web)

SharePoint 2013: Use workflow to provision a SharePoint site (app web)

SharePoint 2013: Use add-ins for SharePoint to provision on-prem site collection

SharePoint 2013 site provisioning
3 The add-in for SharePoint scopes provisioning to the instructions in the request form by using the data available in the add-in web and content database. During this stage, applicable branding elements are provisioned to the site.

SharePoint 2013: Use an add-in for SharePoint to configure CSS

SharePoint 2013: Use an add-in for SharePoint to apply a theme to a SharePoint site

SharePoint 2013: Brand a SharePoint OneDrive For Business site

SharePoint 2013: Provision custom CSS to a site with remote provisioning

SharePoint 2013: Use an add-in for SharePoint to provision a wiki page

SharePoint pages and the page model

SharePoint site branding and page customization solutions

SharePoint 2013 site provisioning

Note Table 4 lists the steps that might be typical of a remote provisioning scenario. The samples you use depend on the approach that works best for your enterprise. For example, if you don't have a business need to create a custom approval workflow, you won't use that sample.

Figure 1. Example of a site provisioning and branding workflow using the remote provisioning pattern

A flowchart that shows the site provisioning and branding workflow using remote provisioning

How remote provisioning affects pre-existing site content

Depending on the specific site elements you want to provision, your code will override default or pre-existing site content with a hook for the remote provisioning add-in for SharePoint. The add-in will select site templates and other capabilities based on the provisioning requirements stored in the database, without configuring SharePoint at all.

The basic remote provisioning pattern is the same regardless of additional requirements. However, when you plan to use this pattern to provision site branding, map your brand development strategy in the context of the customization capabilities that SharePoint CSOM, JSOM, and REST APIs provide (the code samples described in this section use CSOM). Also consider:

  • Site architecture. Are you building an Internet-facing site, an intranet site, or an extranet that requires authorized users to log on through the Internet-facing site to access company data?

  • The degree of control that specific users have to define and request provisioning requirements. Should users be able to specify custom provisioning options using a form? Are changes applied to the site automatically, only after people with decision-making power approve the changes, or are they managed by a governance policy?

  • The types of branding customizations you want to apply (structural, look and feel, or both).

Branding and site provisioning code samples

The code samples described in this section show the core scenario and extend it to cover some more specific use cases. The articles in this section also include some code examples. The following tables list and describe the samples.

Table 5. Site provisioning samples

Sample Description Related article
Batch Provisioning Provisions site collections in a console app. SharePoint 2013 site provisioning
Provisioning.Pages Shows how to use the remote provisioning model to provision a Wiki page and add remote Web Parts and HTML from the Wiki page. SharePoint pages and the page model
SiteProvisioningWorkflow Provisions site collections with a workflow on the host web and a remote event receiver. SharePoint 2013 site provisioning
SiteProvisioningWorkflowAppWeb Provisions site collections with a workflow on the add-in web and a remote event receiver. SharePoint 2013 site provisioning

Note The BatchProvisioning, SiteProvisioningWorkflow, and SiteProvisioningWorkflowAppWeb samples demonstrate the core concepts and functions of the remote provisioning pattern. The ProvisionWikiPages sample addresses a specific use case (Wiki page provisioning).

Table 6. Branding samples

Sample Description Related article
Branding.Theme Shows how to apply a theme (CSOM). SharePoint site branding and page customization solutions
OD4B.Configuration.Async Shows how to use the remote provisioning model to provision a Wiki page and add remote Web Parts and HTML from the Wiki page. SharePoint site branding and page customization solutions
Branding.AlternateCSSAndSiteLogo Shows how to set custom CSS to the host site by using a user customer action and embedded JavaScript (CSOM). SharePoint site branding and page customization solutions
Provisioning.OnPrem.Async Provisioning.SiteCol.OnPrem Shows how to use a service to encapsulate all of the information in SharePoint host web to thePrem) Shows how to use a service to encapsulate all o the information in SharePoint host web to the add-in web, and get a web, and get a list of site collections in a specified web application and create a content type with a specific ContentTypeId. This sample is especially useful when you want to use the remote provisioning pattern to provision sites using add-ins for SharePoint, but the CSOM member you need to complete your scenario is not yet available in CSOM.

SharePoint branding workflow

Branding a SharePoint website is a lot like branding other websites. You use web technologies that you're familiar with, such as HTML, CSS, and JavaScript to build the structure, look and feel, and custom behavior of your sites. SharePoint is also based on ASP.NET, and uses a page model that is very similar to the ASP.NET master page/page layout model. The page model encompasses the structure and provides hooks and logic for applying look and feel elements.

SharePoint provides several Web Parts you can use to incorporate data views, images, scripts, search results, and more into your site design. Composed looks provide an easy way for users to customize the look and feel of their site while reinforcing designer and IT department control over design details and look and feel options that are available, and both the theming engine and custom CSS capabilities open the door for more advanced branding customizations.

The branding design and development workflow for SharePoint websites closely resembles the design workflow the industry uses:

  • Plan your site architecture and design.

  • Create design assets using familiar web design tools and technologies.

  • Build your site using SharePoint tools such as Design Manager.

  • Package your site design, and use add-ins for SharePoint and the remote provisioning pattern to provision site branding.

Note Applying branding in SharePoint means modifying the look and feel of a default SharePoint site. This can include making both structural and cosmetic changes to the site's appearance

Branding cost and complexity

Branding changes range from low-cost and simple to high-cost and complex. Through the UI, users can apply composed looks, which include a background image, color palette, fonts, and a master page associated with these elements, and a preview file associated with the master page. You can use the SharePoint 2013 theming engine to create your own themes, and you can create custom CSS to modify the look and feel of your site.

Important Although it's possible to create custom master pages and other structural elements as part of a custom branding project, the long-term cost of supporting structural customizations can be high, and might make it more costly for your organization to apply upgrades and support the long-term applicability of short-term investments in customization.

Branding SharePoint sites hosted on-premises or on a dedicated farm

You can use the remote provisioning pattern to brand Team sites, Publishing sites, and OneDrive for Business sites that are hosted on-premises or on a dedicated farm at both the site collection and subsite level.

SharePoint Online

Part of planning a SharePoint branding project is deciding which types of site(s) you want to build, brand, and provision. SharePoint Online licensing affects whether publishing site capabilities are available to you. While all licenses enable you to specify at least one public website that has some of the features of a SharePoint Server Publishing site, not all licenses provide full Publishing site capabilities.

Table 7. Site options in SharePoint Online

Office 365 edition Team site Public website Publishing site Notes
Small Business Yes Yes No Includes one Team site and the public website. Does not include Publishing site functionality. The public website capabilities were designed with small business in mind.
Enterprise Yes No Yes Includes a Team site collection at the root web application for the domain that does not include Publishing, and you can create new Publishing site collections under that root web application.

For more information, see Select an Office 365 plan for business and Model: Design and branding in SharePoint 2013.

When should I customize?

Most functionality you need to meet your business needs is available out-of-the-box in SharePoint. Therefore, before creating a customization, determine whether there is an actual business case for creating the customization and what the long-term costs of creating and supporting this customization would be to the enterprise. How are features and functionality provided for end users? Look at business goals and user experience considerations before technology.

When working with an existing custom SharePoint solution and weighing whether and how to migrate it to the Cloud Add-in Model, first understand why the customization was done and what purpose it serves.

When considering moving an existing customization from full-trust code to the Cloud Add-in Model, there usually isn't a one-to-one relationship between features and functionality. Rather than trying to find a one-to-one match between server-side and client-side code, consider alternative approaches. Table 8 maps some commonly used concepts and functionality of SharePoint solutions to their equivalents in add-ins for SharePoint.

Table 8. Mapping SharePoint concepts to add-ins

Task In SharePoint solution In add-ins for SharePoint Guidance
Display information in SharePoint pages Web Parts App Parts Web parts run on the SharePoint Server with user permission or full-permissions/elevated privilege.App parts run in the browser or on an external server with an app identity with specifically granted permissions. They are completely isolated on the client in their own domain. Add-in parts are executed outside of SharePoint and incur no performance impact on the SharePoint Server.
How to: Create add-in parts to install with your add-in for SharePoint
Create and manage notifications Event receivers and feature receivers Remote event receivers and add-in event receivers Event receivers and feature receivers require server-side code and can't notify external systems of events.Remote event receivers use client-side code, can be used in SharePoint solutions or add-ins for SharePoint, and can notify external systems of events.App event receivers execute code when add-ins are installed, uninstalled, or upgraded.
Handling events in add-ins for SharePoint How to: Create an event receiver for an add-in for SharePoint
Access data the .NET server object model (SSOM), .NET client object model (CSOM), and OData .NET client object model (CSOM, JSOM), OData, REST, cross-domain libraries How to: Complete basic operations using SharePoint 2013 client library code
How to: Complete basic operations using JavaScript library code in SharePoint 2013
Get started with the SharePoint 2013 REST service
.NET client API reference for add-ins for SharePoint
JavaScript API reference for add-ins for SharePoint
REST API reference and samples
Package and deploy Solution packages (WSPs, feature packages) App catalog and Office Store Solution packages are difficult to deploy across a SharePoint farm.You can publish an add-in for SharePoint to the Office Store if you want to make it publicly available or sell it. Use the add-in catalog to make an add-in for SharePoint available within your organization.Guidance and code samples in the solution pack demonstrate how to use add-ins for SharePoint to provision branding elements to your SharePoint site. How to: Set up an add-in catalog on SharePoint Online
How to: Set up an add-in catalog on SharePoint
Publish add-ins for Office and SharePoint to make them available to users
Choose patterns for developing and hosting your add-in for SharePoint
Use external data External content types App-scoped external content types SharePoint site administrators or SharePoint Designer users must create and/or install external content types, which, can be installed only at the farm level.App-scoped external content types apply only to the add-in for SharePoint for which they were created, require no administration, and can access OData sources.
App-scoped external content types in SharePoint 2013
How to: Create an external content type from an OData source in SharePoint 2013
Add custom pages and master pages Application pages and site pages Web-hosted pages Application pages are shared across all sites on the server and are hosted on SharePoint.Site pages are hosted by SharePoint, and require that page controls be listed in a safe controls list.While application pages are ideal for custom code, custom code on site pages will break after customization. Instead, use Web hosted pages. They are designed to be customizable, support the use of built-in Web Parts on site pages, are hosted externally, and are available anywhere the add-in is installed.

In this section

Additional resources