Embracing the Modern SharePoint Part 2: Site Scripts & Site Designs

Posted by: Ryan Keller on April 17,2020

Copy of Copy of Add a headingI figured I should finally get around to writing the follow-up to my last post in this series, which touched on creating modern themes.  I also will be hosting a webinar where I combine the points addresses in both Part 1 and Part 2 Blog posts (Themes, Site Scripts, and Site Design).  

This time we’re going to take a brief look at Site Scripts and Site Designs. We’ll look at what they are, what they do, how they work together, and what they mean to you as a SharePoint designer.

A fair warning: This post is going to get a little technical. We’re going to be looking at developer-y things like JSON and we’ll once again have to use (gasp!) PowerShell to make this work. But don’t worry, that’s the whole point of this – to get you used to the “modern” way of doing things in SharePoint!

Arguably one of the most popular ways of building out SharePoint sites was to set up a site or list exactly the way you wanted it and save it as a template. That option was only available on classic Team sites but still proved a useful way to quickly get a set of sites up and running with a standard set of web parts, lists, and libraries. Since that option is no longer available in modern SharePoint sites, let’s see what the options are.

“OK, so what is a site script?”

A very basic description of a site script is that it’s a repeatable to-do list for SharePoint to follow. Once  SharePoint accomplishes a task on its list, it checks it off and moves to the next item.

What do I mean by that? Well, a site script can help us create a sort of template that can be applied to a site, eitherQuestion site script during or after that site is created.

A site script doesn’t technically do anything on its own. We create the site script in JSON and install it to our tenant, but it’ll just sit there until we actually add it to a Site Design.

“Well what is a Site Design then?”

Oh, Microsoft and its terminology… When we say we’re applying a “site design” in a modern site, we’re not talking just about the look and feel of the site. A Site Design in a modern SharePoint site means something different: it is a collection of one or more site scripts. When we choose a site design to apply to a site, it’s looking at the site scripts that are associated with the site design and executing the instructions in the script.

In other words, we add the scripts to the tenant, but the site designs are what make use of the scripts. We choose which site designs to apply in the UI, and SharePoint takes care of the rest.

“So what can I do with them?”

Site scripts are actually quite useful. Even though there is no “true” template option for recreating a site over and over, a site script/site design is the next best thing. With a site script, we can do things like apply our custom theme, set a site logo automatically (but only on Communication sites), create site columns, create lists & libraries, create and add columns to those lists, create views, set some branding options in the site such as the header size and background color, change the navigation, and more.

Creating a Site Script

Let’s go ahead and make a simple site script.

First, you’ll want to open Microsoft’s Site Design JSON Schema page. (A quick Google/Bing search for “JSON site design” will also work too!) This page has a list of all the available actions you can add to the site script.

Fire up your favorite text editor (I am a big fan of Visual Studio Code) and grab the first block of JSON code from the page, and paste it into your file:

{

  "$schema": "schema.json",

  "actions": [

    ...

    <one or more verb actions>

    ...

  ],

  "bindata": { },

  "version": 1

}

 

In between the opening and closing brackets of the “actions” section is where we’ll define the instructions for the site script. You can remove the …<one or more verb actions>… ellipsis and text in between the brackets. Next, you’ll want to scroll through the list of actions on the right side of that page. Find “Apply a theme” and copy that code block, then paste it into the actions section of the file. Your code should look like this now:

{

  "$schema": "schema.json",

  "actions": [

{

  "verb": "applyTheme",

  "themeName": "Blue Yonder"

  ],

  "bindata": { },

  "version": 1

}

NOTE: You’ll (obviously) want to replace “Blue Yonder” with the name of your own custom theme.

Now, let’s apply a logo.

Put a comma after the last curly bracket of the applyTheme action.

Find the “Set a site logo” section of the JSON schema page and copy that code block, then paste it in after the applyTheme action. (Note the comma separating the applyTheme and setSiteLogo action blocks.)

Your site script will look like this:

{

  "$schema": "schema.json",

  "actions": [

    {

    "verb": "applyTheme",

    "themeName": "Blue Yonder"

    },

    {

    "verb": "setSiteLogo",

    "url": "/Customer Event Collateral/logo.jpg"

    }

  ],

  "bindata": { },

  "version": 1

}

 

NOTE: Again, you’ll want to make sure to set the url property for your site logo to a URL in your site that everyone has read access to. A good place to reference it is from the SiteAssets library at the root site. For example, "/SiteAssets/CompanyLogo.png"

That’s it! You’ve created a site script file. Go ahead and save the file on your PC. Click the file to select it, and in the Windows Explorer ribbon click the “Copy Path” button. This will be useful later.

Now, let’s install the site script using the SharePoint Online Management Shell.

Installing a Site Script

Fire up SharePoint Online Management Shell and connect to your tenant using the following cmdlet (replace “contoso” with your tenant name):

Connect-SPOService -url "https://contoso-admin.sharepoint.com"

Set a variable called scriptPath to the path of your script that you copied earlier. In a Powershell window, you can page using Ctrl-V or right-clicking the mouse button in the window.

$scriptPath = "C:\Users\Ryan\Desktop\mySiteScript.json"

Now, we’ll set a new variable to get the content from that script file:

$scriptContent = Get-Content $scriptPath -Raw

And finally, we’ll install the site script to the tenant by piping the contents of the scriptContent variable into the Add-SPOSiteScript cmdlet:

$scriptContent | Add-SPOSiteScript -Title "My Site Script" -Description "Adds logo and sets theme"

You’ll see that your script has been added to your tenant! Yay! Make a note of the script ID. We’ll need that later. You can also get information about the scripts that are installed by running the following:

Get-SPOSiteScript

This will you all the scripts in your tenant. If you want more information on a specific script, you can run the Get-SPOSiteScript cmdlet followed by the ID of the script:

Get-SPOSiteScript 33157e94-cab4-4855-bae6-1028d442fe71

Creating a Site Design to run the Site Script

Remember earlier when we learned that site scripts don’t do anything unless they’re used by a site design? Well now we’re going to build a site design that will actually use our site script.

The SharePoint Online Management Shell is all we’ll need for this step.

Simply run the following cmdlet to create a site design that you can select when you’re creating new sites, or to apply to existing sites:

Add-SPOSiteDesign -Title "My Site Design" -WebTemplate 68 -SiteScripts 33157e94-cab4-4855-bae6-1028d442fe71 -Description "Applies custom theme and logo"

So what’s going on here? Let’s walk through the cmdlet. First, we give it a Title. Then, the WebTemplate switch is what specifies whether this site design will be applied to Communication sites or Team sites. Communication sites will use a WebTemplate  number of 68, while Team Sites will use 64. The SiteScripts switch is where you will add one or more site scripts to your site design. If you had multiple site scripts, you’d simply separate the script IDs with a comma. You can set a description for what the site design does. This shows up when you select your site design during site creation or after a site has been created. (This is a very basic example of installing a site design – there are a couple more things that can be specified in the cmdlet but we’ll tackle those in another post)

You can see all site designs that you’ve added to your tenant by running:

Get-SPOSiteDesign

You can also get more information on a specific site design by adding the site design’s ID after the cmdlet, like so:

Get-SPOSiteDesign e4034db4-6041-47a1-9aec-ec59794ca679

Seeing Your Work in Action

There are two ways to see your new site design in action – you can create a new site from the admin center and select your site design from the dropdown during site creation, or you can open an existing site and apply the site design.

In the SharePoint Admin Center, click Sites > Active Sites. Click the +Create Site button, then select Communication Site (if you created a site design for a Team site, or WebTemplate 64, select Team site instead). In the Choose a design dropdown, select your site design from the list, then continue creating the site as normal.

If you’d like to apply your site design to an existing site, open the site, then click the Settings gear > Site designs. In the slide out menu, select your site design from the dropdown, then click the Apply to site button. This interface shows you exactly what SharePoint will do as it works through the actions you specified in your site script.

Again, this is a very simple example of how site scripts and site designs can work. Although not a true “template” that you may have been used to in classic SharePoint sites, they are a good start for getting a set of sites to have some uniformity. You can take this even further with more actions as shown in the JSON Site Design Schema page, and we’ll touch on this in a future post as well.

 

Topics: Design, Modern SharePoint

Subscribe Today!

Recent Posts

Categories