Working With: Client side Pages

The ability to manage client-side pages is a capability introduced in version 3.0.5 of sp-pnp-js. Through the methods described you can add and edit "modern" pages in SharePoint sites.

Add Client-side page

Using the addClientSidePage you can add a new client side page to a site, specifying the filename.

import pnp from "sp-pnp-js";

const page = await pnp.sp.web.addClientSidePage(`MyFirstPage.aspx`);

Load Client-side page

You can also load an existing page based on the file representing that page. Note that the static fromFile returns a promise which resolves so the loaded page. Here we are showing use of the getFileByServerRelativeUrl method to get the File instance, but any of the ways of getting a File instance will work. Also note we are passing the File instance, not the file content.

import pnp, { 
    ClientSidePage,
} from "sp-pnp-js";

const page = await ClientSidePage.fromFile(pnp.sp.web.getFileByServerRelativeUrl("/sites/dev/SitePages/ExistingFile.aspx"));

The remaining examples below reference a variable "page" which is assumed to be a ClientSidePage instance loaded through one of the above means.

Add Controls

A client-side page is made up of sections, which have columns, which contain controls. A new page will have none of these and an existing page may have any combination of these. There are a few rules to understand how sections and columns layout on a page for display. A section is a horizontal piece of a page that extends 100% of the page width. A page with multiple sections will stack these sections based on the section's order property - a 1 based index.

Within a section you can have one or more columns. Each column is ordered left to right based on the column's order property. The width of each column is controlled by the factor property whose value is one of 0, 2, 4, 6, 8, 10, or 12. The columns in a section should have factors that add up to 12. Meaning if you wanted to have two equal columns you can set a factor of 6 for each. A page can have empty columns.

import pnp, { 
    ClientSideText, 
} from "sp-pnp-js";

// this code adds a section, and then adds a control to that section. The control is added to the section's defaultColumn, and if there are no columns a single
// column of factor 12 is created as a default. Here we add the ClientSideText part
page.addSection().addControl(new ClientSideText("Here is some text!"));

// here we add a section, add two columns, and add a text control to the second section so it will appear on the right of the page
// add and get a reference to a new section
const section = page.addSection();

// add a column of factor 6
section.addColumn(6);

// add and get a reference to a new column of factor 6
const column = section.addColumn(6);

// add a text control to the second new column
column.addControl(new ClientSideText("Be sure to check out the developer guide at https://github.com/SharePoint/PnP-JS-Core/wiki/Developer-Guide"));

// we need to save our content changes
await page.save();

Add Client-side Web Parts

Beyond the text control above you can also add any of the available client-side web parts in a given site. To find out what web parts are available you first call the web's getClientSideWebParts method. Once you have a list of parts you need to find the defintion you want to use, here we get the Embed web part whose's id is "490d7c76-1824-45b2-9de3-676421c997fa" (at least in one farm, your mmv).

import pnp, {
    ClientSideWebpart,
    ClientSideWebpartPropertyTypes,
} from "sp-pnp-js";

// this will be a ClientSidePageComponent array
// this can be cached on the client in production scenarios
const partDefs = await pnp.sp.web.getClientSideWebParts();

// find the definition we want, here by id
const partDef = partDefs.filter(c => c.Id === "490d7c76-1824-45b2-9de3-676421c997fa");

// optionally ensure you found the def
if (partDef.length < 1) {
    // we didn't find it so we throw an error
    throw new Error("Could not find the web part");
}

// create a ClientWebPart instance from the definition
const part = ClientSideWebpart.fromComponentDef(partDef[0]);

// set the properties on the web part. Here we have imported the ClientSideWebpartPropertyTypes module and can use that to type
// the available settings object. You can use your own types or help us out and add some typings to the module :).
// here for the embed web part we only have to supply an embedCode - in this case a youtube video.
part.setProperties<ClientSideWebpartPropertyTypes.Embed>({
    embedCode: "https://www.youtube.com/watch?v=IWQFZ7Lx-rg",
});

// we add that part to a new section
page.addSection().addControl(part);

// save our content changes back to the server
await page.save();

Control Comments

You can choose to enable or disable comments on a page using these methods

// enable comments
await page.enableComments();

// disable comments
await page.disableComments();