link to simple-overlay example (#190)

* link to simple-overlay example * explain limitation of focus wrapping
PolymerElements · Jun 27, 2016 · 0b8da8d · 0b8da8d
1 parent dde758a
commit 0b8da8d
Showing 1 changed file with 10 additions and 2 deletions.
diff --git a/iron-overlay-behavior.html b/iron-overlay-behavior.html
@@ -22,9 +22,12 @@
 on top of other content. It includes an optional backdrop, and can be used to implement a variety
 of UI controls including dialogs and drop downs. Multiple overlays may be displayed at once.
 
+See the [demo source code](https://github.com/PolymerElements/iron-overlay-behavior/blob/master/demo/simple-overlay.html)
+for an example.
+
 ### Closing and canceling
 
-A dialog may be hidden by closing or canceling. The difference between close and cancel is user
+An overlay may be hidden by closing or canceling. The difference between close and cancel is user
 intent. Closing generally implies that the user acknowledged the content on the overlay. By default,
 it will cancel whenever the user taps outside it or presses the escape key. This behavior is
 configurable with the `no-cancel-on-esc-key` and the `no-cancel-on-outside-click` properties.
@@ -43,6 +46,10 @@
 appended to `<body>` and is of type `<iron-overlay-backdrop>`. See its doc page for styling
 options.
 
+In addition, `with-backdrop` will wrap the focus within the content in the light DOM.
+Override the [`_focusableNodes` getter](#Polymer.IronOverlayBehavior:property-_focusableNodes)
+to achieve a different behavior.
+
 ### Limitations
 
 The element is styled to appear on top of other content by setting its `z-index` property. You
@@ -78,7 +85,8 @@
       },
 
       /**
-       * Set to true to display a backdrop behind the overlay.
+       * Set to true to display a backdrop behind the overlay. It traps the focus
+       * within the light DOM of the overlay.
        */
       withBackdrop: {
         observer: '_withBackdropChanged',