Провизия Modern веб-частей в SharePoint Online
Office 365 и SharePoint Online в частности стремительно движутся в направлении обновления пользовательских интерфейсов и сценариев взаимодействия пользователей с системой. Современные сайта с Modern страницами имеют ряд весомых преимуществ по сравнению с классическими: начиная от просторы редактирования контента пользователями и заказчикая адаптивным дизайном, идущим из коробки. Среди стандартных веб-частей довольно большой набор хороших функциональных, при этом почти все что угодно можно дополнительно разработать с помощью SPFx. С ростом популярности использования Modern страниц появился и спрос на автоматизацию и создание и настроку последних в рамках программной логики, кода и скриптов. В данной статье я пройдусь по основным моментам, связанным с Modern страницами и провизией веб-частей.
Структура Modern страниц
Modern страница представляет собой страницу в библиотеке SitePages в рамказ Modern сайта, позволяющую организовывать содержимое, строящееся на Modern веб-частях. Знаю, очень много слова "Modern", но это важно для того, чтобы подчеркнуть, что тот или иной артефакт не является "классическим", т.к. работа с Modern сильно отличается от классики.
Страница может быть разделена на секции, секции делятся на колонки, может быть секция по всей ширине страницы, в колонки в свою очередь размещаются веб-части, которые и представляют содержимое.
Кратко о Modern веб-частях
На Modern страницах могут размещаться только Modern веб-части. Modern веб-части так же могут размещаться на классических страницах. Modern веб-части можно разделить на идущие из коробки, разработанные Microsoft, и кастомные, разработанные вами или кем-то еще с помощью SharePoint Framework (SPFx). Штатные веб-части нельзя модифицировать, но почти все веб-части имеют настроечный слой, который позволяет сконфигурировать внешний вид и поведение под себя. Иногда настройки могут быть очень развитыми и модифицировать веб-часть значительным образом.
Modern веб-части рендерятся на страницах в виде canvas контролов, часто "canvas контрол" можно воспринимать, как синоним веб-части.
У каждой веб-части свой уникальный идентификатор, псевдоним, версия, манифест и данные. Самый простой способ выястить как в программном коде сконфигурирована веб-часть - это вручную разместить желаемую веб-часть на странице, настроить ее в пользовательском интерфейсе, сохранить и опубликовать страницу и переключиться в режим отладки, добавив ?maintenancemode=true
в адресную строку. В режиме отладки отображается сервисная информация о веб-части, где среди настроек видны и системное представление параметров.
Варианты провизии
Любой уважающий себя разработчик SharePoint разворачивает артефакты программными средствами. Только микроскопические решения и POC допустимо "накликивать вручную", иначе вас как SharePoint разработчика ждет боль и провал. ;) Сам процесс и инструменты провизии могут отличаться, но автоматизация должна быть неотемлиемой части любой команды, считающей себя профессиональной.
PnP провизия
Движек PnP провизии это набор инструментов для .Net и PowerShell, предоставляющий самые из последних и актуальных подходов по развертыванию артефактов в среде SharePoint Online.
PnP провизия предполагает два подхода: модель, определенная в коде и модель на основе декларативной модели в виде XML схемы. Рассмотрим ниже схему провизии страницы с веб-частью:
<?xml version="1.0"?>
<pnp:Provisioning xmlns:pnp="http://schemas.dev.office.com/PnP/2018/05/ProvisioningSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schemas.dev.office.com/PnP/2018/05/ProvisioningSchema https://raw.githubusercontent.com/OfficeDev/PnP-Provisioning-Schema/master/OfficeDevPnP.ProvisioningSchema/ProvisioningSchema-2018-05.xsd">
<pnp:Preferences Generator="OfficeDevPnP.Core, Version=2.26.1805.0, Culture=neutral, PublicKeyToken=5e633289e95c321a" />
<pnp:Templates ID="PORTAL-PAGES-TEMPLATE">
<pnp:ProvisioningTemplate ID="PAGES-TEMPLATE" Version="1.0">
<pnp:ClientSidePages>
<pnp:ClientSidePage PageName="SamplePage01.aspx" Title="Sample Page 01" Layout="Article" PromoteAsNewsArticle="false" Overwrite="true" EnableComments="true" Publish="true">
<pnp:Sections>
<pnp:Section>
<pnp:Controls>
<pnp:CanvasControl WebPartType="Custom" ControlId="34f46dbd-abbb-4ff9-be98-7483df537309" Order="1" Column="1">
<pnp:CanvasControlProperties>
<pnp:CanvasControlProperty Key="PropName" Value="PropValue" />
</pnp:CanvasControlProperties>
</pnp:CanvasControl>
</pnp:Controls>
</pnp:Section>
</pnp:Sections>
</pnp:ClientSidePage>
</pnp:ClientSidePages>
</pnp:ProvisioningTemplate>
</pnp:Templates>
</pnp:Provisioning>
Данный XML пример примененый на сайте создает страницу SamplePage01.aspx
с одной единственной секцией и кастомной веб-частью.
Применить PnP шаблон можно с помощью PowerShell:
$Connection = Connect-PnPOnline -Url $SiteUrl -UseWebLogin -ReturnConnection;
Apply-PnPProvisioningTemplate -Path $SchemaPath -Connection $Connection;
Где:
$SiteUrl
- URL сайта SharePoint,$SchemaPath
- путь до шаблона.
Декларативный подход дает визуальное понимание как организовать структуру страницы. Давайте рассмотрим примеры описания веб-частей.
<!-- Штатная веб-часть - разделитель -->
<pnp:CanvasControl
WebPartType="Spacer"
JsonControlData="{"autoHide":true,"height":56}"
Order="1" Column="1"
/>
<!-- Кастомная веб-часть со свойствами -->
<pnp:CanvasControl
WebPartType="Custom"
ControlId="4f87b698-f910-451f-b4ea-7848a472af0f"
JsonControlData="{"description":"Seattle","timeZoneOffset":10}"
Order="1" Column="2"
/>
Примеры выше показывают описание штатной веб-части и нестандартной, самостоятельно разработанной. Для штатных веб-частей в PnP схеме есть словарь с перечнем поддерживаемых веб-частей WebPartType
, при этом нет необходимости указывать идентификатор ControlId
и настройки по умолчанию. Для нестандартных веб-частей обязательно указание актуального ControlId, которой можно легко определить в режиме отладки или увидеть в манифесте в SPFx проекте.
Самое неприятное - это описание свойств, необходимо использовать JSON строку в виде значения XML свойства JsonControlData
, при этом это не чистый JSON, а его форма приведенная в строку с заменой символов, например, символ "
небходимо задать в виде соответствующего HTML кода "
. Однако в ряде простых случаев можно задавать свойтва в XML виде:
<pnp:CanvasControlProperties>
<pnp:CanvasControlProperty Key="PropName" Value="PropValue" />
</pnp:CanvasControlProperties>
Хорошим примером по провизии Modern страниц и веб-частей является SharePoint Starter Kit, где собраны вместе и проекты с исходниками кастомных веб-частей и провизией портала.
PnPjs провизия
PnPjs - набор клиентских библиотек для TypeScript/JavaScript для Microsoft 365, оборачиват работу с REST API у удобный и практичный вид. В PnPjs так же есть возможность для провизии современных страниц и веб-частей с помощью REST API из браузера или процесса Node.js.
import { sp, ClientSidePage, ClientSideWebpart, ClientSideText } from '@pnp/sp';
(async () => {
const page = await sp.web.addClientSidePage('SamplePage01.aspx', 'Sample Page 01');
// Получение существующей страницы
// const pageFile = sp.web.getFileByServerRelativeUrl(`${webUri}/SitePages/SamplePage01.aspx`);
// const page = await ClientSidePage.fromFile(pageFile);
page.sections = [];
const section = page.addSection();
// Размещение веб-частей
// Стандартная веб-часть с текстом
section.addControl(new ClientSideText('HTML содержимое и текст'));
// Кстомная веб-часть
section.addControl(
new ClientSideWebpart('Моя веб-часть', null, {
parameter01: 'value 01'
}, '34f46dbd-abbb-4ff9-be98-7483df537309')
);
// Галерея фотографий (штатная веб-часть)
section.addControl(
new ClientSideWebpart('ImageGallery', null, {
layout: 2,
gridSettings: {
imageSize: 2,
imageCropping: 1,
imageAspectRatio: 1,
lightbox: false
},
images: [
{ url: '/sites/hub/SiteAssets/ImageGallery/88876.jpg' },
{ url: '/sites/hub/SiteAssets/ImageGallery/77559.jpg' },
{ url: '/sites/hub/SiteAssets/ImageGallery/77371.jpg' },
{ url: '/sites/hub/SiteAssets/ImageGallery/36732.jpg' },
{ url: '/sites/hub/SiteAssets/ImageGallery/97899.jpg' }
]
}, 'af8be689-990e-492a-81f7-ba3e4cd3ed9c')
);
await page.save();
})()
.then(_ => console.log('Done'))
.catch(console.log);
Подобные скрипты могут быть в состаре клиентского решения, например, админка, релизованная на SPFx. Так же, может быть удобно запускать скрипты прямо в браузере с помощью расширения для Chrome SP Editor. Либо же, это может быть серверный процесс на Node.js, например, Azure Function.
Заключение
Оба подхода PnP провизия (.Net, PowerShell) и PnPjs скрипты предоставляют возможности по автоматизации задач создания и конфирурирования страниц. Такая автоматизация может быть либо в составе функциональности решения или модели, обновляемой средствами CI/CD. Мое мнение, что использование автоматизированных подходов является обязательным и стандартом де-факто для современных SharePoint разработчиков и администраторов.
Опубликовано: 14.01.2019
Автор: Андрей Кольтяков