From 4708477f5a733e037c95a7b51b451e708b377f1f Mon Sep 17 00:00:00 2001
From: christoth <crstoth@gmail.com>
Date: Thu, 14 Apr 2016 10:29:55 -0400
Subject: [PATCH] webview: add CSS styling notes

Create a new section for CSS and add notes to avoid hiding the webview via hidden or display:none; and provide a recommended approach.
---
 docs/api/web-view-tag.md | 35 ++++++++++++++++++++++++++++++-----
 1 file changed, 30 insertions(+), 5 deletions(-)

diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md
index 8df8d29347..cee06dfa35 100644
--- a/docs/api/web-view-tag.md
+++ b/docs/api/web-view-tag.md
@@ -20,11 +20,6 @@ control the appearance of the `webview` container:
 ```html
 <webview id="foo" src="https://www.github.com/" style="display:inline-flex; width:640px; height:480px"></webview>
 ```
-Please note that the `webview` tag's style uses `display:flex;` internally to 
-ensure the child `object` element fills the full height and width of its `webview` 
-container when used with traditional and flexbox layouts (since v0.36.11). Please 
-do not overwrite the default `display:flex;` CSS property, unless specifying 
-`display:inline-flex;` for inline layout.
 
 If you want to control the guest content in any way, you can write JavaScript
 that listens for `webview` events and responds to those events using the
@@ -50,6 +45,36 @@ and displays a "loading..." message during the load time:
 </script>
 ```
 
+## CSS Styling Notes
+
+Please note that the `webview` tag's style uses `display:flex;` internally to 
+ensure the child `object` element fills the full height and width of its `webview` 
+container when used with traditional and flexbox layouts (since v0.36.11). Please 
+do not overwrite the default `display:flex;` CSS property, unless specifying 
+`display:inline-flex;` for inline layout.
+
+`webview` has issues being hidden using the `hidden` attribute or using `display: none;`. 
+It can cause unusual rendering behaviour within its child `browserplugin` object 
+and the web page is reloaded, when the `webview` is un-hidden, as opposed to just 
+becoming visible again. The recommended approach is to hide the `webview` using 
+CSS by zeroing the `width` & `height` and allowing the element to shrink to the 0px 
+dimensions via `flex`.
+
+```html
+<style>
+  webview {
+    display:inline-flex;
+    width:640px;
+    height:480px;
+  }
+  webview.hide {
+    flex: 0 1;
+    width: 0px;
+    height: 0px; 
+  }
+</style>
+```
+
 ## Tag Attributes
 
 The `webview` tag has the following attributes: