added more basic content to the provisioning doc.

Author: chakkaradeep

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

@@ -2,7 +2,13 @@
 
 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. 
 
-## SharePoint items
+## Provisioning items using JavaScript code
+
+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.
+
+## Create and provision SharePoint items in your solution
+
+### SharePoint items
 
 The following SharePoint assets can be provisioned along with your client-side solution package:
 
@@ -11,7 +17,102 @@ The following SharePoint assets can be provisioned along with your client-side s
 * List Instances
 * List Instances with custom schema
 
-## Create SharePoint items in your solution
+#### Fields
+
+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. 
+
+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.
+
+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. 
+
+Below is an example of a new DateTime field:
+
+```xml
+<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
+            Name="DateOpened"
+            DisplayName="Date Opened"
+            Type="DateTime"
+            Format="DateOnly"
+            Required="FALSE"
+            Group="Financial Columns">
+        <Default>[today]</Default>
+    </Field>
+```
+#### Content Types
+
+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.
+
+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.
+
+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. 
+
+Below is an example of a content type:
+
+```xml
+<ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B" 
+    Name="Cost Center" 
+    Group="Financial Content Types" 
+    Description="Financial Content Type">
+    <FieldRefs>
+        <FieldRef ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}" />
+        <FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" /> 
+    </FieldRefs>
+</ContentType> 
+```
+
+#### Lists Instances
+
+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.
+
+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. 
+
+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.
+
+Below is an example of a list instance definition:
+
+```xml
+<ListInstance 
+    FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
+    Title="Finance Records" 
+    Description="Finance documents"
+    TemplateType="101"
+    Url="Lists/FinanceRecords">
+</ListInstance>
+```
+
+#### Lists Instances with custom schema
+
+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. 
+
+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. 
+
+Below is an example of a list instance definition that uses a custom schema:
+
+```xml
+<ListInstance 
+    CustomSchema="schema.xml"
+    FeatureId="00bfea71-de22-43b2-a848-c05709900100"
+    Title="Cost Centers" 
+    Description="Cost Centers"
+    TemplateType="100"
+    Url="Lists/CostCenters">
+</ListInstance>
+```
+And the custom schema definition that defines a content type for the list instance defined above:
+
+```xml
+<List xmlns:ows="Microsoft SharePoint" Title="Basic List" 
+      EnableContentTypes="TRUE" FolderCreation="FALSE"
+      Direction="$Resources:Direction;" Url="Lists/Basic List" 
+      BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
+  <MetaData>
+    <ContentTypes>
+      <ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
+    </ContentTypes>    
+  </MetaData>
+</List>
+```
+### Create SharePoint items in your solution
 
 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. 
 
@@ -69,7 +170,7 @@ Below is an example of an upgrade action file that applies an element manifest f
 </ApplyElementManifests>
 ```
 
-### Configure the SharePoint feature 
+#### Configure the SharePoint feature 
 
 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. 
 
@@ -113,15 +214,15 @@ elementManifests|Defined within the `assets` property, an array of element manif
 elementFiles|Defined within the `assets` property, an array of element files
 upgradeActions|Defined within the `assets` property, an array of upgrade action files
 
-### Create the feature XML files
+#### Create the feature XML files
 
 The toolchain looks for the XML files as defined in the configuration underneath a special folder - *sharepoint\assets* - in your client-side solution project. 
 
 ![Feature XML files in client-side solution project](../../images/feature-provision-project-items.png)
 
 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.
 
-### Package SharePoint items 
+#### Package SharePoint items 
 
 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.
 
@@ -133,7 +234,7 @@ The command above will package one or more client-side component manifests, such
 
 >**NOTE:** You can use the `--ship` flag to package minified versions of your components. 
 
-## Upgrade SharePoint items
+#### Upgrade SharePoint items
 
 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.