Add docs on iframe resizing and best practices. (#3)

* Add docs on iframe resizing and best practices.

* Force scrollbar to never display in the iframe.

* Update _samples.md

* Include domain in iframe src

Co-Authored-By: Jonah Schulte <[email protected]>

* Match origin to updated iframe src

Co-Authored-By: Jonah Schulte <[email protected]>

* Use cms.dealer.com domain instead

Co-Authored-By: Jonah Schulte <[email protected]>

* Merge Best Practices and Technical Requirements. Tweak iframe resizing documentation for clarity. Update code to be a little more generic.

Co-authored-by: Jonah Schulte <[email protected]>

Author: uberska

source/includes/_requirements.md

@@ -46,13 +46,18 @@ Your code should be minimal and perform only actions necessary to bootstrap your
 	// Your code here
 })(window.DDC.API);
 ```
-* Always ecapsulate your code in an immediately executing function expression to avoid polluting the global namespace. See sidebar for example of such a function.
+* **Avoid Global Scope Pollution** - Always ecapsulate your code in an immediately executing function expression to avoid polluting the global namespace. See sidebar for example of such a function.
 
-* Your bootstrap script and any other integration code or assets should be located on a highly available content delivery network and must work over an HTTPS connection.
+* **Use a CDN** - Your bootstrap script and any other integration code or assets should be located on a highly available content delivery network and must work over an HTTPS connection.
 
-* All code should be minified and served using gzip or better compression.
+* **Minification and Compression** - All code should be minified and served using gzip or better compression.
 
-* Integrations should avoid loading excessive imagery, fonts and scripts. While some are often necessary, less is more and avoiding loading duplicate scripts will help reduce load time for your integration as well as improve overall website speed.
+* **Minimize Asset Size** - Integrations should avoid loading excessive imagery, fonts and scripts. While some are often necessary, less is more and avoiding loading duplicate scripts will help reduce load time for your integration as well as improve overall website speed.
 
-* Please refrain from including large libraries such as jQuery or React, as both are already available on all pages of all of our sites.
+* **Avoid Duplicate Code** - Please refrain from including large libraries such as jQuery or React, as both are already available on all pages of all of our sites. Avoid polyfilling items that DDC already polyfills.
 
+* **Browser Support** - Your code must support IE11, Edge, Firefox, Chrome, Safari, and iOS Safari.
+
+* **Minimize Files** - Serve content from as few files as possible to allow for optimal downloads.
+
+* **Minimize Domains** - Serve content from as few domains as possible to reduce the number of https connections the browser must make.

source/includes/_samples.md

@@ -0,0 +1,83 @@
+# Sample Code
+
+The sample code here is provided as a starting point for how to accomplish tasks that are related to integrations but that may not fit squarely in the responsibility of the Integration API. Code may need to be modified to fit your integration's use case.
+
+## Resizing an `iframe` Based on Content Changes
+
+> iframe Code:
+
+```javascript
+document.body.style.overflow = 'hidden';
+
+function sendResizeMessage() {
+  window.parent.postMessage({
+    type: 'IFRAME_HEIGHT_RESIZE',
+    target: 'growing-iframe',
+    frameHeight: document.body.offsetHeight + 10 /* a little extra for good measure */
+  }, '*');
+}
+
+if (window.ResizeObserver) {
+  var heightObserver = new ResizeObserver(function() {
+    sendResizeMessage();
+  });
+  heightObserver.observe(document.body);
+} else {
+  // IE 11
+  setInterval(
+    sendResizeMessage,
+    500 /* ms */
+  );
+}
+```
+
+> Integration Code:
+
+```javascript
+(function (WIAPI) {
+  API = new WIAPI();
+
+  API.insert('content', function (elem, meta) {
+    var iframeElem = document.createElement('iframe');
+    iframeElem.src = 'https://www.yourdomain.com/path-to-iframe.htm';
+    iframeElem.classList.add('my-integration-name-iframe');
+    API.append(elem, iframeElem);
+  });
+
+  function setIframeHeight(e) {
+    if (e.origin !== 'https://www.yourdomain.com') {
+      // You should ALWAYS verify the origin matches the third party domain
+      // the iframe is loaded from. For more information, see:
+      // https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#Security_concerns
+      return;
+    }
+
+    if (e.data.type === 'IFRAME_HEIGHT_RESIZE' && e.data.frameHeight && e.data.target) {
+      var iframes = document.getElementsByClassName(e.data.target);
+      if (iframes.length === 1) {
+        iframes[0].style.height = e.data.frameHeight + 'px';
+      }
+    }
+  }
+
+  window.addEventListener('message', setIframeHeight, false);
+})(window.DDC.API);
+```
+
+An integration may want to insert an iframe that resizes as its contents change. One possible way to accomplish this is for the iframe and the integration to work together as shown in the sample code from the pane on the right side of this page. You can see the sample code running [here](https://webapitestddc.cms.dealer.com/growing-iframe-example.htm).
+
+### iframe Responsibilities:
+
+* **Determine when content dimensions change** - One way to do this is using [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver). `ResizeObserver` is not supported in IE11, so one possible solution is to fallback to polling. Polling is not ideal, but it will work for this small percentage of our traffic.
+* **Communicate the new dimension to the outer page** - iframes can communicate with the parent page using [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
+* **Ensure a scrollbar never shows up within the iframe** - Styling may be used to ensure a scrollbar never appears in the iframe.
+
+### Integration Responsibilities(on the outer page):
+
+* **Insert the iframe into the page** - You can use the API methods to insert an iframe into a location.
+* **Listen for resize messages and resize the iframe**
+
+### Considerations
+
+* If you use `postMessage`, ensure that you check the event's origin to alleviate [security concerns](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#Security_concerns).
+* The integration resizing code supports multiple iframes from the same vendor. You may need to modify the code to target your iframes differently.

source/index.html.md

@@ -16,6 +16,7 @@ includes:
   - utilities
   - jwt
   - debugging
+  - samples
 
 search: true
 ---