Skip to content

Commit 0bc1982

Browse files
chakkaradeepchakkaradeep
committed
first draft of provision sharepoint assets
1 parent 96bd6e7 commit 0bc1982

File tree

2 files changed

+164
-0
lines changed

2 files changed

+164
-0
lines changed

‎docs/spfx/toolchain/provision-sharepoint-assets.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Provision SharePoint items with your solution package
2+
3+
At times, you may need to provision a SharePoint list or a document library along with your client-side solution package so that that list or library is available for your client-side components, such as web parts. SharePoint Framework toolchain allows you to package and deploy SharePoint assets with your client-side solution package. These assets are then provisioned when the client-side solution is installed on a site.
4+
5+
## SharePoint items
6+
7+
The following SharePoint assets can be provisioned along with your client-side solution package:
8+
9+
* Fields
10+
* Content Types
11+
* List Instances
12+
* List Instances with custom schema
13+
14+
## Create SharePoint items in your solution
15+
16+
The solution package uses [SharePoint Features](https://msdn.microsoft.com/en-us/library/ee537350(office.14).aspx) to package and provision the SharePoint items. A Feature is a container that includes one or more SharePoint items to provision. A Feature contains a Feature.xml file and one or more element manifest files. These XML files are also known as Feature definitions.
17+
18+
Typically, a client-side solution package contains one feature. This feature is activated when the solution is installed in a site. It is important to note that the site administrators install your solution package and not the feature.
19+
20+
A feature is primarily constructed by using the following XML files:
21+
22+
**Element Manifest File**
23+
24+
The element manifest file contains the SharePoint item definitions and will be executed when the feature is activated. For example: The XML definitions to create a new field or content type or list instance(s) will be in the element manifest.
25+
26+
Below is an example of an element manifest file that defines a new DateTime field.
27+
28+
```xml
29+
<?xml version="1.0" encoding="utf-8"?>
30+
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
31+
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
32+
Name="DateOpened"
33+
DisplayName="Date Opened"
34+
Type="DateTime"
35+
Format="DateOnly"
36+
Required="FALSE"
37+
Group="Financial Columns">
38+
<Default>[today]</Default>
39+
</Field>
40+
</Elements>
41+
```
42+
43+
**Element File**
44+
45+
Any supported files that accompany the element manifest will be an element file. For example, the list instance schema is an element manifest that is associated with a list instance that is defined in an element manifest.
46+
47+
Below is an example of a custom list instance schema:
48+
49+
```xml
50+
<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE"
51+
Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
52+
<MetaData>
53+
<ContentTypes>
54+
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
55+
</ContentTypes>
56+
</MetaData>
57+
</List>
58+
```
59+
60+
**Upgrade Actions File**
61+
62+
As it name suggests, this is the file that will include any upgrade actions when the solution is updated in the site. As part of the upgrade actions, the action could specify to include one or more element manifests as well. For example: If the upgrade requires a new field to be added, then the field definition will be available as an element manifest and associated in the upgrade actions file.
63+
64+
Below is an example of an upgrade action file that applies an element manifest file during the upgrade:
65+
66+
```xml
67+
<ApplyElementManifests>
68+
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
69+
</ApplyElementManifests>
70+
```
71+
72+
### Configure the SharePoint feature
73+
74+
In order to include the XML files, you will need to first define the feature configuration in the *package-solution.json* configuration file underneath the *config* folder in your project. The *package-solution.json* contains the key metadata information about your client-side solution package and is referenced when you run the `package-solution` gulp task which packages your solution into a `.sppkg` file.
75+
76+
```json
77+
{
78+
"solution": {
79+
"name": "hello-world-client-side-solution",
80+
"id": "26364618-3056-4b45-98c1-39450adc5723",
81+
"version": "1.1.0.0",
82+
"features": [{
83+
"title": "hello-world-client-side-solution",
84+
"description": "hello-world-client-side-solution",
85+
"id": "d46cd9d6-87fc-473b-a4c0-db9ad9162b64",
86+
"assets": {
87+
"elementManifests": [
88+
"elements.xml"
89+
],
90+
"elementFiles":[
91+
"schema.xml"
92+
],
93+
"upgradeActions":[
94+
"upgrade-actions-v1.xml"
95+
]
96+
}
97+
}]
98+
},
99+
"paths": {
100+
"zippedPackage": "solution/hello-world.sppkg"
101+
}
102+
}
103+
```
104+
The `features` JSON object contains the metadata about the feature:
105+
106+
Property | Description
107+
-----|------
108+
id|Unique identifier (GUID) of the feature
109+
title|Title of the feature
110+
description| Description of the feature
111+
assets|An array of XML files used in the feature
112+
elementManifests|Defined within the `assets` property, an array of element manifest files
113+
elementFiles|Defined within the `assets` property, an array of element files
114+
upgradeActions|Defined within the `assets` property, an array of upgrade action files
115+
116+
### Create the feature XML files
117+
118+
The toolchain looks for the XML files as defined in the configuration underneath a special folder - *sharepoint\assets* - in your client-side solution project.
119+
120+
![Feature XML files in client-side solution project](../../images/feature-provision-project-items.png)
121+
122+
The configurations defined in the `package-solution.json` is what maps the XML files here to its appropriate feature XML file when the `package-solution` gulp task is executed.
123+
124+
### Package SharePoint items
125+
126+
Once you have defined your feature in the `package-solution.json` and created the respective feature XML files, you can use the following gulp task to package the SharePoint items along with your `.sppkg` package.
127+
128+
```js
129+
gulp package-solution
130+
```
131+
132+
The command above will package one or more client-side component manifests, such as web parts, along with the feature XML files referenced in the `package-solution.json` configuration file.
133+
134+
>**NOTE:** You can use the `--ship` flag to package minified versions of your components.
135+
136+
## Upgrade SharePoint items
137+
138+
You may include new SharePoint items or update existing SharePoint items when you upgrade your client-side solution. Since provisioning SharePoint items uses features, you will be using the [feature upgrade actions](https://msdn.microsoft.com/en-us/library/office/ee537575(v=office.14).aspx) XML file to define a list of upgrade actions.
139+
140+
The `upgradeActions` JSON object array in the `package-solution.json` references the feature XML file(s) associated with the upgrade actions for your feature. At the least, an upgrade action file will define the element manifest XML file that will be executed when upgrading the feature.
141+
142+
Below is an example of an upgrade action file that applies an element manifest file during the upgrade:
143+
144+
```xml
145+
<ApplyElementManifests>
146+
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
147+
</ApplyElementManifests>
148+
```
149+
150+
And the corresponding `element-v2.xml` which defines a new Currency Field to be provisioned during the upgrade:
151+
152+
```xml
153+
<?xml version="1.0" encoding="utf-8"?>
154+
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
155+
<Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
156+
Name="Amount"
157+
DisplayName="Amount"
158+
Type="Currency"
159+
Decimals="2"
160+
Min="0"
161+
Required="FALSE"
162+
Group="Financial Columns" />
163+
</Elements>
164+
```

‎images/feature-provision-project-items.png

46.2 KB
Loading

0 commit comments

Comments
 (0)