Провизия 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="{&quot;autoHide&quot;:true,&quot;height&quot;:56}"
  Order="1" Column="1"
/>

<!-- Кастомная веб-часть со свойствами -->
<pnp:CanvasControl
  WebPartType="Custom"
  ControlId="4f87b698-f910-451f-b4ea-7848a472af0f"
  JsonControlData="{&quot;description&quot;:&quot;Seattle&quot;,&quot;timeZoneOffset&quot;:10}"
  Order="1" Column="2"
/>

Примеры выше показывают описание штатной веб-части и нестандартной, самостоятельно разработанной. Для штатных веб-частей в PnP схеме есть словарь с перечнем поддерживаемых веб-частей WebPartType, при этом нет необходимости указывать идентификатор ControlId и настройки по умолчанию. Для нестандартных веб-частей обязательно указание актуального ControlId, которой можно легко определить в режиме отладки или увидеть в манифесте в SPFx проекте.

Самое неприятное - это описание свойств, необходимо использовать JSON строку в виде значения XML свойства JsonControlData, при этом это не чистый JSON, а его форма приведенная в строку с заменой символов, например, символ " небходимо задать в виде соответствующего HTML кода &quot;. Однако в ряде простых случаев можно задавать свойтва в 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
Автор: Андрей Кольтяков