Skip to content

Commit e018c0f

Browse files
chakkaradeepchakkaradeep
authored
Merge pull request SharePoint#445 from SharePoint/staging
GA docs
2 parents f0084c4 + d2cac90 commit e018c0f

7 files changed

+359
-1
lines changed

‎docs/spfx/set-up-your-development-environment.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ Enter the following command to install the Yeoman SharePoint generator:
8585
```
8686
npm install -g @microsoft/generator-sharepoint
8787
```
88-
>**Note:** yeoman generator for SharePoint is targeted to get deployed globally with the intial General Availability (GA) version. There are some known issues if it's installed locally to the project, which are planned to be addressed post GA.
88+
>**Note:** Yeoman generator for SharePoint is targeted to get deployed globally with the initial General Availability (GA) version. There are some known issues if it's installed locally to the project, which are planned to be addressed post GA.
8989
9090

9191
## Optional tools

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

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
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 items with your client-side solution package. These items are then provisioned when the client-side solution is installed on a site.
4+
5+
## Provisioning items using JavaScript code
6+
7+
While it is possible to create SharePoint items using JavaScript code in your component, such as web parts, it is limited to context of the current user using that component. If the user doesn't have sufficient permissions to create or modify SharePoint items, the JavaScript code will not provision those items. In such cases, when you want to provision SharePoint items in an elevated context, you will need to package and deploy the items along with your solution package.
8+
9+
## Create and provision SharePoint items in your solution
10+
11+
### SharePoint items
12+
13+
The following SharePoint assets can be provisioned along with your client-side solution package:
14+
15+
* Fields
16+
* Content Types
17+
* List Instances
18+
* List Instances with custom schema
19+
20+
#### Fields
21+
22+
A field or a site column represents an attribute, or piece of metadata, that the user wants to manage for the items in the list or content type to which they added the column. It is a reusable column definition, or template, that you can assign to multiple lists across multiple SharePoint sites. Site columns decrease rework and help you ensure consistency of metadata across sites and lists.
23+
24+
For example, suppose you define a site column named Customer. Users can add that column to their lists, and reference it in their content types. This ensures that the column has the same attributes—at least to start with—wherever it appears.
25+
26+
You can refer to the schema and attributes in the [Field Element](https://msdn.microsoft.com/en-us/library/aa979575(v=office.15).aspx) documentation to define a new field in your solution.
27+
28+
Below is an example of a new DateTime field:
29+
30+
```xml
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+
```
41+
#### Content Types
42+
43+
A content type is a reusable collection of metadata (columns), behavior, and other settings for a category of items or documents in a SharePoint list or document library. Content types enable you to manage the settings for a category of information in a centralized, reusable way.
44+
45+
For example, imagine a business situation in which you have three different types of documents: expense reports, purchase orders, and invoices. All three types of documents have some characteristics in common; for one thing, they are all financial documents and contain data with values in currency. Yet each type of document has its own data requirements, its own document template, and its own workflow. One solution to this business problem is to create four content types. The first content type, Financial Document, could encapsulate data requirements that are common to all financial documents in the organization. The remaining three, Expense Report, Purchase Order, and Invoice, could inherit common elements from Financial Document. In addition, they could define characteristics that are unique to each type, such as a particular set of metadata, a document template to be used in creating a new item, and a specific workflow for processing an item.
46+
47+
You can refer to the schema and attributes in the [Content Type Element](https://msdn.microsoft.com/en-us/library/aa544268.aspx) documentation to define a new content type in your solution.
48+
49+
Below is an example of a content type:
50+
51+
```xml
52+
<ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
53+
Name="Cost Center"
54+
Group="Financial Content Types"
55+
Description="Financial Content Type">
56+
<FieldRefs>
57+
<FieldRef ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}" />
58+
<FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
59+
</FieldRefs>
60+
</ContentType>
61+
```
62+
63+
#### Lists Instances
64+
65+
Lists are a key, underlying feature of a SharePoint site. They enable teams to gather, track, and share information. Many applications rely on lists created at the site for data storage to implement their behaviors. A list instance is a predefined SharePoint list that has a well-known identifier. You can customize and add items to these lists, create additional lists from the list templates that are already available, and create custom lists with just the settings and columns that you choose.
66+
67+
SharePoint provides several list templates such as contact list, calendar, task list and more. You can use these templates to create new list instances for your web parts or other components. For example, you can define a list instance Finance Documents based on the Document Library template to store associated documents with your web part.
68+
69+
You can refer to the schema and attributes in the [List Instance Element](https://msdn.microsoft.com/en-us/library/office/ms476062.aspx) documentation to define a list instance in your solution.
70+
71+
Below is an example of a list instance definition:
72+
73+
```xml
74+
<ListInstance
75+
FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
76+
Title="Finance Records"
77+
Description="Finance documents"
78+
TemplateType="101"
79+
Url="Lists/FinanceRecords">
80+
</ListInstance>
81+
```
82+
83+
#### Lists Instances with custom schema
84+
85+
You can use a custom list schema definition to define your fields, content types and views used in your list instance. You will use the `customschema` attribute in the [list instance element](https://msdn.microsoft.com/en-us/library/office/ms476062.aspx#sectionSection0) to reference a custom schema for the list instance.
86+
87+
For example, you can define a list instance Finance Documents with a content type Financial Document that could encapsulate data requirements that are common to all financial documents in the organization.
88+
89+
Below is an example of a list instance definition that uses a custom schema:
90+
91+
```xml
92+
<ListInstance
93+
CustomSchema="schema.xml"
94+
FeatureId="00bfea71-de22-43b2-a848-c05709900100"
95+
Title="Cost Centers"
96+
Description="Cost Centers"
97+
TemplateType="100"
98+
Url="Lists/CostCenters">
99+
</ListInstance>
100+
```
101+
And the custom schema definition that defines a content type for the list instance defined above:
102+
103+
```xml
104+
<List xmlns:ows="Microsoft SharePoint" Title="Basic List"
105+
EnableContentTypes="TRUE" FolderCreation="FALSE"
106+
Direction="$Resources:Direction;" Url="Lists/Basic List"
107+
BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
108+
<MetaData>
109+
<ContentTypes>
110+
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
111+
</ContentTypes>
112+
</MetaData>
113+
</List>
114+
```
115+
### Create SharePoint items in your solution
116+
117+
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.
118+
119+
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.
120+
121+
A feature is primarily constructed by using the following XML files:
122+
123+
**Element Manifest File**
124+
125+
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.
126+
127+
Below is an example of an element manifest file that defines a new DateTime field.
128+
129+
```xml
130+
<?xml version="1.0" encoding="utf-8"?>
131+
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
132+
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
133+
Name="DateOpened"
134+
DisplayName="Date Opened"
135+
Type="DateTime"
136+
Format="DateOnly"
137+
Required="FALSE"
138+
Group="Financial Columns">
139+
<Default>[today]</Default>
140+
</Field>
141+
</Elements>
142+
```
143+
144+
**Element File**
145+
146+
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.
147+
148+
Below is an example of a custom list instance schema:
149+
150+
```xml
151+
<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE"
152+
Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
153+
<MetaData>
154+
<ContentTypes>
155+
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
156+
</ContentTypes>
157+
</MetaData>
158+
</List>
159+
```
160+
161+
**Upgrade Actions File**
162+
163+
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.
164+
165+
Below is an example of an upgrade action file that applies an element manifest file during the upgrade:
166+
167+
```xml
168+
<ApplyElementManifests>
169+
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
170+
</ApplyElementManifests>
171+
```
172+
173+
#### Configure the SharePoint feature
174+
175+
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.
176+
177+
```json
178+
{
179+
"solution": {
180+
"name": "hello-world-client-side-solution",
181+
"id": "26364618-3056-4b45-98c1-39450adc5723",
182+
"version": "1.1.0.0",
183+
"features": [{
184+
"title": "hello-world-client-side-solution",
185+
"description": "hello-world-client-side-solution",
186+
"id": "d46cd9d6-87fc-473b-a4c0-db9ad9162b64",
187+
"assets": {
188+
"elementManifests": [
189+
"elements.xml"
190+
],
191+
"elementFiles":[
192+
"schema.xml"
193+
],
194+
"upgradeActions":[
195+
"upgrade-actions-v1.xml"
196+
]
197+
}
198+
}]
199+
},
200+
"paths": {
201+
"zippedPackage": "solution/hello-world.sppkg"
202+
}
203+
}
204+
```
205+
The `features` JSON object contains the metadata about the feature:
206+
207+
Property | Description
208+
-----|------
209+
id|Unique identifier (GUID) of the feature
210+
title|Title of the feature
211+
description| Description of the feature
212+
assets|An array of XML files used in the feature
213+
elementManifests|Defined within the `assets` property, an array of element manifest files
214+
elementFiles|Defined within the `assets` property, an array of element files
215+
upgradeActions|Defined within the `assets` property, an array of upgrade action files
216+
217+
#### Create the feature XML files
218+
219+
The toolchain looks for the XML files as defined in the configuration underneath a special folder - *sharepoint\assets* - in your client-side solution project.
220+
221+
![Feature XML files in client-side solution project](../../images/feature-provision-project-items.png)
222+
223+
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.
224+
225+
#### Package SharePoint items
226+
227+
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.
228+
229+
```js
230+
gulp package-solution
231+
```
232+
233+
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.
234+
235+
>**NOTE:** You can use the `--ship` flag to package minified versions of your components.
236+
237+
#### Upgrade SharePoint items
238+
239+
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.
240+
241+
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.
242+
243+
Below is an example of an upgrade action file that applies an element manifest file during the upgrade:
244+
245+
```xml
246+
<ApplyElementManifests>
247+
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
248+
</ApplyElementManifests>
249+
```
250+
251+
And the corresponding `element-v2.xml` which defines a new Currency Field to be provisioned during the upgrade:
252+
253+
```xml
254+
<?xml version="1.0" encoding="utf-8"?>
255+
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
256+
<Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
257+
Name="Amount"
258+
DisplayName="Amount"
259+
Type="Currency"
260+
Decimals="2"
261+
Min="0"
262+
Required="FALSE"
263+
Group="Financial Columns" />
264+
</Elements>
265+
```
266+
267+
Upgrade actions in client-side solutions support the following sub elements:
268+
269+
270+
**AddContentTypeField**
271+
272+
Adds a new field to an existing provisioned content type. Propagates the change from the site content type to all child lists and content types within the site. For example:
273+
274+
```xml
275+
<AddContentTypeField
276+
ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7"
277+
FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}"
278+
PushDown="TRUE" />
279+
```
280+
281+
**ApplyElementManifests**
282+
283+
Adds a new element to an existing Feature. When a Feature is upgraded, provisions all non-declarative elements that are referenced in the specified element manifests.
284+
285+
**VersionRange**
286+
287+
Specifies a version range to which specified upgrade actions apply.

‎docs/spfx/toolchain/scaffolding-projects-using-yeoman-sharepoint-generator.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Scaffold projects using yeoman SharePoint generator
2+
3+
[Yeoman](http://yeoman.io/) helps you to kickstart new projects, prescribing best practices and tools to help you stay productive. Using the yeoman SharePoint generator, developers are able to scaffold new client-side solution projects to build, package and deploy SharePoint solutions. The generator provides common build tools, boilerplate code, and a common playground web site to host web parts for testing.
4+
5+
## Installing the yeoman SharePoint generator
6+
7+
Yeoman SharePoint generator is available as part of the framework as a [npm package](https://www.npmjs.com/package/@microsoft/generator-sharepoint). You can install the generator by executing the following command in a console:
8+
9+
```
10+
npm install @microsoft/generator-sharepoint -g
11+
```
12+
13+
>**Note:** Yeoman generator for SharePoint is targeted to get deployed globally with the initial General Availability (GA) version. There are some known issues if it's installed locally to the project, which are planned to be addressed post GA.
14+
15+
It is recommended you follow the [set up your development environment](../spfx/set-up-your-development-environment.md) to configure your machine with the complete set of developer tools, including yeoman SharePoint generator.
16+
17+
## Using the yeoman SharePoint generator
18+
19+
Once the generator is installed, you can invoke the generator by just typing the following command in a console:
20+
21+
```
22+
yo
23+
```
24+
25+
The command will list all of the generators available in your machine. Select the `@microsoft/sharepoint` to invoke the SharePoint generator and continue with the prompts to successfully create your client-side solution:
26+
27+
![yeoman SharePoint generator](../../images/yeoman-sp-generator.png)
28+
29+
## Available command line options for the generator
30+
31+
You can use the command line options available with the yeoman SharePoint generator to scaffold projects in one command instead of going through the prompts. Execute the following command to see the list of command line options available for the SharePoint generator:
32+
33+
```
34+
yo @microsoft/generator-sharepoint --help
35+
```
36+
37+
![yeoman SharePoint generator command line options](../../images/yeoman-sp-cmdline-options.png)
38+
39+
Option | Description
40+
-----|------
41+
--skip-install|Do no automatically install dependencies.
42+
--solutionName|Client-side solution name, as well as folder name.
43+
--framework|Framework to use for the solution. Choose one from "none", "react", "knockout".
44+
--componentType|Component type. Currently only "webpart" is supported.
45+
--componentName|Name of the component.
46+
--componentDescription|Description of the component.
47+
48+
Below is an example of a command that creates a solution called "hello-world" with a web part "HelloWorld" with "react" framework:
49+
50+
```
51+
yo @microsoft/sharepoint --solutionName "hello-world" --framework "react" --componentType "webpart" --componentName "HelloWorld" --componentDescription "HelloWorld web part"
52+
```
53+
54+
### Notes on --skip-install
55+
56+
Using the `--skip-install` command will scaffold the project and skip installing dependencies. This means, to successfully build the project, you will need to install the dependencies later once the project is scaffolded.
57+
58+
If you try to build your project without installing the dependencies, then you will get the following error. This indicates you need to install the dependencies before building the project:
59+
60+
```
61+
Local gulp not found in ~/<project-name>
62+
Try running: npm install gulp
63+
```
64+
65+
You can execute the following command to install the dependencies:
66+
67+
```
68+
npm install
69+
```

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

46.2 KB
Loading

‎images/yeoman-sp-cmdline-options.png

106 KB
Loading

‎images/yeoman-sp-generator.png

97.8 KB
Loading

0 commit comments

Comments
 (0)