web_components 0.4.0

Web Components

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

These features exist in dart:html, for example Element.reateShadowRoot 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/platform.js"></script>
<script src="packages/web_components/dart_support.js"></script>

You can also use an unminfied version for development:

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

Because the Shadow DOM polyfill does extensive DOM patching, platform.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

To rebuild platform.js:

# Make a directory like ~/src/polymer
mkdir ~/src/polymer
cd ~/src/polymer
git clone https://github.com/polymer/tools

# Sync polymer repositories
./tools/bin/pull-all-polymer.sh

# If you don't have "npm", get it here: http://nodejs.org
cd platform-dev
npm install
grunt minify audit
cd build

# Copy the build output to your Dart source tree
cp build.log platform* ~/dart/dart/pkg/web_components/lib

changelog

This file contains highlights of what changes on each version of this package.

Pub version 0.4.0

  • Adds registerDartType and updates to platform 0.3.3-29065bc (re-applies the changes in 0.3.5).

Pub version 0.3.5+1

  • Reverts back to what we had in 0.3.4. (The platform.js updates in 0.3.5 had breaking changes so we are republishing it in 0.4.0)

Pub version 0.3.5

  • Added registerDartType to register a Dart API for a custom-element written in Javascript.
  • Updated to platform 0.3.3-29065bc

Pub version 0.3.4

  • Updated to platform 0.2.4 (see lib/build.log for details)

1. Depend on it

Add this to your package's pubspec.yaml file:

dependencies:
  web_components: ">=0.4.0 <0.5.0"

If your package is an application package you should use any as the version constraint.

2. Install it

If you're using the Dart Editor, choose:

Menu > Tools > Pub Install

Or if you want to install from the command line, run:

$ pub install

3. Import it

Now in your Dart code, you can use:

import 'package:web_components/interop.dart';
import 'package:web_components/polyfill.dart';

About

Polyfills for Shadow DOM, Custom Elements, and HTML Imports. Custom Elements let authors define their own elements. Authors associate code with custom tag names, and then use those custom tag names as they would any standard tag. Shadow DOM is designed to provide encapsulation for custom elements, by hiding DOM subtrees under shadow roots. HTML Imports let authors bundle code and HTML as if they were libraries.

Author

Email web-ui-dev@dartlang.org Polymer.dart Authors

Homepage

www.dartlang.org/polymer-dart/

Documentation

www.dartdocs.org/documentation/web_compo...

Uploader

jmesserly@google.com
sigmund@google.com
terry@google.com

Share