Add guidance on subscribing to query string updates (SharePoint#5244)

* Add guidance on subscribing to query string updates

There is a use-case where web parts need to listen to query string
changes but the SharePoint Framework provides no guarantees that a
web part will re-render in the event of a query string change whilst on
the same page. This document serves as a guide to writing a Web Part
that can respond to query string changes.

* undo toc formatting

Author: benkaiser

docs/spfx/web-parts/guidance/intercepting-query-changes-in-webparts.md

@@ -0,0 +1,59 @@
+---
+title: Intercepting Query String Changes in Web Parts
+description: Building web parts that respond to query string changes.
+ms.author: bekaise
+ms.date: 01/28/2020
+ms.prod: sharepoint
+localization_priority: Normal
+---
+
+# Intercepting Query String Changes in Web Parts
+
+When building a web part that needs to take into account query string changes you can use the web API `window.___location.search` to read the query string. However if the user proceeds to click a link on the page that contains the same path as the current URL and only the query string changes, the URL in the address bar will be updated but the page will not re-render (due to performance reasons). This document is aimed at showing how you can take advantage of other web APIs to track query string changes and respond to them in your web part.
+
+First let's assume you have a basic webpart class that renders the current query string.
+
+```typescript
+export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
+  public render(): void {
+    this.domElement.innerHTML = window.___location.query;
+  }
+}
+```
+
+We can use the following changes to trigger our web part to re-render in the event of a query string update:
+
+```typescript
+export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
+  public onInit(): Promise<void> {
+    (function (history) {
+      var ___pushState = history.___pushState;
+      history.___pushState = function (state, key, path) {
+          this._onUrlChange();
+          return ___pushState.apply(history, arguments);
+      };
+    })(window.history);
+
+    window.addEventListener('popstate', function (e) {
+      this._onUrlChange();
+    });
+
+    return Promise.resolve();
+  }
+
+  public render(): void {
+    this.domElement.innerHTML = window.___location.query;
+  }
+
+  private _onUrlChange(): void {
+    // any logic you might want to trigger when the query string updates
+    // e.g. fetching data
+    this.render();
+  }
+}
+```
+
+There are two parts to what we are doing in onInit:
+1. Ensuring that whenever ___pushState is called by other javascript we trigger our `_onUrlChange` method.
+2. Ensuring that whenever the browser fires a 'popstate' event (e.g. user pressing the browser back button) we trigger our `_onUrlChange` method.
+

docs/toc.yml

@@ -141,6 +141,8 @@
       href: spfx/hyperlinking.md
     - name: Building Office add-ins
       href: spfx/office-addins-create.md
+    - name: Intercepting query string changes in web parts
+      href: spfx/web-parts/guidance/intercepting-query-changes-in-webparts.md
   - name: External libraries
     items:
     - name: Add external libraries