Minor grammatical updates (SharePoint#675)

Author: thechriskent

docs/spfx/web-parts/guidance/use-sp-pnp-js-with-spfx-web-parts.md

@@ -1,15 +1,12 @@
 # Use sp-pnp-js with SharePoint Framework Web Parts
 
-You may opt to use the [sp-pnp-js](https://www.npmjs.com/package/sp-pnp-js) library when building your SharePoint Framework web parts. This library 
-provides a fluent API to make building your REST queries intuitive and supports batching and caching. You can learn more on the [project's homepage](https://github.com/SharePoint/PnP-JS-Core) 
-which has links to documentation, samples, and other resources to help you get started.
+You may opt to use the [sp-pnp-js](https://www.npmjs.com/package/sp-pnp-js) library when building your SharePoint Framework (SPFx) web parts. This library provides a fluent API to make building your REST queries intuitive and supports batching and caching. You can learn more on the [project's homepage](https://github.com/SharePoint/PnP-JS-Core) which has links to documentation, samples, and other resources to help you get started.
 
 You can download the [full source](https://github.com/SharePoint/sp-dev-fx-webparts/tree/master/samples/knockout-sp-pnp-js) for this article from the samples site.
 
 ## Setup your Environment
 
-Before you can complete this guide you will need to ensure you have [setup your environment](https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment) for development 
-using SharePoint Framework.
+Before you can complete this guide, you will need to ensure you have [setup your environment](https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment) for development using the SharePoint Framework.
 
 ## Create a New Project
 
@@ -19,30 +16,30 @@ Start by creating a new folder for the project using your console of choice:
 md spfx-sp-pnp-js-example
 ```
 
-And enter that folder
+And enter that folder:
 
 ```sh
 cd spfx-sp-pnp-js-example
 ```
 
-The run the Yeoman generator for SPFx
+Then run the Yeoman generator for SPFx:
 
 ```sh
 yo @microsoft/sharepoint
 ```
 
-Enter the following values when prompted during the setup of your new project:
+Enter the following values when prompted during the setup of the new project:
 
 - **spfx-sp-pnp-js-example** as solution name (keep default)
 - **Current Folder** as the solution ___location
-- **Kockout** as the framework
+- **Knockout** as the framework
 - **SPPnPJSExample** as the name of the web part
 - **Example of using sp-pnp-js within SPFx** as the description
 
 ![Completed Project Scaffolding](../../../../images/sp-pnp-js-guide-completed-setup.png)
 
 
-Once the scaffolding completes open the project in your code editor of choice, the screen shots here show [Visual Studio Code](https://code.visualstudio.com/).
+Once the scaffolding completes, open the project in the code editor of your choosing. The screenshots shown here demonstrate [Visual Studio Code](https://code.visualstudio.com/). To open the directory within Visual Studio Code, enter the following in the console:
 
 ```sh
 code .
@@ -52,28 +49,24 @@ code .
 
 ## Install And Setup sp-pnp-js
 
-Once your project is created you will need to install and setup sp-pnp-js, starting with installing the package. This section is common for any project type (React, etc).
+Once your project is created you will need to install and setup sp-pnp-js, starting with installing the package. These steps are common for any project type (React, etc).
 
 ```sh
 npm install sp-pnp-js --save
 ```
 
-Because the sp-pnp-js library constructs REST requests it needs to know the URL to send these requests. When operating within classic sites and pages 
-we can make use of the global _spPageContextInfo variable. Within SPFx this is not available, or if it is may not be correct. So we need to rely on the 
-[context](https://dev.office.com/sharepoint/reference/spfx/sp-webpart-base/iwebpartcontext) object 
-supplied by the framework. There are [two ways](https://github.com/SharePoint/PnP-JS-Core/wiki/Using-sp-pnp-js-in-SharePoint-Framework#establish-context) to ensure you have correctly setup your requests, 
-we'll use the onInit method in this example.
+Because the sp-pnp-js library constructs REST requests it needs to know the URL to send these requests. When operating within classic sites and pages, we can make use of the global `_spPageContextInfo` variable. Within SPFx, this is not available, or if it is, may not be correct. So we need to rely on the [context](https://dev.office.com/sharepoint/reference/spfx/sp-webpart-base/iwebpartcontext) object 
+supplied by the framework. There are [two ways](https://github.com/SharePoint/PnP-JS-Core/wiki/Using-sp-pnp-js-in-SharePoint-Framework#establish-context) to ensure you have correctly setup your requests, we'll use the `onInit` method in this example.
 
 ### Update onInit in SpPnPjsExampleWebPart.ts
 
-Open the src\webparts\spPnPjsExample\SpPnPjsExampleWebPart.ts file and add the import for the pnp root object.
+Open the **src\webparts\spPnPjsExample\SpPnPjsExampleWebPart.ts** file and add an import statement for the pnp root object:
 
 ```TypeScript
 import pnp from "sp-pnp-js";
 ```
 
-In the onInit method update the code to appear as below. We are adding the block after the super.onInit() call. We do this after the super.onInit to ensure that the framework has a chance to initialize anything 
-required and that we are setting up the library after those steps are complete.
+In the `onInit` method, update the code to appear as below. We are adding the block after the `super.onInit()` call. We do this after the `super.onInit` to ensure that the framework has a chance to initialize anything required and that we are setting up the library after those steps are completed.
 
 ```TypeScript
 /**
@@ -86,7 +79,7 @@ protected onInit(): Promise<void> {
   this._componentElement = this._createComponentElement(tagName);
   this._registerComponent(tagName);
 
-  // When web part description is changed, notify view model to update.
+  // When the web part description is changed, notify the view model to update.
   this._koDescription.subscribe((newValue: string) => {
     this._shouter.notifySubscribers(newValue, 'description');
   });
@@ -108,12 +101,9 @@ protected onInit(): Promise<void> {
 
 ## Update the ViewModel
 
-Next you will want to replace the contents of the SpPnPjsExampleViewModel.ts file with the below. We are adding an import for the pnp items, an interface to define our list item's fields, 
-some observables to track both our list of items and new item form, and methods to support getting, adding, & deleting items. We also added an ensureList method which 
-uses the sp-pnp-js lists.ensure method to always make sure we have the list. There are many ways to provision resources but this was done to demonstrate both creating a list, field, 
-and items using batching in a single method.
+Next, replace the contents of the **SpPnPjsExampleViewModel.ts** file with the code below. We are adding an import statement for the pnp items, an interface to define our list item's fields, some observables to track both our list of items and the new item form, and methods to support getting, adding, & deleting items. We also added an `ensureList` method which uses the sp-pnp-js `lists.ensure` method to always make sure we have the list (and to create it if necessary). There are many ways to provision resources, but this method was choosen to demonstrate creating a list, field, and items using batching within a single method.
 
-The takeaway is that using sp-pnp-js we write much less code to handle the requests and can focus on our business logic.
+The takeaway is that by using sp-pnp-js, we write much less code to handle requests and can focus on our business logic.
 
 ```TypeScript
 import * as ko from 'knockout';
@@ -150,12 +140,12 @@ export default class SpPnPjsExampleViewModel {
   constructor(bindings: ISpPnPjsExampleBindingContext) {
     this.description(bindings.description);
 
-    // When web part description is updated, change this view model's description.
+    // When the web part description is updated, change this view model's description.
     bindings.shouter.subscribe((value: string) => {
       this.description(value);
     }, this, 'description');
 
-    // call the load the items
+    // Load the items
     this.getItems().then(items => {
 
       this.items(items);
@@ -169,7 +159,7 @@ export default class SpPnPjsExampleViewModel {
 
     return this.ensureList().then(list => {
 
-      // here we are using the getAs operator so that our returned value will be typed
+      // Here we are using the getAs operator so that our returned value will be typed
       return list.items.select("Id", "Title", "OrderNumber").getAs<OrderListItem[]>();
     });
   }
@@ -183,20 +173,20 @@ export default class SpPnPjsExampleViewModel {
 
       this.ensureList().then(list => {
 
-        // add the new item to the SharePoint list
+        // Add the new item to the SharePoint list
         list.items.add({
           Title: this.newItemTitle(),
           OrderNumber: this.newItemNumber(),
         }).then((iar: ItemAddResult) => {
 
-          // add the new item to the display
+          // Add the new item to the display
           this.items.push({
             Id: iar.data.Id,
             OrderNumber: iar.data.OrderNumber,
             Title: iar.data.Title,
           });
 
-          // clear the form
+          // Clear the form
           this.newItemTitle("");
           this.newItemNumber("");
         });
@@ -215,30 +205,30 @@ export default class SpPnPjsExampleViewModel {
           this.items.remove(data);
         });
       }).catch((e: Error) => {
-        alert(`There was an error deleting the item ${e.message}`);
+        alert(`There was an error deleting the item: ${e.message}`);
       });
     }
   }
 
   /**
-   * Ensures the list exists and if it creates it adds some default example data
+   * Ensures the list exists. If not, it creates it and adds some default example data
    */
   private ensureList(): Promise<List> {
 
     return new Promise<List>((resolve, reject) => {
 
-      // use lists.ensure to always have the list available
+      // Use lists.ensure to always have the list available
       pnp.sp.web.lists.ensure("SPPnPJSExampleList").then((ler: ListEnsureResult) => {
 
         if (ler.created) {
 
-          // we created the list on this call so let's add a column
+          // We created the list on this call, so let's add a column
           ler.list.fields.addText("OrderNumber").then(_ => {
 
-            // and we will also add a few items so we can see some example data
-            // here we use batching
+            // And we will also add a few items so we can see some example data
+            // Here we use batching
 
-            // create a batch
+            // Create a batch
             let batch = pnp.sp.web.createBatch();
 
             ler.list.getListItemEntityTypeFullName().then(typeName => {
@@ -258,9 +248,9 @@ export default class SpPnPjsExampleViewModel {
                 OrderNumber: "75638923"
               }, typeName);
 
-              // excute the batched operations
+              // Excute the batched operations
               batch.execute().then(_ => {
-                // all of the items have been added within the batch
+                // All of the items have been added within the batch
 
                 resolve(ler.list);
 
@@ -282,7 +272,7 @@ export default class SpPnPjsExampleViewModel {
 ```
 ## Update the Template
 
-Finally we need to update the template to match the functionality we have added into the ViewModel. Copy the below code into the SpPnPjsExample.template.html file. We have added a title row, a foreach repeater 
+Finally, we need to update the template to match the functionality we have added into the ViewModel. Copy the code below into the **SpPnPjsExample.template.html** file. We have added a title row, a foreach repeater 
 for the items collection, and a form allowing you to add new items to the list.
 
 ```html
@@ -344,41 +334,37 @@ for the items collection, and a form allowing you to add new items to the list.
 ```
 ## Run the Example
 
-If you now start the sample and add then add the web part to your site's /_layouts/workbench.aspx you can see it in action.
+Start the sample and add the web part to your SharePoint hosted workbench (/_layouts/workbench.aspx) to can see it in action.
 
 ```sh
-gulp serve
+gulp serve --nobrowser
 ```
 
 ![Project as it appears on first run](../../../../images/sp-pnp-js-guide-first-run.png)
 
-You can delete existing items by clicking on the trashcan icon, or add items by putting values in both fields and clicking the add button.
+You can delete existing items by clicking on the trashcan icon, or add new items by putting values in both fields and clicking the add button.
 
 ## Next Steps
 
-The sp-pnp-js library contains a great range of functionality and extensibility. Please check out the [developer guide](https://github.com/SharePoint/PnP-JS-Core/wiki/Developer-Guide) for samples, 
-guidance, and hints on using and configuring the library.
+The sp-pnp-js library contains a great range of functionality and extensibility. Please check out the [developer guide](https://github.com/SharePoint/PnP-JS-Core/wiki/Developer-Guide) for samples, guidance, and hints on using and configuring the library.
 
 ## Production Deployment
 
-When you are ready to deploy your solution and want to build using the --ship flag you need to mark sp-pnp-js as an external in 
-the configuration. This is done by updating the SPFx config/config.js to include this line in the externals section:
+When you are ready to deploy your solution and want to build using the `--ship` flag you need to mark sp-pnp-js as an external library in the configuration. This is done by updating the SPFx **config/config.js** file to include this line in the externals section:
 
 ```
 "sp-pnp-js": "https://cdnjs.cloudflare.com/ajax/libs/sp-pnp-js/2.0.1/pnp.min.js"
 ```
 
-Here we are using the public CDN but the URL can be internal or any ___location you would like to use. Be sure to update the 
-version number in the url to match the version you want.
+In the configuration above, we are using the public CDN but the URL can be an internal path or any other ___location you would like to use. Be sure, however, to update the version number in the URL to match the version you are targeting.
 
 ## Improving the Example - Mock Data
 
-Ideally the sample will work in both the local workbench as well as the SharePoint hosted. To enable this we need to mock our ViewModel and make an update to the web part code as outlined below.
+Ideally, the sample should work within both the local workbench as well as the SharePoint hosted workbench. To enable this we need to mock our ViewModel and make an update to the web part code as outlined below.
 
 ### Mock ViewModel
 
-Add a new file named MockSpPnPjsExampleViewModel.ts along side the other web part files, then update the content to match the below. This will provide the same set of functionality but does not 
-rely on SharePoint being available and will work in the local environment.
+Add a new file named **MockSpPnPjsExampleViewModel.ts** alongside the other web part files. Update the content of this file using the code below. This will provide the same set of functionality but does not rely on SharePoint being available and will work in the local environment.
 
 ```TypeScript
 import * as ko from 'knockout';
@@ -403,20 +389,20 @@ export default class MockSpPnPjsExampleViewModel {
     constructor(bindings: ISpPnPjsExampleBindingContext) {
         this.description(bindings.description);
 
-        // When web part description is updated, change this view model's description.
+        // When the web part description is updated, change this view model's description.
         bindings.shouter.subscribe((value: string) => {
             this.description(value);
         }, this, 'description');
 
-        // call the load the items
+        // Load the items
         this.getItems().then(items => {
 
             this.items(items);
         });
     }
 
     /**
-     * Gets the items from the list
+     * Simulates getting the items from the list
      */
     private getItems(): Promise<OrderListItem[]> {
         return Promise.resolve([{
@@ -437,27 +423,27 @@ export default class MockSpPnPjsExampleViewModel {
     }
 
     /**
-     * Adds an item to the list
+     * Simulates adding an item to the list
      */
     public addItem(): void {
 
         if (this.newItemTitle() !== "" && this.newItemNumber() !== "") {
 
-            // add the new item to the display
+            // Add the new item to the display
             this.items.push({
                 Id: this.items.length,
                 OrderNumber: this.newItemNumber(),
                 Title: this.newItemTitle(),
             });
 
-            // clear the form
+            // Clear the form
             this.newItemTitle("");
             this.newItemNumber("");
         }
     }
 
     /**
-     * Deletes an item from the list
+     * Simulates deleting an item from the list
      */
     public deleteItem(data): void {
 
@@ -469,12 +455,12 @@ export default class MockSpPnPjsExampleViewModel {
 ```
 ### Update Webpart
 
-Finally we need to update the webpart to use the mock data when appropriate, to do so start by opening the SpPnPjsExampleWebPart.ts file. Start by importing the mock ViewModel web just created.
+Finally, we need to update the webpart to use the mock data when appropriate. Open the **SpPnPjsExampleWebPart.ts** file. Start by importing the mock ViewModel web just created:
 
 ```TypeScript
 import MockSpPnPjsExampleViewModel from './MockSpPnPjsExampleViewModel';
 ```
-Then locate the _registerComponent method and update it as shown below.
+Then, locate the `_registerComponent` method and update it as shown below:
 
 ```TypeScript
 private _registerComponent(tagName: string): void {
@@ -501,7 +487,7 @@ private _registerComponent(tagName: string): void {
   }
 }
 ```
-Finally type gulp serve in the console to bring up the local workbench, which now will work with the mock data. (If you already have the server running stop it using Ctrl+C and then restart it)
+Finally, type `gulp serve` in the console to bring up the local workbench, which now will work with the mock data. (If you already have the server running, stop it using Ctrl+C and then restart it):
 
 ```sh
 gulp serve
@@ -516,4 +502,4 @@ Remember you can find the full sample [here](https://github.com/SharePoint/sp-de
 
 ## Provide Feedback / Report Issues
 
-If you have any feedback or need to report as issue with sp-pnp-js please use the [issues list](https://github.com/SharePoint/PnP-JS-Core/issues) in that repo.
+If you have any feedback or need to report an issue with sp-pnp-js, please use the [issues list](https://github.com/SharePoint/PnP-JS-Core/issues) in that repo.