10 min read

With the 2013 release of SharePoint, Microsoft has added two new capabilities that assist with full-scale branding of SharePoint sites: device channels and design packages. A device channel uses the user agent of the web browser sending the incoming web request to determine which master page to render the content pages with. A common use of the device channels is to detect tablets and smartphones to use a more touch-friendly interface design. For instance, a device channel can be configured to look for an iPad in the following user agent to identify the iPad devices:

Mozilla/5.0 (iPad; CPU OS 7_0_4 like Mac OS X)
AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0
Mobile/11B554a Safari/9537.53

Any portion of the user agent can be used for a device channel. It is important to be specific, but not too specific. Using iPad would apply to all the devices that specify iPad in their user agent, whereas iPad; U; CPU OS 7_0 would only apply to iPads running on iOS Version 7.0.

A design package is a SharePoint solution, packaged as a WSP file containing branding customizations, such as master pages and cascading style sheets. This provides a simple method of exporting a site design from one site and applying it to another. A design package will only contain items that are not default to SharePoint. Default items, such as the included master pages, will be referenced, but are not included as part of the package.

Prior to SharePoint 2013, packaged design solutions could only be created manually or with Visual Studio. Design packages allow any site collection administrator to create and apply packaged designs. This allows the site collection administrators to obtain packaged designs (from third parties, and so on) and apply them, without having to manually upload and configure each piece of the design.

Creating a device channel for mobile devices

One of the most common scenarios for using device channels is to identify the tablet and smartphone browsers. Applying a mobile-specific master page, when appropriate, can provide the users with a design that is more touch friendly and is laid out in a specific manner for smaller screens. In this recipe, we are going to create a device channel that will identify Android, iOS, BlackBerry, WebOS, and Windows mobile devices. There are hundreds of mobile-specific browsers that we can detect with the user agent. However, for this recipe we are going to keep it simple.

Getting ready

In order to view and modify the device channels for a SharePoint site, the SharePoint Server Publishing Infrastructure site collection feature and SharePoint Server Publishing site feature must be activated.

How to do it…

Follow these steps to create a device channel for mobile devices:

  1. Navigate to the site in your preferred web browser.
  2. Select Site settings from the Settings menu.
  3. Select Device Channels from the Look and Feel section.

    You can also navigate to the Device Channels page from the Design Manager page.

  4. Select New Item.
  5. Provide a Name, Description, and Alias for the device channel.

    The Alias field specified will be used when specifying which master page to use with the device channel in the device channel mappings file. We will learn about this in the next recipe, Applying a master page to a device channel.

  6. Specify the Device Inclusion Rules to be included in the device channel.

    Android

    iPad

    iPod

    iPhone

    BlackBerry

    IEMobile

    WebOS

  7. When using multiple device inclusion rules, place each string on a new line to match the user agent. Device Inclusion Rules are simply strings that are looked for in the user agent of incoming web requests.

  8. Mark the Active checkbox and click on Save.

How it works…

Device channels are created and stored in the /DeviceChannels SharePoint list in the root site of a site collection. When an incoming browser request is received, SharePoint checks whether the incoming user agent matches any of the Device Inclusion Rules before selecting the master page to use.

Many web browsers have developer tools that allow changing the user agent reported by the browser. Switching the user agent is one way in which we can test to ensure our device channels are working correctly. Internet Explorer 11, for instance, includes this option in the Emulation section of the F12 Developer Tools.

There’s more…

A device channel may also be created with PowerShell or with code using the server-side object model.

Creating a device channel for mobile devices using PowerShell

Follow these steps to create a device channel for mobile devices using PowerShell:

  1. Get the site using the Get-SPWeb Cmdlet. 
    $web = Get-SPWeb http://sharepoint/site
  2. Get the DeviceChannels list. 
    $list = $web.Lists["Device Channels"]
  3. Add a new SPListItem item to the Items collection of the list. 
    $item = $list.Items.Add()
  4. Assign the values to each of the properties on the SPListItem item. 
    $item["Name"] = "PowerShell"
$item["Alias"] = "PowerShell"
$item["Description"] = "PowerShell Channel"
$item["Device Inclusion Rules"] = "Android`niPad`niPod`niPhone`nBlackBerry
    `nIEMobile`nWebOS"    
$item["Active"] = $true

    When a line break is required within a string, in PowerShell, an escape character can be used. Escape characters in PowerShell use the tilde character. For example, a new line is represented by `n.

  5. Call the Update method on the list to update the Items collection. 
    $item.Update()
  6. Use the Dispose method to discard the SPWeb object. 
    $web.Dispose()

Creating a device channel for mobile devices with code using the server-side object model

Follow these steps to create a device channel for mobile devices with code using the server-side object model:

  1. Open the site collection containing the site in a using statement. 
    using (var site = new SPSite("http://sharepoint/site"))
  2. Open the site in a using statement. 
    using (var web = site.OpenWeb())
  3. Get the DeviceChannels list. 
    var list = web.Lists["Device Channels"];
  4. Add a new SPListItem item to the Items collection of the list. 
    var item = list.Items.Add();
  5. Assign the values to each of the properties on the SPListItem item. 
    item["Name"] = "Code";
item["Alias"] = "Code ";
item["Description"] = "Code Channel";
item["Device Inclusion Rules"] = "AndroidniPadniPodniPhonenBlackBerry
    nIEMobilenWebOS";
item["Active"] = true;

    When a line break is required within a string in C#, an escape character can be used. Escape characters in C# use the backslash character. For example, a new line is represented by n.

  6. Call the Update method on the list to update the Items collection. 
    item.Update();

See also

Applying a master page to a device channel

Once a device channel has been created, it can be configured to use as a different site master page rather than the default site master page. For instance, browsers targeted by a mobile device channel could display the content using the oslo master page whereas all other browsers could display the same content using the seattle master page.

The System Master Page is configured for all device channels and cannot be configured for individual device channels.

How to do it…

Follow these steps to apply a master page to a device channel:

  1. Navigate to the site in your preferred web browser.
  2. Select Site settings from the Settings menu.
  3. Select Master page from the Look and Feel section.
  4. Specify which Site Master Page to use for each device channel.

  5. Click on Save.

How it works…

The master page to device channel mappings are stored in the _catalogs/masterpages/__DeviceChannelMappings.aspx file as XML within the root site of a site collection. For each incoming browser web request, this file is used by SharePoint to determine which master page to use with the content returned to the browser.

There’s more…

A device channel mapping may also be configured with PowerShell or with code using the server-side object model. In this recipe, these two methods are similar. However, the .NET reflection methods used are slightly different. When an object is instantiated with reflection in PowerShell, its public properties and methods become available to the command line. However, when an object is instantiated with reflection in the .NET code, each property and method needs to be searched for before being able to access them.

The methods that provide the functionality to configure the device channel mappings are not publicly exposed in the SharePoint assemblies. As a result, we will use the .NET reflection to instantiate the objects required. It is important to note that non-public classes in the SharePoint assemblies can change between SharePoint versions and updates without notice. Using reflection tools, such as .NET Reflector (http://www.red-gate.com/products/dotnet-development/reflector/) and dotPeek (http://www.jetbrains.com/decompiler/), we can browse the assemblies to adjust the references accordingly.

Applying a master page to a device channel using PowerShell

Follow these steps to apply a master page to a device channel using PowerShell:

  1. Load the Microsoft.SharePoint.dll and Microsoft.SharePoint.Publishing.dll assemblies into the PowerShell session. 
    [Reflection.Assembly]::LoadFrom("C:Program FilesCommon
    Filesmicrosoft sharedWeb Server
    Extensions15ISAPIMicrosoft.SharePoint.Publishing.dll")
    
[Reflection.Assembly]::LoadFrom("C:Program FilesCommon
    Filesmicrosoft sharedWeb Server
    Extensions15ISAPIMicrosoft.SharePoint.dll")
  2. Get the object types for the parameters that will be used when getting the class constructor for the MasterPageMappingsFile object and later instantiating the object. 
    $typeWeb = [Microsoft.SharePoint.SPWeb]
$typeBool = [System.Boolean]
    
$typeMappingFile =
    [System.Type]::GetType("Microsoft.SharePoint.Publishing.Mobile.
    MasterPageMappingsFile, Microsoft.SharePoint.Publishing,
    Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e942
    9c")
  3. Create an array of the object types. 
    $consMappingFileParams = ($typeWeb, $typeBool, $typeWeb)
  4. Get the class constructor for the MasterPageMappingsFile object. 
    $consMappingFile = $typeMappingFile.GetConstructor($consMappingFileParams)
  5. Create an array of the parameters required to instantiate the MasterPageMappingsFile object. 
    $mappingFileParams =
    [System.Array]::CreateInstance([System.Object], 3)
    $mappingFileParams[0] = (Get-SPSite
    http://sharepoint/sitecollection).RootWeb
    $mappingFileParams[1] = $false
    $mappingFileParams[2] = $null

    When invoking a constructor to create an instance of a .NET object in PowerShell, we have to create a System.Object array rather than using a PowerShell array. Even though the base class for a PowerShell array is System.Object[], when calling the Invoke method on the class constructor, it will see it as a PSObject object instead. The same goes for the SPWeb object we are passing as the first parameter. .NET will see the object as a PSObject object instead of a SPWeb object if we use Get-SPWeb. However, if we get the SPWeb object from the SPSite object, it will not get treated as a PSObject object.

  6. Invoke the class constructor to create an instance of the MasterPageMappingsFile object. 
    $mappingFile = $consMappingFile.Invoke($mappingFileParams)
  7. Set the MasterPageUrl property for the device channel on the MasterPageMappingsFile object. 
    $mappingFile["PowerShell"].MasterPageUrl = "/_catalogs/masterpage/oslo.master"
  8. Save the changes using the UpdateSingleChannel method. 
    $mappingFile.UpdateSingleChannel("PowerShell")

Applying a master page to a device channel with code using the server-side object model

Follow these steps to apply a master page to a device channel with code using the server-side object model:

A reference to the Microsoft.SharePoint.Publishing.dll assembly is required for this recipe.

  1. Get the site collection in a using statement. 
    using (var site = new SPSite("http://sharepoint/sitecollection"))
  2. Get the root site of the site collection in a using statement. 
    using (var web = site.RootWeb)
  3. Get the object type that will be used when getting the class constructor for the MasterPageMappingsFile object and later instantiating the object. 
    MasterPageMappingsFile object and later instantiating the object.
    var typeMappingFile =
    Type.GetType("Microsoft.SharePoint.Publishing.Mobile.
    MasterPageMappingsFile, Microsoft.SharePoint.Publishing,
    Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e942
    9c");
  4. Get the class constructor for the MasterPageMappingsFile object. 
    var consMappingFile =
    typeMappingFile.GetConstructor(new Type[] { typeof(SPWeb),
    typeof(bool), typeof(SPWeb) });
  5. Invoke the constructor to create an instance of the MasterPageMappingsFile object. 
    var mappingFile = consMappingFile.Invoke(new object[] { web, false, null });
  6. Get the mappings field of the MasterPageMappingsFile object, and cast the field as an IDictionary. 
    var mappings = (IDictionary)typeMappingFile.GetField("mappings",
    BindingFlags.Instance | BindingFlags.NonPublic).
    GetValue(mappingFile);
  7. Set the MasterPageUrl property for the device channel on the mappings field. 
    mappings["PowerShell"].GetType().GetProperty("MasterPageUrl",
    BindingFlags.Instance |
    BindingFlags.Public).SetValue(mappings["PowerShell"],
    "/_catalogs/masterpage/seattle.master", null);
  8. Set the mappings field of the MasterPageMappingsFile object. 
    typeMappingFile.GetField("mappings", BindingFlags.Instance |
    BindingFlags.NonPublic).SetValue(mappingFile, mappings);
  9. Get the UpdateSingleChannel method from the type of the MasterPageMappingsFile object. 
    var updateMethod = typeMappingFile.GetMethod("UpdateSingleChann
    el",
    BindingFlags.Instance | BindingFlags.Public, null, new Type[]
    { typeof(string) }, null);
  10. Save the changes by invoking the UpdateSingleChannel method. 
    updateMethod.Invoke(mappingFile, new object[] { "Code" });
Packt

LEAVE A REPLY

Please enter your comment!
Please enter your name here