Skip to content

Commit 2cfa922

Browse files
committed
updated getting started to PS cmdlets
1 parent 8ccba32 commit 2cfa922

File tree

2 files changed

+148
-47
lines changed

2 files changed

+148
-47
lines changed

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

Lines changed: 35 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,25 @@
1-
# Get started creating site designs
1+
# Get started creating site designs and site scripts
22

33
Build site designs 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. In this article you'll build a simple site design that adds a SharePoint list for tracking customer orders. Then you'll use the site design to create a new SharePoint site with the custom list.
44

5-
## Create the JSON script
5+
This article shows how to use SharePoint PowerShell cmdlets to create site scripts and site designs. You can also use CSOM and REST APIs to perform the same actions. The corresponding CSOM and REST calls are shown for reference in each step.
6+
7+
## Create the site script in JSON
68

79
A site design is a collection of actions that SharePoint will run 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. The JSON script is a list of all actions to apply. When a script runs, SharePoint completes each action in the order listed.
810

9-
EAch action is specified by the "verb" value in the JSON scipt. Also, actions can have subactions which are also "verb" values. In the JSON below, 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.
11+
Each action is specified by the "verb" value in the JSON scipt. Also, actions can have subactions which are also "verb" values. In the JSON below, 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.
12+
13+
1. Download and install the [SharePoint Online Management Shell](https://www.microsoft.com/en-us/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.
14+
1. Follow the instructions at [Connect to SharePoint Online PowerShell](https://technet.microsoft.com/en-us/library/fp161372.aspx) to connect to your SharePoint tenant.
15+
1. Create and assign the JSON that descripts the new script to a variable as shown in the PowerShell code below.
1016

11-
1. Go to the home page of the SharePoint site you are using for development. You have to be at the home page, not inside a site or you'll receive an authentication error.
12-
1. Use the developer tools of your browser to open the console window.
13-
1. Enter the JSON script below
17+
> ![NOTE]
18+
> You can also specify the script in a CSV format. (TBD link to more info on CSV example)
1419
15-
```javascript
16-
var site_script = {
20+
```powershell
21+
$site_script = @'
22+
{
1723
"$schema": "schema.json",
1824
"actions": [
1925
{
@@ -58,60 +64,42 @@ var site_script = {
5864
"bindata": { },
5965
"version": 1
6066
}
67+
'@
6168
```
6269

63-
## Create a function to submit REST API requests
64-
65-
You'll need to interact with the site design REST API. You can use the following function to submit REST request.
66-
67-
- In the console window enter the following **restRequest** function.
68-
69-
```javascript
70-
function restRequest(url,params) {
71-
var req = new XMLHttpRequest();
72-
req.onreadystatechange = function ()
73-
{
74-
if (req.readyState != 4) // Loaded
75-
return;
76-
console.log(req.responseText);
77-
};
78-
req.open("POST",url,true);
79-
req.setRequestHeader("Content-Type", "application/json;charset=utf-8");
80-
req.setRequestHeader("ACCEPT", "application/json; odata.metadata=minimal");
81-
req.setRequestHeader("x-requestdigest", _spPageContextInfo.formDigestValue);
82-
req.setRequestHeader("ODATA-VERSION","4.0");
83-
req.send(params ? JSON.stringify(params) : void 0);
84-
}
70+
The previous script will create a new SharePoint list named Customer Tracking. It will set the description, and also add four fields to the list.
71+
72+
## Add the site script
73+
74+
Each site script must be registered in SharePoint so that it is available to. Add a new site design by using the **Add-SPOSiteScript** command. The following example shows how to add the JSON script described previously.
75+
76+
```powershell
77+
C:\> Add-SPOSiteScript -Title "Create customer tracking list" -Content $site_script -Description "Creates list for tracking customer contact information"
8578
```
8679

87-
## Register the site design
80+
After running the command you will 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 design.
8881

89-
Each site design needs to be registered in SharePoint so that it is available to users. You register a new site design by calling the **CreateSiteDesign** REST API. The following example shows how to register the JSON script that creates a new list.
82+
The REST API to add a new site script is **CreateSiteScript**. (TBD add CSOM link)
9083

91-
1. Enter the following JavaScript code into your browser's console window.
92-
93-
```javascript
94-
restRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.CreateSiteScript(Title=@title)?@title='customer orders'", site_script);
95-
```
96-
97-
1. The call returns a JSON response containing a site script **ID**. Copy this somewhere so you can use it later.
84+
## Create the site design
9885

99-
## Attach the site design to a template
86+
Next you need to create the site design. The site design will appear 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.
10087

101-
Site designs are only used with the two templates provided with SharePoint. Team site, or communication site. Call the CreateSiteDesign REST API to create the site. It takes the following parameters
102-
webTemplate: 64 for Team site and 68 for Communication site.
88+
- Run the following command to add a new site design. Replace \<ID\> with the site script ID from when you added the site script.
10389

104-
```javascript
105-
restRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.CreateSiteDesign", {info:{Title:"customer orders", Description:"Tracks customer orders", SiteScriptIds:["SiteScriptID from previous response"], WebTemplate:"64", IsDefault: false}});
90+
```powershell
91+
C:\> Add-SPOSiteDesign -Title "Contoso customer tracking" -WebTemplate "64" -SiteScripts "<ID>" -Description "Tracks key customer data in a list"
10692
```
10793

108-
The JSON response will contain an **ID** that you can use later to remove the registration if you want.
94+
The previous command creates a new site design named Contoso customer tracking. The -WebTemplate value selects which base template to associate with. The value "64" indicates Team site template, and the value "68" indicates the communication site template.
95+
96+
The JSON response will display the **ID** of the new site design. You can use in subsequent commands to update or modify the site design.
10997

110-
is default is whether it gets used by default
98+
The REST API to add a new site design is **CreateSiteDesign**. (TBD add CSOM link)
11199

112100
## Use the new site design
113101

114-
Now that the registrations are completed you can use it to create new sites.
102+
Now that you've added a site script and site design, you can use it to create new sites.
115103

116104
1. Go to the home page of the SharePoint site you are using for development.
117105
1. Choose **Create site**.
Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# PowerShell cmdlets for SharePoint site designs and site scripts
2+
3+
SharePoint tenant administrators can use PowerShell cmdlets to create, retrieve, and remove site themes. Developers can also use the SharePoint [REST API](sharepoint-site-theming-rest-api.md) to handle theme management tasks.
4+
5+
For information about how themes are defined and stored, see the [JSON schema reference](site-design-json-schema.md).
6+
7+
## Getting started
8+
9+
To run the PowerShell cmdlets for theme management, you'll need to do the following:
10+
11+
1. (TBD: is this correct download link?) Download and install the [SharePoint Online Management Shell](https://www.microsoft.com/en-us/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.
12+
1. Follow the instructions at [Connect to SharePoint Online PowerShell](https://technet.microsoft.com/en-us/library/fp161372.aspx) to connect to your SharePoint tenant.
13+
14+
To verify your setup, try using the **Get-SPOSiteScript** cmdlet to read the current list of site scripts. If the cmdlet runs and returns with no errors, you're ready to proceed.
15+
16+
## Site design cmdlets
17+
18+
The following cmdlets are available for managing site designs and site scripts from PowerShell:
19+
20+
- **Add-SPOSiteDesign**
21+
- **Add-SPOSiteScript**
22+
- **Get-SPOSiteDesign**
23+
- **Get-SPOSiteDesignRights**
24+
- **Get-SPOSiteScript**
25+
- **Grant-SPOSiteDesignRights**
26+
- **Remove-SPOSiteDesign**
27+
- **Remove-SPOSiteScript**
28+
- **Revoke-SPOSiteDesignRights**
29+
- **Update-SPOSiteDesign (TBD)**
30+
- **Update-SPOSiteScript (TBD)**
31+
32+
## Add-SPOSiteDesign
33+
34+
Creates a new site design for display in the self-service site creation flow.
35+
36+
```powershell
37+
Add-SPOSiteDesign
38+
-Title <string>
39+
-WebTemplate <string>
40+
-SiteScripts <SPOSiteScriptPipeBind[]>
41+
[-Description <string>]
42+
[-PreviewImageUrl <string>]
43+
[-PreviewImageAltText <string>]
44+
[-IsDefault]
45+
[<CommonParameters>]
46+
```
47+
48+
### Parameters
49+
50+
|Parameter | Description |
51+
|-----------|--------------|
52+
|-Title | The display name of the site design. |
53+
|-WebTemplate | Identifies which base template to add the design to. Use the value **64** for the Team site template, and the value **68** for the Communication site template. |
54+
|-SiteScripts | An array of one or more site scripts. Each is identified by an ID. |
55+
|[-Description] | The display description of site design. |
56+
|[-PreviewImageUrl] | The URL of a preview image. If none is specified SharePoint will use a generic image. (TBD where should you put the image on SharePoint) |
57+
|[-PreviewImageAltText] | An alternate text description of the image for accessibility. |
58+
|[-IsDefault] | **$true** if the site design is to be applied to the default template; otherwise **$false**. |
59+
60+
Here's an example of creating a new site design.
61+
62+
```powershell
63+
C:\> Add-SPOSiteDesign `
64+
-Title "Contoso customer tracking" `
65+
-WebTemplate "64" `
66+
-SiteScripts "<ID>" `
67+
-Description "Tracks key customer data in a list" `
68+
-PreviewImageUrl "https://spdfcontosodemo2.sharepoint.com/sites/davechhalloween/Shared%20Documents/Forms/AllItems.aspx?id=%
69+
2Fsites%2Fdavechhalloween%2FShared%20Documents%2Fsite-preview%2Epng" `
70+
-PreviewImageAltText "site preview" `
71+
-IsDefault $false
72+
```
73+
74+
## **Add-SPOSiteScript**
75+
76+
Uploads a new site script to the gallery for use either directly (TBD – via script or app catalog) or in a site design. This command will support inline script; file reference TBD.
77+
78+
```powershell
79+
Add-SPOSiteScript
80+
-Title <string>
81+
-Content <string>
82+
[-Description <string>]
83+
[<CommonParameters>]
84+
```
85+
86+
### Parameters
87+
88+
|Parameter | Description |
89+
|--------------|--------------|
90+
| -Title | The display name of the site design. |
91+
| -Content | JSON or CSV value that describes the script. |
92+
| -Description | A description of the script. |
93+
94+
Here's an example of creating a new site script.
95+
96+
```powershell
97+
C:\> $site_script = @'
98+
{
99+
"$schema": "schema.json",
100+
"actions": [
101+
{
102+
"verb": "setSiteLogo",
103+
"url": "/Customer Event Collateral/logo.jpg"
104+
}
105+
],
106+
"bindata": { },
107+
"version": 1
108+
}
109+
'@
110+
C:\> Add-SPOSiteScript -Title "Customer logo" -Content $site_script -Description "Applies customer logo for customer sites"
111+
```
112+
113+

0 commit comments

Comments
 (0)