From 1fa4948bb1bd2e137b2d32ea7fa10e95ea5b8de4 Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Thu, 2 Apr 2020 14:26:40 -0700
Subject: [PATCH] Add example of overriding `suppressTemplateNotifications` via
 `notify-dom-change`.

---
 CHANGELOG.md | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 42d8972b3a..5d4f589ce1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -117,7 +117,41 @@ This update to Polymer includes some new [global settings](https://polymer-libra
 
   **What does it do?** This setting causes `<dom-if>` and `<dom-repeat>` not to dispatch `dom-change` events when their rendered content is updated. If you're using lots of `<dom-if>` and `<dom-repeat>` but not listening for these events, this setting lets you disable them and their associated propagation work.
 
-  You can override the global setting on an individual `<dom-if>` or `<dom-repeat>` by setting its `notify-dom-change` boolean attribute.
+  You can override the global setting for an individual `<dom-if>` or `<dom-repeat>` by setting its `notify-dom-change` boolean attribute:
+
+  ```js
+  import {PolymerElement, html} from '@polymer/polymer/polymer-element.js';
+
+  class SomeElement extends PolymerElement {
+    static get properties() {
+      return {
+        visible: {type: Boolean, value: false},
+      };
+    }
+
+    static get template() {
+      return html`
+        <button on-click="_toggle">Toggle</button>
+        <!-- Set notify-dom-change to enable dom-change events for this particular <dom-if>. -->
+        <dom-if if="[[visible]]" notify-dom-change on-dom-change="_onDomChange">
+          <template>
+            Hello!
+          </template>
+        </dom-if>
+      `;
+    }
+
+    _toggle() {
+      this.visible = !this.visible;
+    }
+
+    _onDomChange(e) {
+      console.log("Received 'dom-change' event.");
+    }
+  }
+
+  customElements.define('some-element', SomeElement);
+  ```
 
   **Should I use it?** This setting is generally recommended.