Update November 2021
Time to make some updates to this post! Microsoft has recently made some changes to the terminology and user interface (UI) for the process that this blog post covers. Thanks to the new updates, Site Designs are now called Site Templates. So anywhere you may see the term Site Design or Site Template within SharePoint, this post, or other articles covering the same topic, know that they are the same thing with a new name. The basic functionality remains the same – we can apply our own custom themes, create libraries, set some branding properties, edit the navigation, and more. The only major differences with this update are that the UI has changed for applying templates, templates have to be applied after the fact (not during site creation in the admin center anymore), and Microsoft has also opted to include several pre-built templates for you to use as well.
This post has been updated to change most of the references of “site design” to “site template” (the exception here is the PowerShell cmdlets – they still use the term “site design”), and also to describe how to apply the templates within the updated UI.
I 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 hosted a webinar where I combine the points addressed in both Part 1 and Part 2 Blog posts (Themes, Site Scripts, and Site Templates).
This time we’re going to take a brief look at Site Scripts and Site Templates. 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, either 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 Template.
“Well what is a Site Design then?”
Oh, Microsoft and its terminology… When we say we’re applying a “site template” in a modern site, we’re not talking just about the look and feel of the site. A Site Template in a modern SharePoint site means something different: it is a collection of one or more site scripts. When we choose a site template to apply to a site, it’s looking at the site scripts that are associated with the site template and executing the instructions in the script.
In other words, we add the scripts to the tenant, but the site templates are what make use of the scripts. We choose which site template 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 template 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!) Also notice that even this page still uses the term “site design” which certainly adds to the confusion between the two terms. Just remember, they’re interchangeable; a site design is a site template. 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 template that you can apply to existing sites (again, make sure to use your own title, site script ID, description, and URL):
Add-SPOSiteDesign -Title "My Site Template" -WebTemplate 68 -SiteScripts 33157e94-cab4-4855-bae6-1028d442fe71 -Description "Applies custom theme and logo" -ThumbnailUrl "https://contoso.sharepoint.com/SiteAssets/SiteTemplateThumbnail.png"
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 template 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 template. If you had multiple site scripts, you’d simply separate the script IDs with a comma. You can set a Description to let your users know what the site template does. This shows up when you select your site template to apply to a site. Finally, you can specify a thumbnail image to display on the template selection screen. This could be an image of your company logo, a screenshot of a SharePoint site with your theme applied, or even an image of your cat if you were so inclined. Microsoft recommends a 400px wide by 300px tall image. Before running the cmdlet, you’ll want to upload this image to a place that everyone has access to, like the Site Assets library at the root of the site.
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 template by adding the site template’s ID after the cmdlet, like so:
Get-SPOSiteDesign e4034db4-6041-47a1-9aec-ec59794ca679
Seeing Your Work in Action
Previously, we could select a site template to be applied when we were creating a new site in the Admin center. That is no longer the case, and site templates now need to be applied after the fact. (There is somewhat of a workaround to this involving hub sites, which we’ll cover in a minute.)
To apply your site template to an existing site, open the site, then click the Settings gear > Apply a site template. A dialog window will open and allow you to select from one of Microsoft’s templates, or apply your own. Click on the From your organization tab and click your template. (Note that only communication site templates will show on communication sites, and team site templates will only show on team sites.) You will see what changes the template will make to your site based on what you added to your site script. To apply the template, click the Use template button. A notification bar will appear at the top of the page. Once the template is applied, the notification bar will turn green, and you can refresh the page to see your changes applied!
So what’s the workaround to applying site templates automatically? If you have a site registered as a hub site, you can choose a template to automatically apply to a site that is joined to the hub. To set this up, navigate to the hub site, then click the Settings gear > Hub site settings. In the Site Design applied to associated site dropdown (see? This still says “site design” but they mean “site template”), select your site template and click Save. This may not work for your exact scenario, but it is an option to be aware of.
There you have it! You created a site script, added it to a site template, and applied your custom template your site! This was a pretty simple example of how site scripts and site templates 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. The more you work with site scripts and site templates, the easier they will become to build.