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

29 сентября, 2016

Пошаговая инструкция создания клиентской веб-части с использованием SharePoint Framework и AngularJS. 10 простых шагов для создания веб-части SPFx, отображающей данные из списка.

SharePoint Framework

Многие компании используют SharePoint как платформу для создания своих решений. Основными артефактами этих решений являются страницы веб-частей и отдельные веб-части, формирование конечного HTML-кода в которых происходит на стороне сервера. Но современные технологии не стоят на месте. Развитие возможностей клиентских браузеров и JavaScript сделали возможным создание адаптивных веб-приложений, работающих не только на настольных компьютерах, но и на мобильных устройствах.

Современные приложения должны удовлетворять новым требованиям и новая модель для создания решений SharePoint Framework позволяет разработчикам использовать современные инструменты в своей работе и не ограничиваться более возможностями .Net.

Modern всё

SharePoint Framework - это не адаптированный sandbox solution, и не add-in. SharePoint Framework - новый подход к созданию решений, но новый он только для SharePoint разработчиков:

SharePoint Framework позволяет использовать существующие инструменты веб-разработки для создания решений.

Новое помимо адаптации SharePoint-разработки под современные инструменты - новый интерфейс SharePoint, который называется modern.

В SharePoint Online его можно увидеть в библиотеке документов.

Классический вид:

И modern:

HTML-код modern-страницы без блоков <script>:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html dir="ltr" lang="en-US">
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale= 1.0, minimum-scale=1.0, user-scalable=no" />
<link rel="shortcut icon" href="_layouts/15/images/favicon.ico?rev=44" type="image/vnd.microsoft.icon" id="favicon" />
</html>
<body>
</body>

Пустой body (почему-то после html), все содержимое формируется на стороне клиента. В качестве клиентского framework'а можно использовать Knockout, React, AngularJS или какой-либо другой.

Workbench

Так как в SharePoint Framework весь код исполняется на стороне клиента, то возникает вопрос: "Нужен ли установленный SharePoint для разработки решений?".

SharePoint Framework позволяет разрабатывать и отлаживать решения без наличия установленного SharePoint. Для этого используется Workbench.

Этого хватит для элементарной отладки, не более того.

Проект

Переходим к проекту. В качестве примера создадим простую веб-часть, которая будет отображать данные из списка. В работе веб-часть будет использовать AngularJS в качестве JS Framework.

Шаг 0. Node.js

Для создания решений с использованием SharePoint Framework понадобится node.js. Скачиваем и устанавливаем node.js если ещё этого не сделали.

Шаг 1. Создаем проект

Создаем новую папку для будущего проекта:


md StuffWebPart

И переходим в созданную директорию:


cd StuffWebPart

Запускаем Yeoman для создания проекта:


yo @microsoft/sharepoint

При запуске yeoman вводим необходимую информацию:

Дожидаемся окончания генерации проекта:

Проект уже можно запустить, используя Workbench:


gulp serve

Шаг 2. Устанавливаем AngularJS

В качестве JS Framework будет использован AngularJS. Чтобы его установить запускаем:


npm i angular -S

Помимо этого понадобится TypeScript definition. Для его установки исполняем:


tsd install angular -s

Шаг 3. Добавляем Office UI Fabric

Для UI попробуем использовать Office UI Fabric, точнее его Angular-версию. Добавляем его в проект:


npm i angular ng-office-ui-fabric -S

Все установленные пакеты можно увидеть в файле package.json решения:

Шаг 4. Данные

В качестве источника данных будет выступать список, содержащий информацию о сотрудниках. Поскольку теперь нельзя сохранить список в качестве шаблона приведу снимок экрана параметров списка:

Данные исключительно демонстрационные. Воссоздать такие или похожие руками совершенно недолго. Доступ к данным будет реализован с помощью REST API. Элементы списка получаем по URL'у вида:


https://{TenantName}.sharepoint.com/{SiteUrl}/_api/web/lists(guid'{ListGuid}')/items

Шаг 5. Веб-часть

В коде веб-части перед декларацией класса самой веб-части вставляем следующие строки:


// AngularJS
import * as angular from 'angular';
// Office UI Fabric
import 'ng-office-ui-fabric';
// ModuleLoader
import ModuleLoader from '@microsoft/sp-module-loader';
// EnvironmentType
import { EnvironmentType } from '@microsoft/sp-client-base';

С Angular и Office UI Fabric всё понятно. ModuleLoader используется для регистрации CSS и JS файлов на странице. EnvironmentType помогает определить среду в которой исполняется веб-часть. Всего типов сред четыре:

Test (0) - код исполняется в интеграционных или юнит-тестах;
Local (1) - код исполняется в workbench. SharePoint REST API недоступен в workbench;
SharePoint (2) - код исполняется в client-rendered SharePoint page;
ClassicSharePoint (3) - код исполняется на классической странице SharePoint.

ModuleLoader используется для регистрации стилей Office UI Fabric в конструкторе веб-части:


public constructor(context: IWebPartContext) {
  super(context);
  ModuleLoader.loadCss('https://appsforoffice.microsoft.com/fabric/2.6.1/fabric.min.css');
  ModuleLoader.loadCss('https://appsforoffice.microsoft.com/fabric/2.6.1/fabric.components.min.css');
}

Шаг 6. Разметка веб-части

HTML-код веб-части будет в отдельном файле tempaltes/app.html. Содержимое, всего 20 строчек.

/templates/app.html:

Простой вывод информации с помощью компонента Persona и поле для фильтрации.

Блок style - это костыль для Office UI Fabric.

Шаг 7. Angular App

В приложении источником данных будет список SharePoint. Для отправки HTTP-запроса в SharePoint Framework необходимо использовать нативный клиент this.context.httpClient. В этом случае запрос будет отправлен от имени текущего пользователя. SharePoint заполнит все необходимые заголовки в запросе:

В остальном метод render веб-части прост:


public render(): void {
  // Если метод render уже вызывался выходим из метода
  if(this.renderedOnce === true)
  {
    return;
  }
  angular
    .module('StuffApp', [
      'officeuifabric.core',
      'officeuifabric.components'])
    .controller('StuffController', ($scope: ng.IScope):void =>
    {
      // Паттерн фильтра
      ($scope as any).searchPattern = '';
      // Коллекция сотрудников
      ($scope as any).stuff = [];
      // ID списка
      var listId = '2B6B3A8F-6837-4141-A624-5373C2AC0816';
      // URL сайта
      var siteUrl = 'https://vz365.sharepoint.com/rusug'

      // Данные загружаем только если среда исполнения - SharePoint
      switch(this.context.environment.type)
      {
        case 2: // SharePoint
        case 3: // Classic server-rendered SharePoint
            // Запросы только через this.context.httpClient
            this.context.httpClient
              .get(siteUrl + "/_api/web/lists(guid'" + listId + "')/items")
              .then((response: Response) => {
                response.json()
                .then(data=>{
                  // Заполняем коллекцию сотрудников
                  ($scope as any).stuff = data.value;
                  if(!$scope.$$phase)
                  {
                    $scope.$apply();
                  }
                });
              });
      }
    });
  // HTML разметка
  this.domElement.innerHTML = require('./templates/app.html');
  // Bootstrap
  angular.bootstrap(this.domElement, ['StuffApp']);
}

В начале метода проверяем свойство this.renderedOnce и если оно равно true, то выходим из метода.

Метод render вызывается всякий раз как только меняется какое-либо свойство веб-части.

Так как наше AngularJS приложение необходимо загрузить только единожды, то мы выходим из метода render если этот метод уже вызывался.

Шаг 8. Создание пакета решения

Чтобы доставить решение до Office 365 его необходимо упаковать. В SharePoint Framework решения пакуются в .spapp-пакеты. Сперва необходимо подготовить решение с помощью Gulp: