Skip to content

Commit 8a3f792

Browse files
andrewconnellandrewconnell
authored
Merge pull request SharePoint#7350 from vijayysisodia/patch-2
Fixed typo and indentation
2 parents 7c9901e + 20905e5 commit 8a3f792

File tree

1 file changed

+166
-166
lines changed

1 file changed

+166
-166
lines changed

‎docs/declarative-customization/get-started-create-site-design.md

Lines changed: 166 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,166 @@
1-
---
2-
title: Get started creating SharePoint site templates and site scripts
3-
description: Create site templates to provide reusable lists, themes, layouts, pages, or custom actions so that your users can quickly build new SharePoint sites with the features they need.
4-
ms.date: 09/24/2021
5-
ms.localizationpriority: high
6-
---
7-
8-
# Get started creating site templates and site scripts
9-
10-
You can create site templates to provide reusable lists, themes, layouts, or custom actions so that your users can quickly build new SharePoint sites with the features they need.
11-
12-
This article describes how to build a simple site template that adds a SharePoint list for tracking customer orders. You'll use the site template to create a new SharePoint site with the custom list. You'll learn how to use SharePoint PowerShell cmdlets to create site scripts and site templates. You can also use REST APIs to perform the same actions. The corresponding REST calls are shown for reference in each step.
13-
14-
## Create the site script in JSON
15-
16-
A site script is a collection of actions that SharePoint runs when creating a new site. Actions describe changes to apply to the new site, such as creating a new list or applying a theme. The actions are specified in a JSON script, which is a list of all actions to apply. When a script runs, SharePoint completes each action in the order listed.
17-
18-
Each action is specified by the "verb" value in the JSON script. Also, actions can have subactions that are also "verb" values. In the following JSON, the script specifies to create a new list named **Customer Tracking**, and then subactions set the description and add several fields to define the list.
19-
20-
1. Download and install the [SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588). If you already have a previous version of the shell installed, uninstall it first and then install the latest version.
21-
1. Follow the instructions at [Connect to SharePoint Online PowerShell](https://technet.microsoft.com/library/fp161372.aspx) to connect to your SharePoint tenant.
22-
1. Create - and assign the JSON that describes the new script - to a variable as shown in the following PowerShell code. You can view and reference the latest JSON schema file here: https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json
23-
24-
```powershell
25-
$site_script = '
26-
{
27-
"$schema": "schema.json",
28-
"actions": [
29-
{
30-
"verb": "createSPList",
31-
"listName": "Customer Tracking",
32-
"templateType": 100,
33-
"subactions": [
34-
{
35-
"verb": "setDescription",
36-
"description": "List of Customers and Orders"
37-
},
38-
{
39-
"verb": "addSPField",
40-
"fieldType": "Text",
41-
"displayName": "Customer Name",
42-
"isRequired": false,
43-
"addToDefaultView": true
44-
},
45-
{
46-
"verb": "addSPField",
47-
"fieldType": "Number",
48-
"displayName": "Requisition Total",
49-
"addToDefaultView": true,
50-
"isRequired": true
51-
},
52-
{
53-
"verb": "addSPField",
54-
"fieldType": "User",
55-
"displayName": "Contact",
56-
"addToDefaultView": true,
57-
"isRequired": true
58-
},
59-
{
60-
"verb": "addSPField",
61-
"fieldType": "Note",
62-
"displayName": "Meeting Notes",
63-
"isRequired": false
64-
}
65-
]
66-
}
67-
],
68-
"bindata": { },
69-
"version": 1
70-
}
71-
'
72-
```
73-
74-
The previous script creates a new SharePoint list named **Customer Tracking**. It sets the description and adds four fields to the list. Note that each of these are considered an action. Site scripts are limited to 30 cumulative actions (across one or more scripts that may be called in a site template) if applied programmatically using the `Invoke-SPOSiteDesign` command. If they are applied through the UI or using the `Add-SPOSiteDesignTask` command then the limit is 300 cumulative actions (or 100K characters).
75-
76-
## Add the site script
77-
78-
Each site script must be registered in SharePoint so that it is available to use. Add a new site script by using the **Add-SPOSiteScript** cmdlet. The following example shows how to add the JSON script described previously.
79-
80-
```powershell
81-
C:\> Add-SPOSiteScript
82-
-Title "Create customer tracking list"
83-
-Content $site_script
84-
-Description "Creates list for tracking customer contact information"
85-
```
86-
87-
After running the cmdlet, you get a result that lists the site script **ID** of the added script. Keep track of this ID somewhere because you will need it later when you create the site template.
88-
89-
The REST API to add a new site script is **CreateSiteScript**.
90-
91-
## Create the site template
92-
93-
Next, you need to create the site template. The site template appears in a drop-down list when someone creates a new site from one of the templates. It can run one or more site scripts that have already been added.
94-
95-
- Run the following cmdlet to add a new site template. Replace `<ID>` with the site script ID from when you added the site script.
96-
97-
```powershell
98-
C:\> Add-SPOSiteDesign
99-
-Title "Contoso customer tracking"
100-
-WebTemplate "64"
101-
-SiteScripts "<ID>"
102-
-Description "Tracks key customer data in a list"
103-
```
104-
105-
The previous cmdlet creates a new site template named Contoso customer tracking.
106-
107-
| Parameter | Value | Site template type |
108-
| :------------------- | :------------------- |:----------------|
109-
| WebTemplate | 64 | Team site template |
110-
| WebTemplate 1 | 1 | Team site (with group creation disabled) |
111-
| WebTemplate | 68 | Communication site template |
112-
| WebTemplate | 69 | Channel site template |
113-
114-
115-
The JSON response displays the **ID** of the new site template. You can use it in subsequent cmdlets to update or modify the site template.
116-
117-
The REST API to add a new site template is **CreateSiteDesign**.
118-
119-
## Use the new site template
120-
121-
Now that you've added a site script and site template, you can use it to create new sites through the self-service site creation experience or apply the site template to an existing site using the **Invoke-SPOSiteDesign** command in PowerShell. If you are using hub sites you can even associate a site template to a hub so it gets applied to all joining sites.
122-
123-
### New site creation
124-
125-
1. Go to the home page of the SharePoint site that you are using for development.
126-
1. Choose **Create site**.
127-
1. Choose the type of site you need to use. SharePoint will create a team site using the Microsoft **Team collaboration template** or a communication site using the Microsoft **Topic** template unless another custom site template is set as default.
128-
2. Choose **Next**.
129-
4. In **Site name**, enter a name for the new site **Customer order tracking**.
130-
7. Choose **Finish**.
131-
5. Next, go to **Settings** and select **Apply a site template**.
132-
5. Select the site template you just created.
133-
8. Once applied, your new template will display under the tab in the template viewer titled **From your organization.**
134-
9. When the new template has been applied, you will see the custom list on the page.
135-
136-
### Apply to an existing site
137-
138-
You can also apply a published site template to existing sites. On the home page of the site, site owners can navigate to **Settings** and then **Apply a site template** to browse and apply templates provided by your organization and Microsoft.
139-
140-
You can apply templates to existing site collections in bulk by using the [Invoke-SPOSiteDesign](/powershell/module/sharepoint-online/Invoke-SPOSiteDesign) cmdlet.
141-
142-
**Published site templates can be applied to:**
143-
144-
1. Group-connected team sites
145-
1. Team sites that not connected to a Microsoft 365 group
146-
1. Communication sites
147-
2. Channel sites
148-
3. Classic team sites
149-
4. Classic publishing sites
150-
151-
The REST API to apply a site template to an existing site collection is **ApplySiteDesign**.
152-
153-
### Associate with a hub site
154-
155-
Apply a published site template to a new or existing hub site. Then, all associated sites will inherit the hub site template and theme. Navigate to the home page of the hub and go to **Settings** and then **Apply a site template**. Learn more about how to [enable site associations for your hub site](https://support.microsoft.com/office/set-up-your-sharepoint-hub-site-e2daed64-658c-4462-aeaf-7d1a92eba098).
156-
157-
You can also use the `Set-SPOHubSite` cmdlet. Review the [PowerShell cmdlets for SharePoint hub sites](../features/hub-site/hub-site-powershell.md) article.
158-
159-
>[!NOTE]
160-
> [Channel sites](/sharepoint/teams-connected-sites) are automatically blocked from joining a hub site.
161-
162-
163-
## See also
164-
165-
- [SharePoint site template and site script overview](site-design-overview.md)
166-
- [How to apply and customize SharePoint site templates](https://support.microsoft.com/office/apply-and-customize-sharepoint-site-templates-39382463-0e45-4d1b-be27-0e96aeec8398)
1+
---
2+
title: Get started creating SharePoint site templates and site scripts
3+
description: Create site templates to provide reusable lists, themes, layouts, pages, or custom actions so that your users can quickly build new SharePoint sites with the features they need.
4+
ms.date: 09/28/2021
5+
ms.localizationpriority: high
6+
---
7+
8+
# Get started creating site templates and site scripts
9+
10+
You can create site templates to provide reusable lists, themes, layouts, or custom actions so that your users can quickly build new SharePoint sites with the features they need.
11+
12+
This article describes how to build a simple site template that adds a SharePoint list for tracking customer orders. You'll use the site template to create a new SharePoint site with the custom list. You'll learn how to use SharePoint PowerShell cmdlets to create site scripts and site templates. You can also use REST APIs to perform the same actions. The corresponding REST calls are shown for reference in each step.
13+
14+
## Create the site script in JSON
15+
16+
A site script is a collection of actions that SharePoint runs when creating a new site. Actions describe changes to apply to the new site, such as creating a new list or applying a theme. The actions are specified in a JSON script, which is a list of all actions to apply. When a script runs, SharePoint completes each action in the order listed.
17+
18+
Each action is specified by the "verb" value in the JSON script. Also, actions can have subactions that are also "verb" values. In the following JSON, the script specifies to create a new list named **Customer Tracking**, and then subactions set the description and add several fields to define the list.
19+
20+
1. Download and install the [SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588). If you already have a previous version of the shell installed, uninstall it first and then install the latest version.
21+
1. Follow the instructions at [Connect to SharePoint Online PowerShell](https://technet.microsoft.com/library/fp161372.aspx) to connect to your SharePoint tenant.
22+
1. Create - and assign the JSON that describes the new script - to a variable as shown in the following PowerShell code. You can view and reference the latest JSON schema file here: https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json
23+
24+
```powershell
25+
$site_script = '
26+
{
27+
"$schema": "schema.json",
28+
"actions": [
29+
{
30+
"verb": "createSPList",
31+
"listName": "Customer Tracking",
32+
"templateType": 100,
33+
"subactions": [
34+
{
35+
"verb": "setDescription",
36+
"description": "List of Customers and Orders"
37+
},
38+
{
39+
"verb": "addSPField",
40+
"fieldType": "Text",
41+
"displayName": "Customer Name",
42+
"isRequired": false,
43+
"addToDefaultView": true
44+
},
45+
{
46+
"verb": "addSPField",
47+
"fieldType": "Number",
48+
"displayName": "Requisition Total",
49+
"addToDefaultView": true,
50+
"isRequired": true
51+
},
52+
{
53+
"verb": "addSPField",
54+
"fieldType": "User",
55+
"displayName": "Contact",
56+
"addToDefaultView": true,
57+
"isRequired": true
58+
},
59+
{
60+
"verb": "addSPField",
61+
"fieldType": "Note",
62+
"displayName": "Meeting Notes",
63+
"isRequired": false
64+
}
65+
]
66+
}
67+
],
68+
"bindata": { },
69+
"version": 1
70+
}
71+
'
72+
```
73+
74+
The previous script creates a new SharePoint list named **Customer Tracking**. It sets the description and adds four fields to the list. Note that each of these are considered an action. Site scripts are limited to 30 cumulative actions (across one or more scripts that may be called in a site template) if applied programmatically using the `Invoke-SPOSiteDesign` command. If they are applied through the UI or using the `Add-SPOSiteDesignTask` command then the limit is 300 cumulative actions (or 100K characters).
75+
76+
## Add the site script
77+
78+
Each site script must be registered in SharePoint so that it is available to use. Add a new site script by using the **Add-SPOSiteScript** cmdlet. The following example shows how to add the JSON script described previously.
79+
80+
```powershell
81+
C:\> Add-SPOSiteScript
82+
-Title "Create customer tracking list"
83+
-Content $site_script
84+
-Description "Creates list for tracking customer contact information"
85+
```
86+
87+
After running the cmdlet, you get a result that lists the site script **ID** of the added script. Keep track of this ID somewhere because you will need it later when you create the site template.
88+
89+
The REST API to add a new site script is **CreateSiteScript**.
90+
91+
## Create the site template
92+
93+
Next, you need to create the site template. The site template appears in a drop-down list when someone creates a new site from one of the templates. It can run one or more site scripts that have already been added.
94+
95+
- Run the following cmdlet to add a new site template. Replace `<ID>` with the site script ID from when you added the site script.
96+
97+
```powershell
98+
C:\> Add-SPOSiteDesign
99+
-Title "Contoso customer tracking"
100+
-WebTemplate "64"
101+
-SiteScripts "<ID>"
102+
-Description "Tracks key customer data in a list"
103+
```
104+
105+
The previous cmdlet creates a new site template named Contoso customer tracking.
106+
107+
| Parameter | Value | Site template type |
108+
| :------------------- | :------------------- |:----------------|
109+
| WebTemplate | 64 | Team site template |
110+
| WebTemplate | 1 | Team site (with group creation disabled) |
111+
| WebTemplate | 68 | Communication site template |
112+
| WebTemplate | 69 | Channel site template |
113+
114+
115+
The JSON response displays the **ID** of the new site template. You can use it in subsequent cmdlets to update or modify the site template.
116+
117+
The REST API to add a new site template is **CreateSiteDesign**.
118+
119+
## Use the new site template
120+
121+
Now that you've added a site script and site template, you can use it to create new sites through the self-service site creation experience or apply the site template to an existing site using the **Invoke-SPOSiteDesign** command in PowerShell. If you are using hub sites you can even associate a site template to a hub so it gets applied to all joining sites.
122+
123+
### New site creation
124+
125+
1. Go to the home page of the SharePoint site that you are using for development.
126+
1. Choose **Create site**.
127+
1. Choose the type of site you need to use. SharePoint will create a team site using the Microsoft **Team collaboration template** or a communication site using the Microsoft **Topic** template unless another custom site template is set as default.
128+
2. Choose **Next**.
129+
4. In **Site name**, enter a name for the new site **Customer order tracking**.
130+
7. Choose **Finish**.
131+
5. Next, go to **Settings** and select **Apply a site template**.
132+
5. Select the site template you just created.
133+
8. Once applied, your new template will display under the tab in the template viewer titled **From your organization.**
134+
9. When the new template has been applied, you will see the custom list on the page.
135+
136+
### Apply to an existing site
137+
138+
You can also apply a published site template to existing sites. On the home page of the site, site owners can navigate to **Settings** and then **Apply a site template** to browse and apply templates provided by your organization and Microsoft.
139+
140+
You can apply templates to existing site collections in bulk by using the [Invoke-SPOSiteDesign](/powershell/module/sharepoint-online/Invoke-SPOSiteDesign) cmdlet.
141+
142+
**Published site templates can be applied to:**
143+
144+
1. Group-connected team sites
145+
1. Team sites that not connected to a Microsoft 365 group
146+
1. Communication sites
147+
2. Channel sites
148+
3. Classic team sites
149+
4. Classic publishing sites
150+
151+
The REST API to apply a site template to an existing site collection is **ApplySiteDesign**.
152+
153+
### Associate with a hub site
154+
155+
Apply a published site template to a new or existing hub site. Then, all associated sites will inherit the hub site template and theme. Navigate to the home page of the hub and go to **Settings** and then **Apply a site template**. Learn more about how to [enable site associations for your hub site](https://support.microsoft.com/office/set-up-your-sharepoint-hub-site-e2daed64-658c-4462-aeaf-7d1a92eba098).
156+
157+
You can also use the `Set-SPOHubSite` cmdlet. Review the [PowerShell cmdlets for SharePoint hub sites](../features/hub-site/hub-site-powershell.md) article.
158+
159+
>[!NOTE]
160+
> [Channel sites](/sharepoint/teams-connected-sites) are automatically blocked from joining a hub site.
161+
162+
163+
## See also
164+
165+
- [SharePoint site template and site script overview](site-design-overview.md)
166+
- [How to apply and customize SharePoint site templates](https://support.microsoft.com/office/apply-and-customize-sharepoint-site-templates-39382463-0e45-4d1b-be27-0e96aeec8398)

0 commit comments

Comments
 (0)