Шаблоны отображения Дизайнера SharePoint
Важно!
Такая расширяемость доступна только для классического интерфейса SharePoint. Эту возможность нельзя использовать вместе с современным интерфейсом в SharePoint Online, например на сайтах для общения. Мы больше не рекомендуем использовать классический интерфейс и эти методы применения фирменной символики.
В этой статье рассказывается о шаблонах отображения, в том числе об их связи с веб-частями Поиска, принципах структурирования шаблонов, способах сопоставления свойств, использовании переменных и jQuery, а также о создании пользовательских шаблонов отображения в SharePoint.
Общие сведения о шаблонах отображения
Шаблоны отображения в SharePoint — это шаблоны, используемые в веб-частях, в которых применяется технология поиска (в этой статье они называются веб-частями Поиска), для отображения результатов запроса, полученных из индекса поиска. Шаблоны отображения указывают, какие управляемые свойства следует отображать в результатах поиска и как они должны выглядеть в веб-части. Каждый шаблон отображения состоит из двух файлов: версии в формате HTML, которую можно изменить в редакторе HTML, и JS-файла, используемого средой SharePoint.
Примечание.
Только веб-части поиска могут использовать шаблоны отображения. Веб-часть "Запрос контента" не управляется поиском и поэтому не использует шаблоны отображения.
Вы можете просмотреть существующие шаблоны отображения в Дизайнере, но они не создаются в Дизайнере так, как главные страницы и макеты страниц. Для их создания выполните следующие действия.
Откройте сопоставленный сетевой диск в коллекции главных страниц.
Откройте одну из четырех папок, вложенных в папку Шаблоны отображения.
Примечание.
Выбор папки зависит от типа нужного шаблона отображения. Например, если используется публикация на нескольких сайтах, скопируйте шаблон отображения из папки Веб-части контента. Дополнительные сведения см. в статье Справочник по шаблонам отображения в SharePoint.
Скопируйте HTML-файл для существующего шаблона отображения, который похож на то, что нужно вам. Неважно, куда вы скопируете файл, главное, чтобы целевая папка находилась в коллекции главных страниц.
Откройте и измените свою копию в HTML-редакторе.
Используя существующий шаблон отображения в качестве отправной точки для нового шаблона отображения, вы можете воспользоваться полезной информацией о процессе настройки в комментариях шаблонов отображения по умолчанию, а также создать платформу для основных задач, таких как сопоставление полей ввода. Это также гарантирует, что шаблоны используют правильную базовую структуру страниц.
Что происходит, когда вы создаете шаблон отображения, скопировав HTML-файл существующего шаблона в папку Шаблоны для отображения в коллекцию главных страниц:
В том расположении, куда был скопирован HTML-файл, создается JS-файл с таким же именем.
Вся разметка, необходимая среде SharePoint, добавляется в JS-файл, чтобы шаблон отображения был показан правильно.
HTML-файл и JS-файла связываются, чтобы последующие правки HTML-файла синхронизировались с JS-файлом после сохранения HTML-файла.
Примечание.
Синхронизация осуществляется только в одном направлении. Изменения HTML шаблона отображения будут синхронизированы со связанным JS-файлом. В отличие от главных страниц и макетов страниц при использовании шаблонов отображения невозможно работать только с JS-файлом, разорвав связь между файлами. Весь HTML- и JavaScript-код необходимо ввести в HTML-файл.
Общие сведения о связи между шаблонами отображения и веб-частями Поиска
Существует два основных типа шаблонов отображения:
Шаблоны элементов управления, которые определяют общую структуру представления результатов. К ним относятся списки, списки с разбиением по страницам и слайд-шоу.
Шаблоны элементов, которые определяют, как отображается каждый результат в наборе. К ним относятся изображения, текст, видео и другие элементы.
Дополнительные сведения об этих и других шаблонах отображения см. в статье Справочник по шаблонам отображения в SharePoint.
После добавления веб-части Поиска на страницу (например, веб-части "Поиск контента") для настройки веб-части необходимо выбрать шаблон отображения элемента управления и шаблон отображения элемента, как показано на рис. 1.
Рис. 1. Область инструментов веб-части "Поиск контента"
Шаблон отображения элемента управления предоставляет HTML для структурирования общего макета, используемого для отображения результатов поиска. Например, шаблон отображения элемента управления может предоставить HTML для заголовка, а также начала и конца списка. Шаблон отображения элемента управления отображается в веб-части только один раз.
Шаблон отображения элемента содержит HTML-код, который определяет способ отображения каждого элемента в результирующем наборе. Например, шаблон отображения элемента может предоставить HTML-код для элемента списка, содержащего рисунок и три строки текста, которые сопоставляются с различными управляемыми свойствами, связанными с элементом. Шаблон отображения элемента отображается один раз для каждого элемента в результирующем наборе. Если результирующий набор содержит 10 элементов, шаблон отображения элемента создает его HTML-раздел десять раз.
При совместном использовании подобным образом шаблон отображения элемента управления и шаблон отображения элемента создают согласованный HTML-блок, отрисовываемый в веб-части, как показано на рис. 2.
Рис. 2. Комбинированный вывод шаблона отображения элемента и шаблона отображения элемента управления в формате HTML
Дополнительные сведения о шаблонах отображения см. в разделе "Веб-части на основе поиска и шаблоны отображения" статьи Обзор модели страниц SharePoint.
Структура шаблона отображения
HTML-файл, который используется для шаблона отображения это полностью сформированный HTML-документ, но он не представляет полную веб-страницу HTML. SharePoint преобразует части HTML-файл шаблона отображения в JavaScript. В этом разделе описаны четыре основных раздела шаблона отображения.
Тег title
Текст в теге <title> в файле шаблона отображения используется в качестве отображаемого имени в разделе Шаблоны отображения области редактирования веб-части, если веб-часть поиска находится в режиме редактирования. Приведенный ниже пример предназначен для шаблона отображения с именем Item_Picture3Lines.html:
<title>Picture on left, 3 lines on right</title>
Свойства заголовков
Сразу после тега <title> находится набор настраиваемых элементов, ограниченных следующей разметкой:
<!--[if gte mso 9]><xml>
<mso:CustomDocumentProperties>
…
</mso:CustomDocumentProperties>
</xml><![endif]-->
Эти элементы и их свойства предоставляют среде SharePoint важные сведения о шаблоне отображения. В таблице 1 описаны настраиваемые свойства, которые используются в шаблонах отображения.
Примечание.
Не все настраиваемые свойства используются в каждом шаблоне отображения. Кроме того, некоторые свойства можно, изменив свойства файла шаблона отображения в Дизайнере.
Таблица 1. Список объектов CustomDocumentProperties
| Свойство | Описание |
|---|---|
| TemplateHidden |
Логическое значение, указывающее, следует ли скрывать шаблон отображения из списка доступных шаблонов в веб-части. Это значение можно изменить в свойствах файла шаблона отображения. |
| ManagedPropertyMapping |
Сопоставляет поля, предоставляемые элементами результатов поиска в свойствах, доступных для JavaScript. Используется только в шаблонах элементов. |
| MasterPageDescription |
Понятное описание шаблона отображения. Его пользователи увидят в среде редактирования SharePoint. Это значение можно изменить в свойствах файла шаблона отображения. |
| ContentTypeId |
Идентификатор типа контента, связанного с шаблоном отображения. |
| TargetControlType |
Указывает контекст, в котором используется шаблон отображения. Это значение можно изменить в свойствах файла шаблона отображения. |
| HtmlDesignAssociated |
Логическое значение, которое указывает, связан ли с HTML-файлом шаблона отображения JS-файл. |
| HtmlDesignConversionSucceeded |
Указывает, успешно ли выполнено преобразование. Это значение автоматически добавляется в файл SharePoint и используется только в настраиваемых шаблонах отображения. |
| HtmlDesignStatusAndPreview |
Содержит URL-адрес HTML-файла и текст для столбца Состояние ( Преобразование выполнено успешно или Предупреждения и ошибки). Это значение автоматически добавляется в файл SharePoint и используется только в настраиваемых шаблонах отображения. |
Блок скрипта
В теге <body> есть следующий тег <script>:
<script>
$includeLanguageScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Language Files/{Locale}/CustomStrings.js");
</script>
По умолчанию эта строка включается во все шаблоны отображения. Вы можете добавить больше строк кода в теге <script>, чтобы ссылаться на CSS-файлы или другие файлы JavaScript за пределами HTML-файла основного шаблона отображения. В таблице 2 показаны примеры того, как включать другие ресурсы.
Табл. 2. Примеры включения внешних ресурсов в тег скрипта <>
| Что требуется включить: | Используйте следующий код: |
|---|---|
| Файл JavaScript, часть текущего семейства веб-сайтов |
$includeScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/MyScripts.js"); |
| Внешний файл JavaScript |
$includeScript(this.url, "http://www.contoso.com/ExternalScript.js"); |
| CSS-файл, часть текущего семейства веб-сайтов |
$includeCSS(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/MyCSS.css"); |
| CSS-файл в расположении, относящемся к текущему шаблону отображения |
$includeCSS(this.url,"../../MyStyles/MyCSS.css"); |
Примечание.
Если для элементов в коллекции эталонных страниц требуется утверждение контента, все файлы ресурсов (включая CSS- и JS-файлы) должны быть опубликованы, прежде чем они станут доступными эталонным страницам и макетам страниц. Дополнительные сведения см. в статье Обязательное утверждение элементов в библиотеке или списке сайта.
Блок DIV
После тега <script> находится тег <div> с идентификатором. По умолчанию идентификатор этого тега <div> совпадает с именем HTML-файла. Любое содержимое HTML или код, которые должен предоставлять шаблон отображения, должны быть включены в этот тег <div>. Однако сам тег не включается в разметку, отображаемую на веб-странице во время выполнения.
Примечание.
Если вам нужно назначить стиль CSS или идентификатор блоку HTML, отображаемому на странице во время выполнения, можете добавить новый тег в первый тег <div>. Вы также можете назначить стиль CSS или идентификатор коду HTML вокруг переменной _#= ctx.RenderGroups(ctx) =#_ в шаблоне элемента управления. Переменная _#= ctx.RenderGroups(ctx) =#_ используется для отображения содержимого HTML вокруг результатов запроса, отображаемых шаблоном элемента.
В первом <теге div> вы увидите код внутри блоков комментариев, которые начинаются с <!--#_ и заканчиваются на _#--->. Код JavaScript используется внутри этих блоков, а HTML — за их пределами. С помощью этих блоков также можно управлять содержимым HTML, используя условные операторы. Для этого добавьте блок комментариев с условным оператором и открывающей скобкой, за которой следует код HTML, а затем еще один блок комментариев с закрывающей скобкой. В приведенном ниже примере тег привязки отображается на странице, только если значение объекта linkURL не является пустым.
<!--#_
if(!linkURL.isEmpty)
{
_#-->
<a class="cbs-pictureImgLink" href="_#= linkURL =#_" title="_#= $htmlEncode(line1.defaultValueRenderer(line1)) =#_" id="_#= pictureLinkId =#_">
<!--#_
}
_#-->
Сопоставление входных свойств и получение их значений
Раздел заголовка в шаблоне отображения элемента содержит настраиваемое свойство документа с именем ManagedPropertyMapping. Это свойство принимает управляемые свойства, используемые для поиска, и сопоставляет их со значениями, которые может использовать шаблон отображения. Свойство — это разделенный запятыми список значений в следующем формате: ' отображаемое имя свойства'{ имя свойства}:' управляемое свойство'. Например, 'Picture URL'{Picture URL}:'PublishingImage;PictureURL;PictureThumbnailURL'.
Рассмотрим этот формат подробнее:
Отображаемое имя свойства — это имя свойства, которое отображается в области редактирования веб-части при выборе шаблона отображения.
имясвойства_ это идентификатор, который использует локализованные строковые ресурсов, чтобы найти имя управляемого свойства. Это также значение, которое отображается в разделе Сопоставления свойств меню параметров веб-части. При изменении параметров веб-части это значение можно изменить, чтобы изменить управляемое свойство, связанное с полем, которое отображается в веб-части.
управляемоесвойство_ это строка из одного или нескольких управляемых свойств, разделенных точкой с запятой. Во время выполнения этот список вычисляется слева направо, а первое значение, соответствующее имени управляемого свойства текущего элемента поиска, будет сопоставлено с этим сегментов. Это позволяет создать шаблон отображения, который может работать с несколькими типами элементов и использовать унифицированный способ визуализации при наличии совместимых свойств.
После сопоставления свойства его значение можно получить в скрипте с помощью следующего кода: var pictureURL = $getItemValue(ctx, "Picture URL");
Второй параметр, который передается $getItemValue(), должен соответствовать отображаемому имени свойства в одинарных кавычках, которое используется в элементе ManagedPropertyMapping. В этом примере Picture URL это имя свойства, которое передается $getItemValue().
Этот код возвращает объект сведений о значении ( valueInfoObj). Он содержит необработанное представление входного значения, а также значение, к которому применена кодировка по умолчанию.
Переменные в разделах JavaScript можно использовать, как и обычно, для обработки переменных и создания HTML-строк, которые будут отображаться на странице во время выполнения. Но чтобы ссылаться на переменные, объявленные в скрипте непосредственно в HTML-коде, необходимо использовать следующий формат: #= variableName =#. Например, чтобы использовать переменную pictureURL как значение изображения, воспользуйтесь следующим HTML-кодом: <img src="_#= pictureURL =#_" />
Использование jQuery с шаблонами отображения
JQuery можно использовать с шаблонами отображения. Но имейте в виду два важных фактора:
для включения библиотеки jQuery в шаблон отображения следуйте инструкциям, описанным в разделе Блок скрипта выше;
Если вы используете селекторы идентификаторов в jQuery, используйте следующий код, чтобы создать переменную для идентификатора:
var containerQueryId = '#' + '_#= containerId =#_';Используйте следующий код для ссылки на селектор в jQuery:
$('_#= containerQueryId =#_')
Создание шаблона отображения
Перед созданием шаблона отображения с помощью следующей процедуры необходимо создать сопоставленный сетевой диск, который указывает на коллекцию главных страниц. Дополнительные сведения см. в разделе Практическое руководство. Сопоставление сетевого диска с коллекцией главных страниц SharePoint.
Создание шаблона отображения
С помощью проводника Windows откройте сетевой диск, сопоставленный с коллекцией главных страниц.
Откройте папку Шаблоны отображения, а затем — папку Веб-части контента.
Скопируйте HTML-файл шаблона отображения, подобный тому, который требуется создать. Список шаблонов отображения по умолчанию и их описания см. в разделе Справочник по шаблонам отображения в SharePoint.
На этом этапе SharePoint копирует HTML-файл в JS-файл с таким же именем. Например, если имя скопированного HTML-файла — Item_Picture3Line_copy.html, то также создается соответствующий JS-файл с именем Item_Picture3Lines_copy.js. Если переименовать файл, соответствующий JS-файл также меняется.
Чтобы настроить шаблон отображения, измените HTML-файл, который находится на сервере, с помощью редактора HTML, чтобы открыть и изменить HTML-файл на сопоставленном диске. При каждом сохранении HTML-файла все изменения синхронизируются со связанным .js файлом.
Перейдите на сайт публикации.
В правом верхнем углу страницы выберите пункт Параметры, а затем выберите Дизайнер.
В левой области навигации Дизайнера щелкните Изменить шаблоны отображения. Появится HTML-файл со столбцом Состояние, в котором отображается одно из двух состояний:
Предупреждения и ошибки;
Преобразование выполнено успешно.
Примечание.
В отличие от главных страниц и макетов страниц вы не можете использовать страницу предварительного просмотра для динамического изучения шаблона отображения на сервере. Чтобы просмотреть шаблон отображения, необходимо добавить веб-часть поиска контента на страницу, а затем применить шаблон отображения в области редактирования веб-части поиска контента. Если в шаблоне отображения есть ошибки, веб-часть "Поиск контента" отображает сообщение об ошибке. Исправьте ошибки, чтобы шаблон отображался правильно.
- Чтобы исправить ошибки, отредактируйте HTML-файл, который находится на сервере, в HTML-редакторе, чтобы открыть и изменить HTML-файл на сопоставленном диске. Сохраните шаблон отображения, а затем перезагрузите страницу, содержащую веб-часть поиска контента, которая использует шаблон отображения.