Experimental Features

Feature layering

EXPERIMENTAL: API MAY CHANGE.

Polymer is currently layered into 3 sets of features provided as 3 discrete HTML imports, such that an individual element developer can depend on a version of Polymer whose feature set matches their tastes/needs. For authors who opt out of the more opinionated local DOM or data-binding features, their element's dependencies would not be payload- or runtime-burdened by these higher-level features, to the extent that a user didn't depend on other elements using those features on that page. That said, all features are designed to have low runtime cost when unused by a given element.

Higher layers depend on lower layers, and elements requiring lower layers will actually be imbued with features of the highest-level version of Polymer used on the page (those elements would simply not use/take advantage of those features). This provides a good tradeoff between element authors being able to avoid direct dependencies on unused features when their element is used standalone, while also allowing end users to mix-and-match elements created with different layers on the same page.

• polymer-micro.dart: Polymer micro features (bare-minimum Custom Element sugaring)

• polymer-mini.dart: Polymer mini features (template stamped into "local DOM" and tree lifecycle)

• polymer.dart: Polymer standard features (all other features: declarative data binding and event handlers, property nofication, computed properties, and experimental features)

This layering is subject to change in the future and the number of layers may be reduced.

Polymer micro features

The Polymer micro layer provides bare-minimum Custom Element sugaring.

Feature	Usage
Custom element registration	@PolymerRegister(...)
Basic lifecycle callbacks	created, attached, detached, attributeChanged
Declared properties	@property String myProperty;
Attribute deserialization to property	<my-element my-property="bar"></myelement>
Static attributes on host	static final hostAttributes = { <attribute>: <value> };)
Behaviors	class MyElement extends PolymerElement with MyBehavior {...}

Polymer mini features

The Polymer mini layer provides features related to local DOM: Template contents cloned into the custom element's local DOM, DOM APIs and tree lifecycle.

Feature	Usage
Template stamping into local DOM	<dom-module><template>...</template></dom-module>
DOM distribution	<content>
DOM API	Polymer.dom
Configuring default values	@property String myProperty = 'hello';
Bottom-up callback after configuration	ready: () {...}

Polymer standard features

The Polymer standard layer adds declarative data binding, events, property notifications and utility methods.

Feature	Usage
Automatic node finding	this.$[<id>]
Event listener setup	@Listen('<node>.<event>') void onFoo(event, target) {...}
Annotated event listener setup	<element on-[event]="function">
Property change callbacks	@Property(observer: 'function') String myProperty;
Annotated property binding	`<element prop="{{property
Property change notification	@Property(notify: true) String myProperty;
Binding to structured data	<element prop="{{obj.sub.path}}">
Path change notification	set(<path>, <value>)
Declarative attribute binding	`<element attr$="{{property
Reflecting properties to attributes	@Property(reflectToAttribute: true) String myProperty;
Computed properties	@Property(computed: 'computeFn(dep1, dep2)') String myString;
Computed bindings	<span>{{computeFn(dep1, dep2)}}</span>
Read-only properties	@property String get myString;
Utility functions	toggleClass, toggleAttribute, fire, async, …
Scoped styling	<style> in <dom-module>, Shadow-DOM styling rules (:host, ...)
General polymer settings	<script> Polymer = { ... }; </script>