pkg/shadow_dom/README.md - Issue 158083002: introduce web_components pkg for consolidated polyfills

Side by Side Diff: pkg/shadow_dom/README.md

Issue 158083002: introduce web_components pkg for consolidated polyfills (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart

Patch Set: Created 6 years, 10 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch | Annotate | Revision Log

OLD	NEW
	(Empty)
1 # Shadow DOM polyfill

2

3 Shadow DOM is designed to provide encapsulation by hiding DOM subtrees under

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:

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

26 script tags.

27

28 ## Useful resources

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

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

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

« pkg/polymer/test/noscript_test.dart ('K') | « pkg/shadow_dom/PATENTS ('k') | pkg/shadow_dom/REVISIONS » ('j') | pkg/third_party/html5lib/lib/dom.dart » ('J')