V3.2 Documentation Updates

Clean up and refactor samples for clarity.

AUTHORS

@@ -5,3 +5,9 @@ Patrick Rodgers, Microsoft (patrick-rodgers)
 Ademosu Ayodele (aaademosu)
 Tomi Tavela (tavikukko)
 Chris Kent (thechriskent)
+Waldek Mastykarzk, Microsoft (waldekmastykarz)
+jesse (barkdoll)
+Superior (SuperioOne)
+Robert Lindström (robert-lindstrom)
+Marc D Anderson (sympmarc)
+(lch-dbrown)

CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 3.2.0 - 2022-April-08
+
+### Fixed
+
+- node:
+  - Fix for CommonJS imports with ESM modules.
+
+- sp:
+  - Fix issue with sendEmail utility.
+  - Bug fixes for getAllChildrenAsOrderedTree in Taxonomy.
+  - Update for issues with stale requestdigest.
+  - Bug fix for client-side pages for home page so that title is read from the json blob.
+  - Remove user-agent header for throttling as no longer used.
+  - Bug fix for renderListDataAsStream method
+
+- graph:
+  - Added getById method to Sites.
+  - Added transitiveMemberOf method to User.
+  - Added installedApps method to a Team.
+
+- docs:
+  - Various documentation copy/paste and typo fixes.
+  - Updates for getting-started guidance for imports of both @pnp/sp and @pnp/graph in SPFx.
+  - Updates to remove documentation showing batching adding files; includes new tag on all areas of library that are not supported for batching.
+  - New documentation for Graph to get SharePoint sites.
+  - New doucmentation for updating a BCS field in SharePoint.
+  - Added Graph memberOf and transitiveMemberOf properties.
+  - Updated docs on the Web() method.
+
 ## 3.1.0 - 2022-March-11
 
 - sp:
@@ -17,15 +46,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## 3.0.3 - 2022-March-3
 
-### Fixed
-
 - sp:
   - Issues preventing search queries from running. #2124
 
 ## 3.0.2 - 2022-Feb-22
 
-### Fixed
-
 - sp:
   - Issue in SPFx behavior with improperly using current web's request digest for non-current web calls #2102
 
@@ -35,8 +60,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## 3.0.1 - 2022-Feb-15
 
-### Fixed
-
 - sp:
   - Fixed root property initializers #2082
 

docs/concepts/authentication.md

@@ -48,7 +48,7 @@ import { SPFx, spfi } from "@pnp/sp";
 import "@pnp/sp/webs";
 
 // within a webpart, application customizer, or adaptive card extension where the context object is available
-const sp = spfi().using(SPFx(this.context));
+const sp = spfi(...);
 
 const webData = await sp.web();
 ```

docs/concepts/batching-caching.md

@@ -3,12 +3,12 @@
 When optimizing for performance you can combine [batching](batching.md) and [caching](../queryable/behaviors.md#caching) to reduce the overall number of requests. On the first request any cachable data is stored as expected once the request completes. On subsequent requests if data is found in the cache it is returned immediately and that request is not added to the batch, in fact the batch will never register the request. This can work across many requests such that some returned cached data and others do not - the non-cached requests will be added to and processed by the batch as expected.
 
 ```TypeScript
-import { spfi, SPFx } from "@pnp/sp";
+import { spfi } from "@pnp/sp";
 import "@pnp/sp/webs";
 import "@pnp/sp/lists";
 import { Caching } from "@pnp/queryable";
 
-const sp = spfi("https://318studios.sharepoint.com/sites/dev").using(SPFx(this.context));
+const sp = spfi(...);
 
 const [batchedSP, execute] = await sp.batched();
 
@@ -36,12 +36,12 @@ await execute2();
 In this second example we include an update to the web's title. Because non-get requests are never cached the update code will always run, but the results from the two get requests will resolve from the cache prior to being added to the batch.
 
 ```TypeScript
-import { spfi, SPFx } from "@pnp/sp";
+import { spfi } from "@pnp/sp";
 import "@pnp/sp/webs";
 import "@pnp/sp/lists";
 import { Caching } from "@pnp/queryable";
 
-const sp = spfi("https://318studios.sharepoint.com/sites/dev").using(SPFx(this.context));
+const sp = spfi(...);
 
 const [batchedSP, execute] = await sp.batched();
 

docs/concepts/batching.md

@@ -5,12 +5,12 @@ Where possible batching can significantly increase application performance by co
 ## SP Example
 
 ```TypeScript
-import { spfi, SPFx } from "@pnp/sp";
+import { spfi } from "@pnp/sp";
 import "@pnp/sp/webs";
 import "@pnp/sp/lists";
 import "@pnp/sp/batching";
 
-const sp = spfi().using(SPFx(this.context));
+const sp = spfi(...);
 
 const [batchedSP, execute] = sp.batched();
 
@@ -35,12 +35,12 @@ for(let i = 0; i < res.length; i++) {
 ### Using a batched web
 
 ```TypeScript
-import { spfi, SPFx } from "@pnp/sp";
+import { spfi } from "@pnp/sp";
 import "@pnp/sp/webs";
 import "@pnp/sp/lists";
 import "@pnp/sp/batching";
 
-const sp = spfi().using(SPFx(this.context));
+const sp = spfi(...);
 
 const [batchedWeb, execute] = sp.web.batched();
 

docs/contributing/extending-the-library.md

@@ -38,10 +38,11 @@ And the matching graph type:
 The general idea of a factory function is that it takes two parameters. The first is either a string or Queryable derivative which forms base for the new object. The second is the next part of the url. In some cases (like the webs property example above) you will note there is no second parameter. Some classes are decorated with defaultPath, which automatically fills the second param. Don't worry too much right now about the deep internals of the library, let's instead focus on some concrete examples.
 
 ```TypeScript
+import { SPFx } from "@pnp/sp";
 import { Web } from "@pnp/sp/webs";
 
 // create a web from an absolute url
-const web = Web("https://tenant.sharepoint.com");
+const web = Web("https://tenant.sharepoint.com").using(SPFx(this.context));
 
 // as an example, create a new web using the first as a base
 // targets: https://tenant.sharepoint.com/sites/dev

docs/getting-started.md

@@ -82,6 +82,8 @@ Because SharePoint Framework provides a local context to each component we need
 
 Depending on how you architect your solution establishing context is done where you want to make calls to the API. The examples demonstrate doing so in the onInit method as a local variable but this could also be done to a private variable or passed into a service.
 
+>Note if you are going to use both the @pnp/sp and @pnp/graph packages in SPFx you will need to alias the SPFx behavior import, please see the [section](#using-both-pnpsp-and-pnpgraph-in-spfx) below for more details.
+
 ### Using @pnp/sp `spfi` factory interface in SPFx
 
 ```TypeScript
@@ -92,8 +94,8 @@ import { spfi, SPFx } from "@pnp/sp";
 protected async onInit(): Promise<void> {
 
     await super.onInit();
-    const sp = spfi().using(SPFx(this.context));
-
+    const sp = spfi().using(spSPFx(this.context));
+    
 }
 
 // ...
@@ -118,6 +120,27 @@ protected async onInit(): Promise<void> {
 
 ```
 
+### Using both @pnp/sp and @pnp/graph in SPFx
+
+```TypeScript
+
+import { spfi, SPFx as spSPFx } from "@pnp/sp";
+import { graphfi, SPFx as graphSPFx} from "@pnp/graph";
+
+// ...
+
+protected async onInit(): Promise<void> {
+
+    await super.onInit();
+    const sp = spfi().using(spSPFx(this.context));
+    const graph = graphfi().using(graphSPFx(this.context));
+
+}
+
+// ...
+
+```
+
 ### Establish context within an SPFx service
 
 Because you do not have full access to the context object within a service you need to setup things a little differently. If you do not need AAD tokens you can leave that part out and specify just the pageContext (Option 2).
@@ -154,8 +177,6 @@ export class SampleService {
 
         //Option 2 - without AADTokenProvider
         this._sp = spfi().using(SPFx({ pageContext }));
-
-        });
     }
 
     public getLists(): Promise<any[]> {
@@ -172,7 +193,7 @@ export class SampleService {
 
 To call the SharePoint APIs via MSAL you are required to use certificate authentication with your application. Fully covering certificates is outside the scope of these docs, but the following commands were used with openssl to create testing certs for the sample code below.
 
-```
+```cmd
 mkdir \temp
 cd \temp
 openssl req -x509 -newkey rsa:2048 -keyout keytmp.pem -out cert.pem -days 365 -passout pass:HereIsMySuperPass -subj '/C=US/ST=Washington/L=Seattle'
@@ -269,6 +290,7 @@ You must install TypeScript @next or you will get errors using node12 module res
 The tsconfig file for your project should have the `"module": "CommonJS"` and `"moduleResolution": "node12",` settings in addition to whatever else you need.
 
 _tsconfig.json_
+
 ```JSON
 {
     "compilerOptions": {
@@ -280,6 +302,7 @@ _tsconfig.json_
 You must then import the esm dependencies using the async import pattern. This works as expected with our selective imports, and vscode will pick up the intellisense as expected.
 
 _index.ts_
+
 ```TypeScript
 import { settings } from "./settings.js";
 
@@ -312,7 +335,6 @@ Finally, when launching node you need to include the `` flag with a setting of '
 
 > Read more in the releated [TypeScript Issue](https://github.com/microsoft/TypeScript/issues/43329), [TS pull request Adding the functionality](https://github.com/microsoft/TypeScript/pull/45884), and the [TS Docs](https://www.typescriptlang.org/tsconfig#moduleResolution).
 
-
 ## Single Page Application Context
 
 In some cases you may be working in a client-side application that doesn't have context to the SharePoint site. In that case you will need to utilize the MSAL Client, you can get the details on creating that connection in this [article](./concepts/authentication.md#MSAL-in-Browser).
@@ -341,7 +363,7 @@ import { AssignFrom } from "@pnp/core";
 import "@pnp/sp/webs";
 
 //Connection to the current context's Web
-const sp = spfi().using(SPFx(this.context));
+const sp = spfi(...);
 
 // Option 1: Create a new instance of Queryable
 const spWebB = spfi({Other Web URL}).using(SPDefault(this.context));

docs/graph/behaviors.md

@@ -106,11 +106,11 @@ await graph.users();
 This behavior is designed to work closely with SPFx. The only parameter is the current SPFx Context. `SPFx` is a composed behavior including DefaultHeaders, DefaultInit, BrowserFetchWithRetry, and DefaultParse. It also replaces any authentication present with a method to get a token from the SPFx aadTokenProviderFactory.
 
 ```TypeScript
-import { graphfi, SPFx } from "@pnp/graph";
+import { graphfi } from "@pnp/graph";
 import "@pnp/graph/users";
 
 // this.context represents the context object within an SPFx webpart, application customizer, or ACE.
-const graph = graphfi().using(SPFx(this.context));
+const graph = graphfi(...);
 
 await graph.users();
 ```
@@ -128,7 +128,7 @@ const graph = graphfi().using(graphSPFx(this.context));
 If you want to use a different form of authentication you can apply that behavior after `SPFx` to override it. In this case we are using the [client MSAL authentication](../msaljsclient).
 
 ```TypeScript
-import { graphfi, SPFx } from "@pnp/graph";
+import { graphfi } from "@pnp/graph";
 import { MSAL } from "@pnp/msaljsclient";
 import "@pnp/graph/users";