web_components 0.11.1+1

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.

0.11.1+1

  • fixes unknown HTML elements if using interop_support.js

0.11.1

  • Added initWebComponents function which performs html import aware initialization of an application. This is done by crawling all imported documents for dart script tags and initializing them. Any applications using this package should switch to this method instead of calling run from the initialize package directly.
  • You may also now just export package:web_components/init.dart to initialize your app, and then stick your startup code inside a method marked with @initMethod, for instance:

    library my_app;
    export 'package:web_components/init.dart';
    
    @initMethod
    void startup() {
      // custom app code here.
    }
    

0.11.0

  • Add bindingStartDelimiters option to the ImportInlinerTransformer. Any urls which contain any of the supplied delimiters before the first / will be left alone since they can't be reasoned about. If you want these urls to be treated as relative to the current path you should add a ./ in front.
  • The ScriptCompactorTransformer now names its bootstrap file based on the entry point html file, instead of the original dart file. This is ensure it is the original package.

0.10.5+3

0.10.5+2

  • Append html imports in front of the dart script tag, if one exists in document.head.

0.10.5+1

  • Fix @HtmlImport with relative paths from within folders in deployment mode.

0.10.5

  • Update ImportCrawler with support for pre-parsed initial documents. This allows it to work better with other transformers in the same step (you can pass in a modified document).

0.10.4+2

  • Fix @CustomElement test in internet explorer.

0.10.4+1

  • Update initialize lower bound to get bug fixes.
  • Make sure to always use path.url in transformers.

0.10.4

  • Added CustomElement annotation. This can be added to any class to register it with a tag in the main document.
  • Added a web_components.dart file which exports all the annotations provided by this package. Note that in later breaking releases html_import_annotation.dart and custom_element_proxy.dart will likely move into the src folder, so switching to the web_components.dart import is recommended.

0.10.3

  • Added generateWebComponentsBootstrap method to the main web_components transformer file which accepts a Transform and a Resolver. You can use this function from any transformer and share the resolver you already have.
  • Fixed up the bootstrap call in ScriptCompactor to not use => syntax since it has a declared return type of void. This could previously cause a checked mode error if the original program returned something from main.

0.10.2+1

  • Minor cleanup to changelog and tests.
  • ImportInliner now throws warnings instead of errors.

0.10.2

  • Added the HtmlImport annotation. This can be added to any library declaration and it will inject an html import to the specified path into the head of the current document, which allows dart files to declare their html dependencies. Paths can be relative to the current dart file or they can be in package: form.

    Note: Html imports included this way cannot contain dart script tags. The mirror based implementation injects the imports dynamically and dart script tags are not allowed to be injected in that way.

    Note: Relative urls cannot be used in inlined script tags. Either move the script code to a Dart file, use a package: url, or use a normal HTML import. See https://github.com/dart-lang/web-components/issues/6.

  • Added a web_components transformer. This should be used in place of the initialize transformer if that already exists in your application (it will call that transformer). This will inline html imports (including @HtmlImport annotations) into the head of your document at compile time, it can be used like this:

    transformers:
    - web_components:
        entry_points:
          - web/index.html
    

    If no entry_points option is supplied then any html file under web or test will be treated as an entry point.

0.10.1

  • Added the CustomElementProxy annotation. This can be added to any class which proxies a javascript custom element and is the equivalent of calling registerDartType. In order to use this you will need to be using the initialize package, and call its run method from your main function. It is also recommended that you include the transformer from that package to remove the use of mirrors at runtime, see initialize for more information.

0.10.0

  • Updated to the 0.5.1 js version.
  • Breaking Change To remain consistent with the js repository all the platform.js has been replaced with webcomponents.js. Also, the default file is now unminified, and the minified version is called webcomponents.min.js.

0.9.0+1

  • Remove all .map and .concat.js files during release mode.

0.9.0

  • Updated to platform version 0.4.2, internally a deprecated API was removed, hence the bump in the version number.

  • split dart_support.js in two. dart_support.js only contains what is necessary in order to use platform.js, interop_support.js/interop_support.html can be imported separately when providing Dart APIs for js custom elements.

0.8.0

  • Re-apply changes from 0.7.1+1 and also cherry pick efdbbc to fix the customElementsTakeRecords function.
  • Breaking Change The customElementsTakeRecords function now has an an optional argument node. There is no longer a single global observer, but one for each ShadowRoot and one for the main document. The observer that is actually used defaults to the main document, but if node is supplied then it will walk up the document tree and use the first observer that it finds.

0.7.1+2

  • Revert the change from 0.7.1+1 due to redness in FF/Safari/IE.

0.7.1+1

  • Cherry pick f280d and 165c3 to fix memory leaks.

0.7.1

  • Update to platform version 0.4.1-d214582.

0.7.0+1

0.7.0

  • Updated to 0.4.0-5a7353d release, with same cherry pick as 0.6.0+1.
  • Many features were moved into the polymer package, this package is now purely focused on polyfills.
  • Change Platform.deliverDeclarations to Platform.consumeDeclarations(callback).
  • Cherry pick https://github.com/Polymer/ShadowDOM/pull/505 to fix mem leak.

0.6.0+1

0.6.0

  • Upgrades to platform master as of 8/25/2014 (see lib/build.log for details). This is more recent than the 0.3.5 release as there were multiple breakages that required updating past that.
  • There is a bug in this version where selecting non-rendered elements doesn't work, but it shouldn't affect most people. See https://github.com/Polymer/ShadowDOM/issues/495.

0.5.0+1

  • Backward compatible change to prepare for upcoming change of the user agent in Dartium.

0.5.0

  • Upgrades to platform version 0.3.4-02a0f66 (see lib/build.log for details).

0.4.0

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

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)

0.3.5

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

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.11.1+1 <0.12.0"

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

2. Install it

You can install packages from the command line:

$ pub get

Alternatively, your editor might support pub. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:web_components/web_components.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_components/0.11.1+1/index.html#web_components

Uploader

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

Share