Skip to content

Commit 8277d4a

Browse files
davidchesnutdavidchesnut
committed
additional site design docs
1 parent 2cfa922 commit 8277d4a

File tree

4 files changed

+227
-12
lines changed

4 files changed

+227
-12
lines changed

‎docs/declarative-customization/site-design-json-schema.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -250,7 +250,7 @@ Example:
250250

251251
## Set a site logo
252252

253-
Use the **setSiteLogo** verb to specify a logo for your site.
253+
Use the **setSiteLogo** verb to specify a logo for your site. This action only works on the communication site template (68).
254254

255255
JSON value:
256256

‎docs/declarative-customization/site-design-overview.md

Lines changed: 49 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -30,23 +30,61 @@ For more information, see [Get started creating site designs](get-started-create
3030

3131
## Anatomy of a site script
3232

33-
Site scripts are JSON files that specify an ordered list of actions to run when creating the new site. Here's an example of a script with only one action that simply applies the blue yonder theme.
33+
Site scripts are JSON files that specify an ordered list of actions to run when creating the new site. The actions are run in the order listed. The following example is a script that has two top-level actions. First it applies a theme that was previously created named **Contoso Explorers**. Then it creates a **Customer Tracking** list.
3434

3535
```json
3636
{
37-
"$schema": "schema.json",
38-
"actions": [
39-
{
40-
verb: "applyTheme",
41-
themeName: "Blue Yonder"
42-
}
43-
],
44-
"bindata": { },
45-
"version": 1
37+
"$schema": "schema.json",
38+
"actions": [
39+
{
40+
"verb": "applyTheme",
41+
"themeName": "Contoso Explorers"
42+
},
43+
{
44+
"verb": "createSPList",
45+
"listName": "Customer Tracking",
46+
"templateType": 100,
47+
"subactions": [
48+
{
49+
"verb": "SetDescription",
50+
"description": "List of Customers and Orders"
51+
},
52+
{
53+
"verb": "addSPField",
54+
"fieldType": "Text",
55+
"displayName": "Customer Name",
56+
"isRequired": false,
57+
"addToDefaultView": true
58+
},
59+
{
60+
"verb": "addSPField",
61+
"fieldType": "Number",
62+
"displayName": "Requisition Total",
63+
"addToDefaultView": true,
64+
"isRequired": true
65+
},
66+
{
67+
"verb": "addSPField",
68+
"fieldType": "User",
69+
"displayName": "Contact",
70+
"addToDefaultView": true,
71+
"isRequired": true
72+
},
73+
{
74+
"verb": "addSPField",
75+
"fieldType": "Note",
76+
"displayName": "Meeting Notes",
77+
"isRequired": false
78+
}
79+
]
80+
}
81+
],
82+
"bindata": { },
83+
"version": 1
4684
}
4785
```
4886

49-
Each action in a site script is specified by a **verb** in the JSON.
87+
Each action in a site script is specified by a **verb** value in the JSON. In the previous script the first action is specified by the **applyTheme** verb. Then the **createSPList** verb creates the list. Notice that the **createSPList** verb contains its own set of verbs which run additional actions on just the list.
5088

5189
Actions include:
5290

‎docs/declarative-customization/site-design-powershell.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@ The following cmdlets are available for managing site designs and site scripts f
2929
- **Update-SPOSiteDesign (TBD)**
3030
- **Update-SPOSiteScript (TBD)**
3131

32+
## Identity for site designs and site scripts
33+
34+
In many commands you'll see a parameter of type **SPOSiteDesignPipeBind** or **SPOSiteScriptPipeBind**. This parameter is a GUID. It uniquely identifies the site design or site script. You'll see it used with commands like **Get-SPOSiteDesign**, or **Remove-SPOSiteDesign**.
35+
3236
## Add-SPOSiteDesign
3337

3438
Creates a new site design for display in the self-service site creation flow.
@@ -110,4 +114,112 @@ C:\> $site_script = @'
110114
C:\> Add-SPOSiteScript -Title "Customer logo" -Content $site_script -Description "Applies customer logo for customer sites"
111115
```
112116

117+
## Get-SPOSiteDesign
118+
119+
Gets details about site designs that are on the SharePoint tenant. You can specify an ID of a specific site design to retrieve. If there are no parameters listed, then details about all site designs are listed.
120+
121+
```powershell
122+
Get-SPOSiteDesign
123+
[[-Identity] <SPOSiteDesignPipeBind>]
124+
[<CommonParameters>]
125+
```
126+
127+
### Parameters
128+
129+
|Parameter | Description |
130+
|--------------|--------------|
131+
| [-Identity] | The ID of the site design to retrieve. |
132+
133+
## Get-SPOSiteDesignRights
134+
135+
Displays a list of principals and their rights for usage of the site design. This can be used to determine the scope that your site design has with users on the tenant.
136+
137+
```powershell
138+
Get-SPOSiteDesignRights
139+
[-Identity] <SPOSiteDesignPipeBind>
140+
[<CommonParameters>]
141+
```
142+
143+
### Parameters
144+
145+
|Parameter | Description |
146+
|--------------|--------------|
147+
| [-Identity] | The ID of the site design to get scoping information. |
148+
149+
## Get-SPOSiteScript
150+
151+
## Grant-SPOSiteDesignRights
152+
153+
sed to apply permissions to set of users or security group, effectively scoping visibility of site design in UX. They start off public. But once you set permissions, only those groups or users with permissions can access the site design.
154+
155+
```powershell
156+
Grant-SPOSiteDesignRights
157+
[-Identity] <SPOSiteDesignPipeBind>
158+
-Principals <string[]>
159+
-Rights {View}
160+
[<CommonParameters>]
161+
```
162+
163+
### Parameters
164+
165+
|Parameter | Description |
166+
|--------------|--------------|
167+
| [-Identity] | The ID of the site design to get scoping information. |
168+
| -Principals | One or more principles to add permissions for. |
169+
| -Rights | Always set to the value **View**. Any user or group with view permissions can view and use the site design. |
170+
171+
## Remove-SPOSiteDesign
172+
173+
Removes a site design. It will no longer appear in the UI for creating a new site.
174+
175+
```powershell
176+
Remove-SPOSiteDesign
177+
[-Identity] <SPOSiteDesignPipeBind>
178+
[<CommonParameters>]
179+
```
180+
181+
### Parameters
182+
183+
|Parameter | Description |
184+
|--------------|--------------|
185+
| [-Identity] | The ID of the site design to remove. |
186+
187+
## Remove-SPOSiteScript
188+
189+
Removes a site script. (TBD handling dependency on site design)
190+
191+
```powershell
192+
Remove-SPOSiteScript
193+
[-Identity] <SPOSiteScriptPipeBind>
194+
[<CommonParameters>]
195+
```
196+
197+
### Parameters
198+
199+
|Parameter | Description |
200+
|--------------|--------------|
201+
| [-Identity] | The ID of the site script to remove. |
202+
203+
## Revoke-SPOSiteDesignRights
204+
205+
Revokes rights for specified principals from a site design.
206+
207+
```powershell
208+
Revoke-SPOSiteDesignRights
209+
[-Identity] <SPOSiteDesignPipeBind>
210+
-Principals <string[]>
211+
[<CommonParameters>]
212+
```
213+
214+
### Parameters
215+
216+
|Parameter | Description |
217+
|--------------|--------------|
218+
| [-Identity] | The ID of the site design from which to revoke rights. |
219+
| -Principals | One or more principals to revoke rights on the specified site design. |
220+
221+
## Update-SPOSiteDesign (TBD)
222+
223+
## Update-SPOSiteScript (TBD)
224+
113225

‎docs/declarative-customization/site-design-scoping.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Site design scoping
2+
3+
Site designs are available to everyone by default. But you can scope site designs so that they are only available to specific users or groups. For example, the accounting apartment may have specific site designs they use, but it may not make sense to share those site designs with everyone. This article will explain how you can control which users and groups can see specific site designs.
4+
5+
## Granting rights to a site design
6+
7+
When a site design is first created it is available to everyone. You can grant **View** rights to the site design. Once rights are granted, only the users or groups (principals) specified have access. You can continue granting rights to more principals with subsequent API calls. The only way to restore access to everyone is to revoke all rights (shown later).
8+
9+
## Granting rights to security groups
10+
11+
Here's an example of how to scope an existing site design so that only the mail-enabled security group sitedesignscope can view and use the site design.
12+
13+
```powershell
14+
Grant-SPOSiteDesignRights `
15+
-Identity db752673-18fd-44db-865a-aa3e0b28698e `
16+
-Principals ("[email protected]") `
17+
-Rights View
18+
```
19+
20+
With PowerShell, you can also connect multiple commands. For example, you can create a new site design and scope it at the same time.
21+
22+
```powershell
23+
Add-SPOSiteDesign `
24+
-Title "Scoped site design" `
25+
-Description "Scoped to only the sitedesignscope SG" `
26+
-SiteScripts 256494cb-bd31-4f60-9eba-285308d7a863 `
27+
-WebTemplate 64 `
28+
-PreviewImageUrl "https://contoso.com/SiteAssets/scope-image.png" `
29+
| Grant-SPOSiteDesignRights `
30+
-Principals ("[email protected]") `
31+
-Rights View
32+
```
33+
34+
## Granting rights to users
35+
36+
Here's an example of how to scope an existing site design so that only Nestor (a user at the fictional Contoso site) can view and use the site design.
37+
38+
```powershell
39+
Grant-SPOSiteDesignRights `
40+
-Identity 44252d09-62c4-4913-9eb0-a2a8b8d7f863 `
41+
-Principals [email protected] `
42+
-Rights View
43+
```
44+
45+
## Granting rights to groups
46+
47+
(tbd need more info on groups)
48+
49+
50+
## Viewing rights assigned to a site design
51+
52+
53+
## Revoking rights from a site design
54+
55+
You can revoke rights for any principal. If you revoke all rights, then the site design will again be available to everyone.
56+
57+
Here's an example of revoking access for the sitedesignscope mail-enabled security group.
58+
59+
```powershell
60+
Revoke-SPOSiteDesignRights `
61+
-Identity db752673-18fd-44db-865a-aa3e0b28698e `
62+
-Principals ("[email protected]") `
63+
```
64+
65+
(TBD need to show how to use an array of principals)

0 commit comments

Comments
 (0)