Modern web parts provisioning in SharePoint Online

by Andrew Koltyakov

Office 365 and SharePoint Online in particular rush in the direction of Modern UI and UX. The modern sites with modern pages have a number of advantages starting with simplicity for end users who manages the content and finishing with OOTB responsiveness and mobile friendliness. There is a bunch of great web parts to use out of the shelf as well as a rich tooling and the framework for rapid development of custom ones. After a while, a question of modern sites managing and automated provisioning appears. In this post, I'm going to reveal and investigate some options for pages and web parts provisioning.

Modern page structure quick overview

The modern page is a page in SitePages on a modern SharePoint site which provides a capability of organizing content within the page. A page can be configured with sections (rows), a section can be dynamically divided into columns or declared as a full-width section, then web parts can be added into a column. All of these gives a flexible way of managing the visual representation of information on the page.

Modern web part quick overview

Only modern web parts can be located on a modern page. Modern web parts can be separated to OOTB provided by Microsoft and custom 3rd party developed using SharePoint Framework (SPFx). OOTB web parts can't be changed, but all the web parts could be configured with properties defined during development time. Sometimes changing properties, one can receive absolutely different experience within the same web part.

Modern web parts are rendered on the pages as canvas controls, so "canvas control" is the second name for modern web parts.

Each web part has its own unique id, alias, version, manifest and data. The simplest way to research web parts' metadata is to add web parts you're interested in on the page, provide settings in the UI, publish the page and then add ?maintenancemode=true parameter to the URL. This switches page into maintenance mode showing web parts' service information.

Provisioning options

Any developer in the wild should be equipped with provisioning toolchains. Only microscopic solutions should assume manual actions as a rule. I say this words as a mantra to the team members and customers. Depending on preferences and scenarios different approaches can be used for provisioning, but the process should be automated, point or even exclamation mark.

PnP provisioning

PnP provisioning is a set of tools for .Net and PowerShell, which provides cutting edge feature capabilities when it comes to SharePoint Online.

PnP provisioning assumes two approaches: functional code-base provisioning and declarative schema-based processing. So, for example, one can provisiong an artifact using a specific PowerShell commandlet or .Net method or create an XML template based of a schema and apply this template to site.

This XML sample shows configuration of creation SamplePage01.aspx page with one sections and a custom web part placed to the first and the only column in this case.

Having such a template it can be applyed to a site with a bit of PowerShell:

$Connection = Connect-PnPOnline -Url $SiteUrl -UseWebLogin -ReturnConnection;
Apply-PnPProvisioningTemplate -Path $SchemaPath -Connection $Connection;

Where:

  • $SiteUrl is a URL of SharePoint modern site,
  • $SchemaPath is path to the XML template.

Declarative style gives an idea how to organize pages, sections and web parts. Let's investigate canvas control in particular.

The example above shows OOTB web part provisioning definition. For OOTB controls PnP schema has WebPartTypes dictionary, no need in providing ControlIds. For a custom types, ControlId is required. It can be easily found in maintanence mode or web part manifest.

The most annoying part is providing properties, i.e., JsonControlData stored escaped version of properties JSON. Yet you can get used dealing with this rather soon, especially, for some simple cases the props can be provided in XML way:

A good example of web parts provisioning and modern SharePoint solution in general with all moving parts can be found in SharePoint Starter Kit repository.

PnPjs provisioning

PnPjs, client side libraries for Microsoft 365, wrapper for SharePoint REST API and much more, also provides its mechanisms for dealing with client side pages via REST API.

With REST API, most of the actions with client site pages and modern web parts are in out disposal.

import { sp, ClientSidePage, ClientSideWebpart, ClientSideText } from '@pnp/sp';

(async () => {

  const page = await sp.web.addClientSidePage('SamplePage01.aspx', 'Sample Page 01');

  // Getting existing page
  // const pageFile = sp.web.getFileByServerRelativeUrl(`${webUri}/SitePages/SamplePage01.aspx`);
  // const page = await ClientSidePage.fromFile(pageFile);

  page.sections = [];
  const section = page.addSection();

  // Placing all the webparts in one section

  // Standard text control
  section.addControl(new ClientSideText('HTML content goes here'));

  // Custom 3rd party webpart
  section.addControl(
    new ClientSideWebpart('Custom web part', null, {
      parameter01: 'value 01'
    }, '34f46dbd-abbb-4ff9-be98-7483df537309')
  );

  // Image gallery webpart
  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);

Such scripts can be a part of admin applications within SPFx solution for example, can be executed right in the browser using SP Editor extension, or can run in Node.js process.

Wrapping up

Both PnP Provisioning (.Net, PowerShell) and PnPjs scripts are friendly for automated processes and CI/CD. In my opinion these tools are mandatory and de-facto for modern SharePoint developers and administrators.

The second wrapping idea is that it has been never so easy to provision pages and web parts as it is now with Modern cutting edge SharePoint.