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

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

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

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

Solution Explorer

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

CSS

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

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:

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.

Виталий Жуков

Виталий Жуков

SharePoint архитектор, разработчик, тренер, Microsoft MVP (Office Development). Более 15 лет опыта работы с SharePoint, Dynamics CRM, Office 365, и другими продуктами и сервисами Microsoft.

Смотрите также

Развертывание списков и библиотек с помощью SPFx-решений

Развертывание списков и библиотек с помощью SPFx-решений

SharePoint. Drag-and-Drop Загрузчик файлов

SharePoint. Drag-and-Drop Загрузчик файлов

CSOM. Загрузка файлов

CSOM. Загрузка файлов

SharePoint List REST API. Часть 2

SharePoint List REST API. Часть 2

SharePoint Framework. Создание веб-части на Angular

SharePoint Framework. Создание веб-части на Angular

SharePoint List REST API. Часть 1

SharePoint List REST API. Часть 1

Презентация с доклада о SharePoint Framework

Презентация с доклада о SharePoint Framework

SharePoint Framework. Создаем AngularJS 1.x Client WebPart

SharePoint Framework. Создаем AngularJS 1.x Client WebPart

SharePoint. Расширяем REST API

SharePoint. Расширяем REST API

SharePoint Excel Services. Создаем кредитный калькулятор

SharePoint Excel Services. Создаем кредитный калькулятор

SharePoint Ribbon API. Использование ToggleButton

SharePoint Ribbon API. Использование ToggleButton

SharePoint 2013. How To: настройка входящей почты для разработчиков

SharePoint 2013. How To: настройка входящей почты для разработчиков

Мифы и правда о Linq to SharePoint

Мифы и правда о Linq to SharePoint

5 особенностей SPSiteDataQuery

5 особенностей SPSiteDataQuery

SharePoint 2013. Введение в SharePoint App. Часть 2

SharePoint 2013. Введение в SharePoint App. Часть 2

SharePoint 2013. Введение в SharePoint App. Часть 1

SharePoint 2013. Введение в SharePoint App. Часть 1

Превью для веб-части в SharePoint 2010/2013

Превью для веб-части в SharePoint 2010/2013

SharePoint 2013. Еще немного о новых контролах

SharePoint 2013. Еще немного о новых контролах

SharePoint 2013. Контрол ClientPeoplePicker

SharePoint 2013. Контрол ClientPeoplePicker

SharePoint 2013. Контрол ImageCrop

SharePoint 2013. Контрол ImageCrop

SharePoint 2013. Тип поля Geolocation

SharePoint 2013. Тип поля Geolocation

Создание типа поля в SharePoint

Создание типа поля в SharePoint

SharePoint 2010. Длительные операции с обновляемым статусом

SharePoint 2010. Длительные операции с обновляемым статусом

Linq to SharePoint. Создаем ContentIterator

Linq to SharePoint. Создаем ContentIterator

Linq to SharePoint. Получение данных из другой коллекции сайтов

Linq to SharePoint. Получение данных из другой коллекции сайтов

Linq to SharePoint. Версионность

Linq to SharePoint. Версионность

SharePoint. Получение URL-адреса иконки для документа

SharePoint. Получение URL-адреса иконки для документа

SharePoint 2010. PostBack для Fluent Ribbon API

SharePoint 2010. PostBack для Fluent Ribbon API

Linq to SharePoint. Блокировка документов

Linq to SharePoint. Блокировка документов

Linq to SharePoint. Паттерн Repository

Linq to SharePoint. Паттерн Repository

Linq to SharePoint. Получение мета-данных списка

Linq to SharePoint. Получение мета-данных списка

Linq to SharePoint. Мапинг полей

Linq to SharePoint. Мапинг полей

Linq to SharePoint. Формирование данных для ProcessBatchData

Linq to SharePoint. Формирование данных для ProcessBatchData

Linq to SharePoint. Сравнение производительности с Camlex.NET

Linq to SharePoint. Сравнение производительности с Camlex.NET

Linq to SharePoint. Часть 5. Поля Choice и MultiChoice

Linq to SharePoint. Часть 5. Поля Choice и MultiChoice

Linq to SharePoint. Часть 4. Dynamic LINQ

Linq to SharePoint. Часть 4. Dynamic LINQ

Linq to SharePoint. Особенности. Часть 3

Linq to SharePoint. Особенности. Часть 3

Linq to SharePoint. Особенности. Часть 2

Linq to SharePoint. Особенности. Часть 2

SharePoint 2010. PeopleEditor. Установка значения

SharePoint 2010. PeopleEditor. Установка значения

SharePoint 2010. Настройка входящей почты для кастомного списка

SharePoint 2010. Настройка входящей почты для кастомного списка

Linq to Sharepoint. Особенности

Linq to Sharepoint. Особенности

EntityFramework. Оптимистические блокировки

EntityFramework. Оптимистические блокировки