Chromium Code Reviews Chromium Code Reviews
Issue 18354007:
initial commit of shadow_dom pkg (Closed)
Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart| OLD | NEW |
|---|---|
| (Empty) | |
| 1 # Shadow DOM polyfill | |
| 2 | |
| 3 Shadow DOM is designed to provide encapsulation by hiding DOM subtrees under | |
|
Jennifer Messerly
2013/07/10 01:15:30
this text is from www.polymer-project.org/platform
| |
| 4 shadow roots. It provides a method of establishing and maintaining functional | |
| 5 boundaries between DOM trees and how these trees interact with each other within | |
| 6 a document, thus enabling better functional encapsulation within the DOM. See | |
| 7 the | |
| 8 [W3C specification](https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shado w/index.html) | |
| 9 for details. | |
| 10 | |
| 11 ## Getting started | |
| 12 | |
| 13 Include the polyfill in your HTML `<head>` to enable Shadow DOM: | |
|
Jennifer Messerly
2013/07/10 01:15:30
I added this section to illustrate usage.
dgrove
2013/07/10 20:04:32
Is there a way to avoid downloading the JS polyfil
Jennifer Messerly
2013/07/10 20:25:03
probably yes. It looks like https://github.com/Pol
| |
| 14 | |
| 15 ```html | |
| 16 <script src="packages/shadow_dom/shadow_dom.debug.js"></script> | |
| 17 ``` | |
| 18 | |
| 19 You can also use a minified version for deployment: | |
| 20 | |
| 21 ```html | |
| 22 <script src="packages/shadow_dom/shadow_dom.min.js"></script> | |
| 23 ``` | |
| 24 | |
| 25 Because it does extensive DOM patching, it should be included before other | |
|
Siggi Cherem (dart-lang)
2013/07/10 15:45:08
suggestion: make bold **before** or **before other
Jennifer Messerly
2013/07/10 20:25:03
Done.
| |
| 26 script tags. | |
| 27 | |
| 28 ## Useful Resources | |
|
Jennifer Messerly
2013/07/10 01:15:30
from www.polymer-project.org/platform/shadow-dom.h
| |
| 29 | |
| 30 - [What the Heck is Shadow DOM?](http://glazkov.com/2011/01/14/what-the-heck-is- shadow-dom/) | |
| 31 - [Web Components Explained - Shadow DOM](https://dvcs.w3.org/hg/webcomponents/r aw-file/57f8cfc4a7dc/explainer/index.html#shadow-dom-section) | |
| 32 - [HTML5Rocks - Shadow DOM 101](http://www.html5rocks.com/tutorials/webcomponent s/shadowdom/) | |
| 33 - [HTML5Rocks - Shadow DOM 201: CSS and Styling](http://www.html5rocks.com/tutor ials/webcomponents/shadowdom-201/) | |
| 34 - [HTML5Rocks - Shadow DOM 301: Advanced Concepts & DOM APIs](http://www.html5ro cks.com/tutorials/webcomponents/shadowdom-301/) | |
| 35 | |
| 36 ## Learn the tech | |
| 37 | |
| 38 ### Basic usage | |
| 39 | |
| 40 ```dart | |
|
Jennifer Messerly
2013/07/10 01:15:30
fixed this to be Dart
| |
| 41 var el = new DivElement(); | |
| 42 var shadow = el.createShadowRoot(); | |
| 43 shadow.innerHtml = '<content select="h1"></content>'; | |
| 44 ``` | |
| 45 | |
| 46 ### Shadow DOM subtrees | |
| 47 | |
| 48 Shadow DOM allows a single node to express three subtrees: _light DOM_, _shadow DOM_, and _composed DOM_. | |
| 49 | |
| 50 A component user supplies the light DOM; the node has a (hidden) shadow DOM; and the composed DOM is what is actually rendered in the browser. At render time, t he light DOM is merged with the shadow DOM to produce the composed DOM. For exam ple: | |
| 51 | |
| 52 **Light DOM** | |
| 53 | |
| 54 ```html | |
| 55 <my-custom-element> | |
| 56 <!-- everything in here is my-custom-element's light DOM --> | |
| 57 <q>Hello World</q> | |
| 58 </my-custom-element> | |
| 59 ``` | |
| 60 | |
| 61 **Shadow DOM** | |
| 62 | |
| 63 ```html | |
| 64 <!-- shadow-root is attached to my-custom-element, but is not a child --> | |
| 65 <shadow-root> | |
| 66 <!-- everything in here is my-custom-element's shadow DOM --> | |
| 67 <span>People say: <content></content></span> | |
| 68 </shadow-root> | |
| 69 ``` | |
| 70 | |
| 71 **Composed (rendered) DOM** | |
| 72 | |
| 73 ```html | |
| 74 <!-- rendered DOM --> | |
| 75 <my-custom-element> | |
| 76 <span>People say: <q>Hello World</q></span> | |
| 77 </my-custom-element> | |
| 78 ``` | |
| 79 | |
| 80 The following is true about this example: | |
| 81 | |
| 82 * The light DOM that belongs to `<my-custom-element>` is visible to the user as its normal subtree. It can expressed by `.childNodes`, `.nodes`, `.innerHtml` or any other property or method that gives you information about a node's subtree. | |
| 83 * Nodes in light DOM or shadow DOM express parent and sibling relationships that match their respective tree structures; the relationships that exist in the ren dered tree are not expressed anywhere in DOM. | |
| 84 | |
| 85 So, while in the final rendered tree `<span>` is a child of `<my-custom-element> ` and the parent of `<q>`, interrogating those nodes will tell you that the `<sp an>` is a child of `<shadow-root>` and `<q>` is a child of `<my-custom-element>` , and that those two nodes are unrelated. | |
| 86 | |
| 87 In this way, the user can manipulate light DOM or shadow DOM directly as regular DOM subtrees, and let the system take care of keeping the render tree synchroni zed. | |
| 88 | |
| 89 ## Polyfill details | |
| 90 | |
| 91 You can read more about how the polyfill is implemented in JavaScript here: | |
| 92 <https://github.com/polymer/ShadowDOM#polyfill-details>. | |
| 93 | |
| 94 ## Getting the source code | |
|
Jennifer Messerly
2013/07/10 01:15:30
this info indicates how to get the code and build
| |
| 95 | |
| 96 This package is built from: | |
| 97 <https://github.com/dart-lang/ShadowDOM/tree/conditional_shadowdom> | |
| 98 | |
| 99 You'll need [node.js](http://nodejs.org) to rebuild the JS file. Use `npm instal l` to | |
| 100 get dependencies and `grunt` to build. | |
| OLD | NEW |
