SharePoint metadata, site navigation, and publishing site features

This article explains how to manage metadata and customize site navigation and publishing site features in SharePoint Online by using the add-in model. It also covers ways to work with common web programming patterns and libraries to help customize SharePoint publishing site branding.

Terms and concepts

Table 1. Key metadata, navigation, and publishing terms and concepts

Term or concept Description and guidance
Content Search web part A SharePoint web part that displays dynamic search content on pages in ways that you can easily format.For more information, see: Configure Search Web Parts in SharePoint Server, Configure a Content Search Web Part in SharePoint, Search features in SharePoint Online
ContentTypeId Unique identifiers of content types that are designed to be recursive.For more information, see ContentTypeId class (CSOM).
Content type A reusable, centralized collection of metadata (columns), workflow, behavior, and other settings for a category of information.For information, see:- Columns, Creating content types, Custom information in content types
Content type hub Part of the Managed Metadata service application, which is a hub site that publishes content types to other site collections.Allows you to publish, republish, and unpublish content types from a central location.For information, see:- Publish a content type from a content publishing hub, View error logs for content type publishing
Device channels A method for rendering publishing site pages in multiple ways by using different designs that target multiple devices.For more information, see Add a Device Channel Panel snippet in SharePoint.
Display template Used in web parts that use search technology, display templates control the rendering of the results of queries made to the search index.Display templates are available for all Search web parts.For more information, see Display template reference in SharePoint Server.
Managed navigation Site navigation powered by the SharePoint managed metadata service (taxonomy). Use it to build site navigation derived from a managed metadata taxonomy. Managed navigation often works best with the product catalog.
Managed metadata A hierarchical collection of centrally managed terms that you can use to define and attribute items in SharePoint.You can use managed metadata to manage content type publishing and to create taxonomies.In SharePoint and SharePoint Online, the managed metadata service is used to create managed navigation—site navigation powered by taxonomy.For more information, see: Customizing Navigation Controls and Providers in SharePoint Server 2010 (ECM), Introduction to managed metadata, Introduction to managed metadata in SharePoint Server 2010, Managed metadata administration (SharePoint Server 2010), Managed metadata and navigation in SharePoint, Managed navigation in SharePoint, Migrating Managed Metadata in SharePoint Server 2010
Navigation namespace Contains client object model (CSOM) classes that support site navigation for publishing sites.
Taxonomy namespace Contains CSOM classes that support taxonomy features.For more information, see Synchronize term groups sample SharePoint Add-in.
Pinning Similar to reusing a term, pinning maintains a shared relationship between the source term and the reuse instance.For example, the shared relationship can span across site collections in a cross-site publishing scenario. Any time the term is added or removed, that action is updated across the hierarchy anywhere the term is pinned.For more information, see Use code to pin terms to navigation term sets in SharePoint.
Product catalog For information, see the following:- Cross-site publishing in SharePoint, Configure cross-site publishing in SharePoint Server
Snippet A piece of HTML functionality that you can add to the HTML file generated by the Design Manager. For example, you might want to add a Device Channel panel to your publishing page—there's a snippet for that. The following articles provide some examples: Add a Device Channel Panel snippet in SharePoint, Add a web part zone snippet in SharePoint, Add a Security Trim snippet in SharePoint
Structured navigation For information about using structured navigation, see How to: Customize Navigation in SharePoint Server 2010 (ECM).

Prerequisites for using CSOM to brand publishing sites

By default, web content published to public-facing SharePoint on-premises websites is available to anonymous users. By default, both CSOM and REST are not available to anonymous users.


This scenario presents a potentially serious threat to on-premises SharePoint sites. Before you use the remote provisioning model described in Use remote provisioning to brand SharePoint pages to provision branding to publishing sites, make sure that your site's security and permissions are set correctly, and consider the security implications of anonymous access.

In the event that the site administrator creates a new web application that includes a site collection that uses the publishing template and also enables anonymous access, anonymous access will be available to every user of the site when the application is uploaded to the add-in catalog. Because anonymous access is enabled for the on-premises SharePoint publishing site, what happens if a user who is not authenticated navigates to the site?

If you create a SharePoint-hosted add-in and add a client add-in part to the project, go to Central Administration > Add-ins > Manage Add-in Catalog and create an add-in catalog for the web application, publish the SharePoint-hosted add-in using Visual Studio to create the add-in package, and then upload the add-in package to the add-in catalog. At this point the site collection administrator can add the add-in to the publishing site. The add-in is now available to add to a page on the publishing site.

If you edit the main page of the publishing site and publish the add-in to it, the add-in works as expected. Choosing the linked title of the add-in loads the full-page experience. If SharePoint throws an error, this means that the anonymous user does not have access to use the CSOM. This makes sense because CSOM and REST are not available by default to anonymous users.

Be aware that disabling Use Remote Interfaces permissions can introduce a security risk

In Site Permissions, the Require Use Remote Interfaces permission check box is selected by default. You can clear the Use Remote Interfaces permission check box to allow anonymous users to have access to use CSOM and REST. This decouples the user from Use Remote Interfaces permissions, which grants the user access to SOAP, WebDAV, and CSOM. Clearing the check box also removes the ability to use SharePoint Designer.

There might be times when you want to remove the ability to use SharePoint Designer, but still permit the use of CSOM. The Use Remote Interfaces permission check box enables you to let anonymous users use CSOM without requiring them to have Use Remote Interfaces permissions. When the Use Remote Interfaces permission check box is cleared, and you choose the linked title of the add-in to load the full-page experience, SharePoint does not throw an error. Basic error handling code interprets this case as an anonymous user.


  • When you add apps to public-facing SharePoint sites that use the Publishing template, do not clear the Use Remote Interfaces permissions check box in Site Permissions. Enabling CSOM for anonymous users presents a possible information disclosure risk; it divulges much more information than you would anticipate. That said, even with access to the full CSOM, SharePoint permissions still apply. Anonymous users will only be able to see lists or items that have been explicitly made available to anonymous users. More than what you see on the webpage is available to anonymous users via CSOM and REST.
  • Unless absolutely necessary, do not clear the Require Use Remote Interfaces permission check box when anonymous access permissions are enabled on a SharePoint on-premises publishing site. Doing so could expose both published and unpublished site content to anonymous users, and could leave your site open to a denial of service attack.

Use the ViewFormPagesLockdown feature

To prevent users from accessing forms pages (for example, Pages/Forms/AllItems.aspx) in a public-facing SharePoint site, use the ViewFormPagesLockdown feature. It is designed to prevent users from seeing Created By and Modified By information. This feature removes the permission to View Application Pages or Use Remote Interfaces. When this feature is active, users cannot go to Pages/Forms/AllItems.aspx and view items in that library.

If CSOM and REST are available to all anonymous users—if the Use Remote Interfaces permissions check box is cleared—although they still can't see Created By and Modified By information in the browser, they can use CSOM or REST to access that information.

Configure anonymous access (security trimming)

By configuring anonymous access for the web application, you specify the anonymous policy: Deny write—Has no write access . This means that users with anonymous access can't write to the site—even with CSOM or REST code. Anonymous users can only see the information that was granted to them when anonymous access to the site was configured.

Unpublished pages are not visible to anonymous users by default. They can only see lists that enable anonymous access.


If the Use Remote Interfaces permissions check box is cleared, use the permissions model and other precautions to be sure that anonymous users don't have access to things that they should not.

Prevent denial of service attacks

There is no caching with CSOM. This means that a malicious attacker can query thousands of items from lists simultaneously, all while staying under the default list view threshold and taxing the SharePoint database. This could spread and escalate into a full-blown denial of service attack.

Use app-only policy

You can use app-only policy with provider-hosted add-ins. App-only policy permits the add-in to perform actions that the current user is not authorized to perform. For example, a user with read-only permissions who is notable to write to a list can use an add-in with app-only permissions to write to a list.

For more information, see Authorization and authentication of SharePoint Add-ins and Understanding Authentication and Permissions with Apps for SharePoint and Office (Channel 9 video).

Implement SSL

When you use the add-in model, implement the Secure Sockets Layer (SSL) protocol to manage security of message transmissions on the Internet. SSL works by the remote website, sending an access token in the HTTP header Authorization with a value of Bearer + a base64-encoded (not encrypted) string.


SSL protects your SharePoint publishing site from attackers who want to get to an authorization token and exploit that access.

Remote provisioning and publishing sites

You can use remote provisioning practices to provision branding and other customizations to SharePoint publishing sites.

Publishing sites depend on content types and the ContentTypeId, which links content types to page layouts and display templates. Customizing and provisioning SharePoint publishing page content depends on this functionality. Other aspects of custom publishing site provisioning behavior, such as managed metadata services and managed navigation, do not depend on ContentTypeId and are fully supported in CSOM.

Other publishing site customization options, such as device channels and display templates, don't require custom CSOM. They depend on Design Manager features, CSS, and HTML. They are post-provisioning customizations that you build from scratch and do not need to migrate.

Managed metadata

The managed metadata feature, first introduced in SharePoint 2010, enables you to define a custom hierarchy, or taxonomy, of metadata tags for use in SharePoint. If you want to create a custom site navigation, you can use the managed navigation feature, which is built on the managed metadata infrastructure.

A taxonomy is a hierarchical classification of words, labels, or terms that are organized into groups based on similarities. The smallest unit in a SharePoint taxonomy is the term. Terms can be grouped into term sets. Term sets can be grouped by affinity into larger groups.

For a brief introduction to taxonomy in SharePoint, see A brief introduction to Enterprise Managed Metadata in SharePoint 2010 and Introduction to managed metadata in SharePoint 2010.

SharePoint 2013 introduced new APIs and functionality to the managed metadata feature set.

Managed metadata programming model

For SharePoint, the .NET Server programmability model for managed metadata is defined in the following set of namespaces:

The equivalent CSOM classes are in the Client.Taxonomy namespace namespace.

Unlike some other areas of the SharePoint object model, for managed metadata, there is a close affinity between the .NET Server programming model classes and members and the CSOM classes and members.

The following are some key differences:

  • CSOM does not support content type synchronization.
  • The Group class, which represents the top layer of organization in the TermStore class, is only available in the .NET Server object model. Its equivalent in CSOM is the TermGroup class.
  • The GroupCollection class, which represents a collection of Group objects, is only available in the .NET Server object model. Its equivalent in CSOM is the TermGroupCollection class class.
  • CSOM includes the CustomPropertyMatchInformation and LabelMatchInformation classes that keep custom property and label data in sync with the server.

The following table compares classes in the .NET Server object model and the CSOM object model.

Table 2. Comparison of classes in the two models

.NET Server object model Equivalent CSOM API
Microsoft.SharePoint.Taxonomy.ChangedGroup Microsoft.SharePoint.Client.Taxonomy.ChangedGroup
Microsoft.SharePoint.Taxonomy.ChangedItem Microsoft.SharePoint.Client.Taxonomy.ChangedItem
Microsoft.SharePoint.Taxonomy.ChangedItemCollection Microsoft.SharePoint.Client.Taxonomy.ChangedItemCollection
Microsoft.SharePoint.Taxonomy.ChangedItemType Microsoft.SharePoint.Client.Taxonomy.ChangedItemType
Microsoft.SharePoint.Taxonomy.ChangedOperationType Microsoft.SharePoint.Client.Taxonomy.ChangedOperationType
Microsoft.SharePoint.Taxonomy.ChangedSite Microsoft.SharePoint.Client.Taxonomy.ChangedSite
Microsoft.SharePoint.Taxonomy.ChangedTerm Microsoft.SharePoint.Client.Taxonomy.ChangedTerm
Microsoft.SharePoint.Taxonomy.ChangedTermSet Microsoft.SharePoint.Client.Taxonomy.ChangedTermSet
Microsoft.SharePoint.Taxonomy.ChangedTermStore Microsoft.SharePoint.Client.Taxonomy.ChangedTermStore
Not applicable. Microsoft.SharePoint.Client.Taxonomy.ChangeInformation
Not applicable. Microsoft.SharePoint.Client.Taxonomy.CustomPropertyMatchInformation
Microsoft.SharePoint.Taxonomy.FeatureIds Not applicable.
Microsoft.SharePoint.Taxonomy.Group Not applicable.
Microsoft.SharePoint.Taxonomy.HiddenListFullSyncJobDefinition Not applicable.
Microsoft.SharePoint.Taxonomy.ImportManager Not applicable.
Microsoft.SharePoint.Taxonomy.Label Microsoft.SharePoint.Client.Taxonomy.Label
Microsoft.SharePoint.Taxonomy.LabelCollection Microsoft.SharePoint.Client.Taxonomy.LabelCollection
Not applicable. Microsoft.SharePoint.Client.Taxonomy.LabelMatchInformation
Microsoft.SharePoint.Taxonomy.MobileTaxonomyField Microsoft.SharePoint.Client.Taxonomy.MobileTaxonomyField
Microsoft.SharePoint.Taxonomy.StringMatchOption Microsoft.SharePoint.Client.Taxonomy.StringMatchOption
Microsoft.SharePoint.Taxonomy.TaxonomyField Microsoft.SharePoint.Client.Taxonomy.TaxonomyField
Microsoft.SharePoint.Taxonomy.TaxonomyFieldControl Not applicable.
Microsoft.SharePoint.Taxonomy.TaxonomyFieldEditor Not applicable.
Microsoft.SharePoint.Taxonomy.TaxonomyFieldValue Microsoft.SharePoint.Client.Taxonomy.TaxonomyFieldValue
Microsoft.SharePoint.Taxonomy.TaxonomyFieldValueCollection Microsoft.SharePoint.Client.Taxonomy.TaxonomyFieldValueCollection
Microsoft.SharePoint.Taxonomy.TaxonomyItem Microsoft.SharePoint.Client.Taxonomy.TaxonomyItem
Microsoft.SharePoint.Taxonomy.TaxonomyItemPicker Not applicable.
Microsoft.SharePoint.Taxonomy.TaxonomyRights Not applicable.
Microsoft.SharePoint.Taxonomy.TaxonomySession Microsoft.SharePoint.Client.Taxonomy.TaxonomySession
Microsoft.SharePoint.Taxonomy.TaxonomyWebTaggingControl Not applicable.
Microsoft.SharePoint.Taxonomy.Term Microsoft.SharePoint.Client.Taxonomy.Term
Microsoft.SharePoint.Taxonomy.TermCollection Microsoft.SharePoint.Client.Taxonomy.TermCollection
Not applicable. Microsoft.SharePoint.Client.Taxonomy.TermGroup
Not applicable. Microsoft.SharePoint.Client.Taxonomy.TermGroupCollection
Microsoft.SharePoint.Taxonomy.TermProperty Not applicable.
Microsoft.SharePoint.Taxonomy.TermPropertyToolPart Not applicable.
Microsoft.SharePoint.Taxonomy.TermSet Microsoft.SharePoint.Client.Taxonomy.TermSet
Microsoft.SharePoint.Taxonomy.TermSetCollection Microsoft.SharePoint.Client.Taxonomy.TermSetCollection
Microsoft.SharePoint.Taxonomy.TermSetItem Microsoft.SharePoint.Client.Taxonomy.TermSetItem
Microsoft.SharePoint.Taxonomy.TermStore Microsoft.SharePoint.Client.Taxonomy.TermStore
Microsoft.SharePoint.Taxonomy.TermStoreCollection Microsoft.SharePoint.Client.Taxonomy.TermStoreCollection
Microsoft.SharePoint.Taxonomy.TermStoreOperationException Not applicable.
Microsoft.SharePoint.Taxonomy.TreeControl Not applicable.

Page layouts

For publishing sites, the page layout defines the layout of a specific class of pages. It also defines the customizable regions of a page with content placeholders, which are filled in by content from matching regions on page layouts. Page layouts are usually based on a custom content type. Content types define custom content fields that you want to display on a page. Usually, you'll create a custom content type that includes fields that map to the page design you or your design team had previously planned.

Custom field controls can include text, images, video, or other types of content. SharePoint provides content types for Article, Catalog, Welcome Page, and more. Access the page layout content types by going to Site Settings > Site Content Types. These default page layout content types can serve as parent content types for a custom content type that you create.

All page layout content types inherit from the Page content type. After you create a custom content type, SharePoint displays the columns that the new content type inherited from the Page content type. You can add new site columns to represent new custom fields that you want to display in your page layout. Specify a type for each site column. A type is a value such as "single line of text" or "Full HTML". Consider factors like the degree of descriptiveness or control that the user should have with the field when you specify its type.

After you create all the fields that store the content in your page layout, you can create the page layout in Design Manager. For more information, see Create a page layout in SharePoint.

After you create the page layout, publish it by going to Site Settings > Master pages and page layouts. An HTML file and an ASPX file are present. The HTML file is the master, and you can use any HTML editor to edit it. After you save the file and publish it, Design Manager incorporates changes and converts the updated HTML file to ASPX format, which SharePoint uses to render the page. To publish the page layout, select the HTML file and choose Publish in the ribbon.

To create a page based on the new layout, go to New Page > Page > Page Layouts to see the new page layout in the list of available page layouts. When you choose the new page layout, you should see all the new fields that you specified when you created a new content type for the new page layout. If you view the page and the HTML isn't rendering the way you expect, you can edit the HTML and then use Design Manager to upload the updated file.

There are four kinds of site navigation:

  • Global navigation
  • Local navigation
  • Structured navigation
  • Managed navigation

Global navigation refers to navigation elements that help users move from one SharePoint site to another.

Local navigation refers to navigation within a SharePoint site.

Structured and managed navigation are a bit more involved.

Structured navigation

Structured navigation is a static approach to implementing navigation on SharePoint sites. It usually matches the company's structure, which requires restructuring the SharePoint site navigation. Restructuring work often means moving subsites and/or pages, and refreshing links to point to new targets.

Structured navigation might be sufficient for fairly flat, shallow site structures if your company structure (and therefore site structure) is stable for long periods of time. For deeper and more complex site structures, and companies with publishing site navigation structures that need to grow and change dynamically, managed navigation might be a better option.

For more information about structured navigation, see How to: Customize Navigation in SharePoint Server 2010.

Managed navigation

Managed navigation is built on the core publishing site and taxonomy infrastructure. Managed navigation is bound to a single site collection. It uses term sets and terms to define global and local navigation. For example, you can create a term set that defines global navigation overall, and then add terms to that term set for specific navigation elements in the global navigation.

You can find more information about managed navigation in the following articles:

The following are some key high-level points about classes, methods, and properties in the SharePoint navigation extensibility model for publishing sites:

  • NavigationTerm and NavigationTermSet classes add properties and methods that are specific to managed navigation. Additional state is stored in the CustomProperties property of the NavigationTerm class.
  • NavigationTerm and NavigationTermSet classes have two modes: editable, and read-only. In the .NET Server object model, NavigationTerm objects are stored in the taxonomy navigation cache, which can only be accessed by functions in the TaxonomyNavigation static class.
  • PortalSiteMapNodeProvider objects in the .NET Server object model provide an interface between the data-driven site navigation features and site map data sources. Usually, you write a custom site map node provider to store site maps in an XML file or a data format that's not supported by SharePoint by default.

CSOM includes some unique classes and enumerations:

  • The NavigationLinkType enumeration defines the type of navigation node in a navigation tree. You can specify a node as a root node, a friendly URL, or a standard link.
  • The StandardNavigationScheme enumeration identifies the navigation as either global or local.
  • The StandardNavigationSource enumeration includes three choices for both global navigation and local navigation. Each choice represents a state that corresponds to the configuration of underlying providers.
  • The StandardNavigationSettings class manages the global and local navigation schemes.

The following table lists the publishing navigation classes in the server object model and their CSOM equivalents.

Table 3. Publishing navigation classes

Server object model CSOM
Microsoft.SharePoint.Publishing.Navigation.CachedObjectSiteMapNode Not applicable.
Microsoft.SharePoint.Publishing.Navigation.NavigationComparer Not applicable.
Not applicable. Microsoft.SharePoint.Client.Publishing.Navigation.NavigationLinkType
Microsoft.SharePoint.Publishing.Navigation.NavigationTerm Microsoft.SharePoint.Client.Publishing.Navigation.NavigationTerm
Not applicable. Microsoft.SharePoint.Client.Publishing.Navigation.NavigationTermCollection
Microsoft.SharePoint.Publishing.Navigation.NavigationTermSet Microsoft.SharePoint.Client.Publishing.Navigation.NavigationTermSet
Microsoft.SharePoint.Publishing.Navigation.NavigationTermSetItem Microsoft.SharePoint.Client.Publishing.Navigation.NavigationTermSetItem
Microsoft.SharePoint.Publishing.Navigation.NavigationTermSetView Microsoft.SharePoint.Client.Publishing.Navigation.NavigationTermSetView
Microsoft.SharePoint.Publishing.Navigation.PortalHierarchicalDataSourceView Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalHierarchicalEnumerable Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalHierarchyData Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalListItemSiteMapNode Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalListSiteMapNode Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalNavigation Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalSiteMapDataSource Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalSiteMapDataSourceSwitch Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalSiteMapNode Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalSiteMapProvider Not applicable.
Microsoft.SharePoint.Publishing.Navigation.PortalWebSiteMapNode Not applicable.
Microsoft.SharePoint.Publishing.Navigation.ProxySiteMapNode Not applicable.
Microsoft.SharePoint.Publishing.Navigation.SiteNavigationSettings Not applicable.
Microsoft.SharePoint.Publishing.Navigation.SiteNavigationSettingsWriter Not applicable.
Microsoft.SharePoint.Publishing.Navigation.SPNavigationSiteMapNode Not applicable.
Not applicable. Microsoft.SharePoint.Client.Publishing.Navigation.StandardNavigationSource
Not applicable. Microsoft.SharePoint.Client.Publishing.Navigation.StandardNavigationSettings
Microsoft.SharePoint.Publishing.Navigation.TaxonomyNavigation Microsoft.SharePoint.Client.Publishing.Navigation.TaxonomyNavigation
Microsoft.SharePoint.Publishing.Navigation.TaxonomyNavigationCacheConfig Not applicable.
Microsoft.SharePoint.Publishing.Navigation.TaxonomyNavigationCacheStatistics Not applicable.
Microsoft.SharePoint.Publishing.Navigation.TaxonomyNavigationContext Not applicable.
Microsoft.SharePoint.Publishing.Navigation.TaxonomySiteMapNode Not applicable.
Microsoft.SharePoint.Publishing.Navigation.TaxonomySiteMapProvider Not applicable.
Microsoft.SharePoint.Publishing.Navigation.WebNavigationSettings Microsoft.SharePoint.Client.Publishing.Navigation.WebNavigationSettings

Publishing site features

SharePoint and SharePoint Online include a few features that are specific to SharePoint publishing sites:

  • Device channels enable you to apply a single publishing site design to multiple devices and browsers.
  • Display templates make it possible to brand and customize the appearance of search-related web parts.
  • Image renditions define the dimensions that are used to display images on pages in SharePoint publishing sites.

You can implement these features by using classes in the Publishing namespace of the CSOM programming model.

Device channels and device channel panels

You can use device channels and device channel panels to optimize your site for phones and tablets. By creating a unique channel for each device you want to target, you can render a SharePoint publishing site in more than one way. You can author a single site once, and then map the site and its content to different master pages and style sheets to accommodate different targets.

You create channels by using the Design Manager. After you create a channel, map it to the mobile device or browser with the user agent string of the incoming device.

A device can belong to more than one channel. In that case, you can rank channels in the event that a device belongs. For example, if you create a channel for smartphones and a channel for a specific device configuration, you can rank the channels so that devices with the specific configuration get the channel for them, and all other smartphones get the smartphones channel.

You can create up to 10 channels (including the default channel) in Design Manager. The default channel captures all traffic not caught by one of the other channels. When you create a new channel, complete the fields listed in the following table.

Table 4. Device channels

Field Required or optional? Description
Name Required Identifies the channel to distinguish it from others.
Channel alias Required How code, the query string, cookies, or Device Channel Panels distinguish differences between channels.
Device inclusion rules Required The user-agent substrings that direct requests from devices (each should be on a different line).
Description Optional Describes what this channel does.
Active Optional When checked, the channel uses the related assets for the channel to direct traffic.Otherwise, the query string ?DeviceChannel=<alias> previews the site in the channel.

Device channel panels

After you create device channels, map a master page to each one. Because master page customizations are increasingly rare, this is often the default master page (seattle.master). If you create a unique master page for one or more device channels, you can reference a different CSS file than the master page for the default channel. Page layouts that you create work with every channel you create. You can use the Device Channel Panel control to differentiate page layout designs between channels.

For more information, see Add a Device Channel Panel snippet in SharePoint.

The device channel panel is a container control that is mapped to one or more channels. You can add a device channel panel control to a page layout, and the panel will control what content is rendered in each channel. When one or more of those channels are active when the page is rendered, all the contents of the device channel panel are rendered. Use the device channel panel to determine when to include specific content for one or more specific channels.

Consider a page layout that includes ten fields. Some of those fields are available to all channels, and some should only be rendered in specific channels. For example, consider a mobile header banner field that only renders on smartphones, or a large custom sidebar that only renders on desktops and tablets.

You can also use the device channel panel to change the styling and placement of content on a page by adding channel-specific CSS.

For more information, see Brand snippets by using CSS in SharePoint.

User-agent strings and device channels

A user-agent string is a small string of data that identifies the browser. This information can be sent to the server, which identifies the user agent. Device channels assign a request to a corresponding device channel based on the user-agent string (or substrings) of the device (or browser) the user is browsing from. The front-end web developer creates and sets up channels to capture traffic.

For more information, see What Will Windows Internet Explorer Report as the User-Agent String?

Order of resolution for device channels

When you create multiple channels, put them in the order in which you want them to resolve. The first channel that includes a device inclusion rule that matches the user agent string is used. The following table shows an example of this rule.

Table 5. Example of device inclusion rule

Channel Order 1 Order 2
1 Windows Phone 8 Windows Phone
2 Windows Phone Windows Phone 8
3 Default Default

If order 1 is active, a user requesting a page from a Windows Phone 8 receives device channel 1 labeled Windows Phone 8. A user with any other Windows phone would use channel 2, and everything else would use channel 3. However, using order 2, a user requesting a page from a Windows Phone 8 would always receive device channel 1 labeled Windows Phone and would never use the device channel specified for it.

After you define and order device channels, you can apply different master pages to each channel. By default, all channels will use the master page of the default channel.


CSOM does not include a public API for manipulating device channels and device channel panels.

Display templates

SharePoint publishing sites use display templates to control which managed properties are shown in the search results, and how they appear in the web part. Only Search web parts use display templates; the Content Query web part is not a Search web part, and does not use display templates.

The following table lists the types of display templates, in the order in which SharePoint applies them.

Table 6: Types of display templates

Display template Description
Control Display templates Applies to the entire web part, so SharePoint applies it first, and only once.It provides HTML that structures the overall layout for presenting search results.For example, a control display template might provide HTML for the heading and the beginning and end of a list.This template is rendered only once in the web part.
Group Display templates Applied second, and is applied once per group to the Search Results web part.
Item Display templates Applied last unless a Filter Display template is applied.Item Display templates are applied to each item.This template determines how each item in the result set is displayed in the web part.For example, it might provide the HTML for a list item that is plain text, a list item that contains a picture, or a list item that formats a block of additional links and summary description information to help provide more context for the search results.

SharePoint stores display templates in the Display Templates folder in the Master Page Gallery.Each display template is associated with a content type in the Master Page Gallery.To identify the content type for each display template file while using a mapped drive, use the file name.

The event receivers that convert and update master pages and page layouts from HTML to JavaScript also convert display templates from HTML to JavaScript. The conversion and synching is unidirectional; it does not convert from JavaScript back to HTML.


CSOM does not include a public API for manipulating display templates.

Display template structure

Each display template contains the following:

  • A title.
  • A header that contains custom elements bounded by a <mso:CustomDocumentProperties> tag.
  • A <body> tag that contains a script block.
  • A <div> tag.

The custom document properties provide important information to SharePoint about the display template. Each display template is associated with a content type, which is identified by <ContenTypeId>. You can set other properties that determine whether to hide or show the template in the list of available display templates for the web part, the HTML to JavaScript managed property mapping, the context in which the display template is used, whether a .js file is currently associated with the display template HTML, and whether the conversion from HTML to JavaScript was successful or if warnings and errors were produced.

From within the <script> tag, you can reference external CSS or JavaScript files outside the main display templates HTML file.

If content approval is required in the Master Page Gallery, all CSS, JavaScript, and other resources files must be published before they are available to master pages and page layouts.

For more information, see Require approval of items in a site list or library.

The <div> tag contains an ID that matches the name of the display template HTML file. Place CSS or JavaScript that you want to include that customizes how this web part is displayed in the <div> block.

Display template processing

SharePoint defines display templates in HTML files and JavaScript. If in Design Manager you change an HTML file that contains a display template definition and save changes, SharePoint compiles changes into a JavaScript file that has the same name. SharePoint uses this JavaScript file to render web parts on pages.


Do not edit the JavaScript file that contains the display template definition. Only update the HTML file. The conversion process requires the HTML file to be XML-compliant. For example, use <br>, not <br/>. For more information, see Convert an HTML file into a master page in SharePoint.

Creating new display templates

The easiest way to create a new display template is to modify an existing template. Different display templates change the appearance of different search-related web parts, including the Content Search web part, the Refinement web part, the Taxonomy Refinement web part, and the Search Results web part.

For more information, see:

Properties that can be used in display templates

Before you start to identify properties that you can use in a display template, locate an existing display template you want to build from and then save it with a new name. Display template code is located within the <mso:ManagedPropertyMapping> tag.

<mso:ManagedPropertyMapping msdt:dt="string">'Picture URL'{Picture URL}:'PublishingImage;PictureURL;PictureThumbnailURL','Link URL'{Link URL}:'Path','Line 1'{Line 1}:'Title','Line 2'{Line 2}:'Description','Line 3'{Line3}:'','SecondaryFileExtension','ContentTypeId'</mso:ManagedPropertyMapping>

Next, open Site Settings > Search Schema, and then search for a column name in the Managed property filter box that you want to include in a display template. Select the managed property, and then edit and copy the property name.

<mso:ManagedPropertyMapping msdt:dt="string">'Picture URL'{Picture URL}:'PublishingImage;PictureURL;PictureThumbnailURL','Link URL'{Link URL}:'Path','Line 1'{Line 1}:'Title','Line 2'{Line 2}:'Description','Line 3'{Line3}:'','owsTXTPrice','owsTXTColor'</mso:ManagedPropertyMapping>


In this example, PictureURL is mapped to the first managed property that is present when search is getting results for PublishingImage, PictureURL, or PictureThumbnailURL.

Image renditions

An image rendition defines the dimensions that are used to display images on pages in SharePoint publishing sites. You can use CSOM to instantiate and manipulate image renditions. You can specify metadata such as the height, width, name, and version of an image rendition by using the ImageRendition class. You can use methods and properties in the SiteImageRenditions class to read and write image renditions from a site collection.

For more information, see SharePoint Design Manager image renditions.

SharePoint and web programming techniques

SharePoint designers and developers often want to use standard web programming techniques with SharePoint when they design publishing sites. You can use responsive design, adaptive design, or both device channels and responsive design together.

Responsive design

With device channels, you can build a site once and then target it to multiple devices and browsers. The web development community typically uses responsive design and the "fluid grid" approach to manage how layouts render and to design sites to render correctly on any browser or device. In a responsive design, elements on a page rearrange themselves to fit the user's device and screen orientation.

Responsive design is based on the media queries feature in CSS3. It uses media queries to match the width of the device's display and then applies styles on the client side to render the content. Media queries make it possible for a designer to target specific site properties, such as screen width. You can use media queries to create flexible layouts and images, and conditionally call CSS file alternatives.

For more information and examples, see:

Adaptive design

Adaptive web design (sometimes called adaptive web delivery) is similar to responsive web design. An adaptive design listens for devices or browsers and chooses the optimal way to render pages.

The device channels feature in SharePoint is an adaptive design. It delivers adaptive layouts to each device based on page layout, the specifications of each device channel, and the order defined in the device channel panel.

Device channels and responsive design together

You can use device channels and responsive web design techniques together to build a responsive public-facing SharePoint publishing site. Consider creating a single custom master page for devices, such as phones and tablets, and another for web browsers, and associate each one with a device channel. Then, use fluid grids, flexible images, and CSS3 media queries to craft the best viewing experience for each device and browser that your site needs to support.

Add jQuery to a SharePoint site

You can add jQuery to a SharePoint site at the site level, the page level, or within sections of a page, such as one of the SharePoint page regions or a web part that you've added to the page layout.

You can use a custom action to load jQuery from a document library. Do this if you need to make jQuery available to all pages in a SharePoint site. This approach is flexible but is not easy to control, and this affects the site designer and the administrator. You can store and maintain JavaScript files in the document library, but they can also be accidentally modified or deleted. For this reason, we don't recommend this approach.

You can also load jQuery from the SharePoint root by using ScriptLinkControl. You can use the control to insert scripts that are running on a remote site, and modify the scripts without touching the SharePoint installation. The ScriptLinkControl approach makes sense when you want to use jQuery on an application page or in a web part that is displayed on a page. While provisioning with this option is slow and affects performance because jQuery is added to one page at a time, deploying the jQuery file to the SharePoint rule circumvents other legacy requirements. This is helpful if you need to migrate your SharePoint full trust code (FTC) solution to CSOM, and the migration includes moving and refactoring custom JavaScript and jQuery behaviors.

Finally, you can use the Content Editor web part to load jQuery from a content delivery network (CDN). This is useful if you need to add jQuery to one or a few pages, including wiki and web part pages. Because you're loading the jQuery file from a CDN, you don't need to store extra files on the SharePoint server, and users get the benefit of a distributed, cached version of the jQuery files. SharePoint calls the jQuery file from the CDN, and you can add custom jQuery code that you author to the Content Editor web part.

Build SharePoint provider-hosted add-ins with ASP.NET MVC 5

You can build custom provider-hosted add-ins with the model-view-controller (MVC) pattern in SharePoint. This model separates the application into three interconnected parts. This separates the internal representations of information from the way they are viewed and accepted by the user. The model represents the underlying structure of the software, the view (usually UI elements), and the controller, which are the classes that connect the model and the view.

You can wrap ASP.NET MVC content in SharePoint site master page content. In fact, you can use Office 365 APIs to create a SharePoint Add-in with ASP.NET MVC 5.

APIs for MVC for SharePoint development are defined in Filters\SharePointContextFilterAttribute.cs and SharePointContext.cs. These APIs wrap the steps that the web project takes to seamlessly communicate to SharePoint in a single call, which simplifies the logic you need to implement.

The SharePoint context filter attribute performs additional processing to get standard information when redirected from SharePoint to your remote web application, such as Host Web URL. It also determines whether the add-in needs to be redirected to SharePoint for the user to sign in (for example, bookmarks). You can apply this filter either to the controller or to a view. SharePoint context classes encapsulate all the information from SharePoint so that you can create specific contexts for the add-in web and host web and communicate with SharePoint.

For more information, see Learn About ASP.NET MVC and Introducing MVC support for SharePoint Add-ins.

See also