Web Components

This package has the polyfills for Shadow DOM, Custom Elements, and HTML Imports.

These features exist in dart:html, for example Element.createShadowRoot and Document.register. However those APIs are not supported on all browsers yet unless you load the polyfills, as indicated below.

Getting started

Include the polyfills in your HTML <head> to enable Shadow DOM:

<script src="packages/web_components/webcomponents.min.js"></script>
<script src="packages/web_components/dart_support.js"></script>

You can also use an unminified version for development:

<script src="packages/web_components/webcomponents.js"></script>
<script src="packages/web_components/dart_support.js"></script>

Because the Shadow DOM polyfill does extensive DOM patching, webcomponents.js should be included before other script tags. Be sure to include dart_support.js too, it is required for the Shadow DOM polyfill to work with dart2js.

Custom Elements

Custom Elements let authors define their own elements. Authors associate JavaScript or Dart code with custom tag names, and then use those custom tag names as they would any standard tag.

For example, after registering a special kind of button called super-button, use the super button just like this:

<super-button></super-button>

Custom elements are still elements. We can create, use, manipulate, and compose them just as easily as any standard <div> or <span> today.

See the Polymer Custom Elements page for more information.

Shadow DOM

Shadow DOM is designed to provide encapsulation by hiding DOM subtrees under shadow roots. It provides a method of establishing and maintaining functional boundaries between DOM trees and how these trees interact with each other within a document, thus enabling better functional encapsulation within the DOM.

See the Polymer Shadow DOM page for more information.

Hacking on this package

The webcomponents.* files in this package are developed here. Follow the instructions there for how to build a new release and then copy the files into this package.

Libraries

web_components
web_components.build.common
web_components.build.html_import_recorder_inliner
web_components.build.import_crawler
web_components.build.import_inliner
web_components.build.messages
Contains all error and warning messages produced by web_components.
web_components.build.mirrors_remover
web_components.build.script_compactor
web_components.build.test_compatability.dart
Some Transformers to maintain compatibility with the new test package, since it doesn't use normal dart script tags in html. We get around this by using two transformers: [...]
web_components.build.web_components
Transformer used for pub serve and pub build
web_components.custom_element_proxy
web_components.html_import_annotation
web_components.init
web_components.interop
Provides support for associating a Dart type for Javascript Custom Elements. This will not work unless dart_support.js is loaded.
web_components.polyfill
Dart APIs for interacting with the JavaScript Custom Elements polyfill.
web_components.transformer
Transformer used for pub serve and pub build