SharePoint. Регистрация CSS и JavaScript с помощью DelegateControl

13 июля, 2016

При создании решений на базе Microsoft SharePoint часто возникает необходимость добавить на сайт, коллекцию сайтов или на всё веб-приложение CSS и JavaScript-файлы. Сделать это можно, используя механизм регистрации этих файлов в DelegateControl'ах.

Демонстрационный проект

Для примера предположим, что у нас есть решение, которое содержит кастомные JavaScript- и CSS-файлы, развертываемые в _layouts, который необходимо зарегистрировать на странице (сайте, коллекции сайтов, веб-приложении):

Начнем с таблиц стилей.

CSS

Для регистрации CSS на странице в SharePoint существует контрол CssRegistration:

Простая регистрация CSS-файла /_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css с помощью контрола CssRegistration выглядит примерно так:


<SharePoint:CssRegistration Name="/_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css" runat="server" />

И результат в браузере:


<link rel="stylesheet" type="text/css" href="/_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css"/>

Возможности CssRegistration на этом не ограничиваются, с помощью него можно успешно решать следующие задачи:

Порядок регистрации CSS

С помощью свойства After можно управлять порядком регистрации CSS на странице, что крайне важно, учитывая правила применение, а точнее переопределения стилей. Если наш кастомный CSS необходимо зарегистрировать на странице после определенного, например SuiteNav.css, то код будет выглядеть вот так:


<SharePoint:CssRegistration After="SuiteNav.css" Name="/_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css" runat="server" />

Результат в браузере:


...
<link rel="stylesheet" type="text/css" href="/_layouts/15/1033/styles/SuiteNav.css?rev=MftMX5e%2Fyc5ksxukBblvoA%3D%3DTAG0"/>
...
<link rel="stylesheet" type="text/css" href="/_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css"/>

Условия регистрации

Для указания условий регистрации CSS существует свойство ConditionalExpression. Для регистрации CSS только для Internet Explorer 8 и выше:


<SharePoint:CssRegistration ConditionalExpression="gte IE 8" Name="/_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css" runat="server" />

Результат в браузере:


<!--[if gte IE 8]>
<link rel="stylesheet" type="text/css" href="/_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css"/>
<![endif]-->

Значение для свойства ConditionalExpression можно указать любое, например http://subpointsolutions.com:


<!--[if http://subpointsolutions.com]>
<link rel="stylesheet" type="text/css" href="/_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css"/>
<![endif]-->

Дубликаты CSS

При использовании контрола CssRegistration не получится зарегистрировать один и тот же CSS-файл дважды, что упрощает жизнь.

Недостатки CssRegistration

Из недостатков контрола CssRegistration стоит отметить то, что не получится использовать токены вроде ~sitecollection и ~site в свойстве After.

Теперь переходим к регистрации CSS-файла с помощью DelegateControl'а.

CssRegistration DelegateControl

Таблицу стилей в SharePoint можно зарегистрировать в DelegateControl, например AdditionalPageHead, который расположен в заголовке страницы. Для этого в качестве контрола указываем тип Microsoft.SharePoint.WebControls.CssRegistration, сборку Microsoft.SharePoint (в моём примере версия 16.0, что соответствует SharePoint 2016) и необходимые свойства, перечисляя их в дочерних элементах Property:


<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Control Id="AdditionalPageHead"
           Sequence="250"
           ControlClass="Microsoft.SharePoint.WebControls.CssRegistration"
           ControlAssembly="Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"
           xmlns="http://schemas.microsoft.com/sharepoint/">
    <Property Name="Name">/_layouts/15/Zhukov.Blog.DelegateControl/css/custom.css</Property>
    <Property Name="After">SuiteNav.css</Property>
    <Property Name="ConditionalExpression">http://subpointsolutions.com/</Property>
  </Control>
</Elements>

Добавляя элемент в возможности разного уровня (сайт, коллекция сайтов, веб-приложение) и активируя её, мы получаем возможность регистрировать таблицы стилей без модификации мастер-страниц или использования для этих целей пользовательских контролов.

Довольно легко можно реализовать, например, стилизацию SuiteBar:

С таблицами стилей разобрались, переходим к JavaScipt.

JavaScipt

Для регистрации JavaScipt используется контрол ScriptLink:

В качестве примера зарегистрируем jQuery-библиотеку, представленную файлом jquery.js, публикуемым в _layouts.

Начнем с возможностей контрола ScriptLink.

Токены в именах

Имя файла скрипта задается в свойстве Name. Можно использовать токены такие как ~site и ~sitecollection, например на сайте http://spapp/site контрол ScriptLink:


<SharePoint:ScriptLink name="~site/js/custom.js" runat="server" />

Результат в браузере:


$lt;script src="/sps/js/custom.js"></script>

Загрузка по требованию

Указав свойство OnDemand равное "True" получаем в браузере:


<script type="text/javascript">RegisterSod("~site/js/custom.js", "\u002fsps\u002fjs\u002fcustom.js");</script>

При этом скрипт не будет загружен явно. Инициализировать его загрузку в дальнейшем можно, например, вызвав метод SP.SOD.executeOrDelayUntilScriptLoaded.

Стас

Дополнительно про SciptLink читаем у Стаса: Загрузка скриптов в SharePoint.

ScriptLink DelegateControl

Регистрация ScriptLink аналогична регистрации CssRegistration. В качестве класса указываем Microsoft.SharePoint.WebControls.ScriptLink, свойства также перечисляем в элементах Property:


<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ControlId="AdditionalPageHead"
             Sequence="160"
             ControlClass="Microsoft.SharePoint.WebControls.ScriptLink"
             ControlAssembly="Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" xmlns="http://schemas.microsoft.com/sharepoint/">
    <Property Name="Name">/_layouts/15/Zhukov.Blog.DelegateControl/js/jquery.js</Property>
    <Property Name="OnDemand">true</Property>
  </Control>
</Elements>

Указанный скрипт после активации фичи будет зарегистрирован в заголовке страницы (ControlId="AdditionalPageHead"). Ровно также можно указывать область определения фичи, меняя уровень страниц, где будет зарегистрирован указанный скрипт.

Исходные коды

Исходные коды доступны на code.msdn. В демонстрационном решении присутствуют две возможности: первая регистрирует jquery,js на странице, вторая - регистрирует таблицу стилей для изменения цвета AppLauncher.