Polymer.dart is a port of the JavaScript Polymer library that combines Web Components, the Observe library, and a few others libraries into a single framework. This makes creating reusable encapsulated components very easy (it also uses polymer.js internally).
As we already know enough about Web Components, we'll particularly take a look at one-way / two-way data binding and creating custom elements with their behavior written in Dart.
We'll begin by installing polymer.dart by adding polymer among our dependencies in pubspec.yaml and letting Dart Editor fetch all the dependencies for us. Right away, we can tell polymer.dart what our app's entrance points are. These are the pages that the user can access (that's probably everything except HTML templates for our custom elements), so all our pubspec.yaml files will look alike. When compiling apps with Pub Build, this also lets polymer.dart concatenate all pages together for faster loading:
name: Chapter_05_polymer_tutorial
description: My first Polymer app
dependencies:
browser: any
polymer: '>=0.16.0 <0.17.0'
transformers:
- polymer:
entry_points: web/index.htmlThe HTML for index.html is going to be very simple and mostly what we've already seen in the previous examples. Note that we're including the Dart script at the end. It has to be included after importing custom elements, so the best practice is to put it at the end:
<!-- web/index.html -->
<html>
<head>
<script src="packages/browser/dart.js"></script>
<link rel="import" href="my-element.html">
</head>
<body>
<my-element></my-element>
<script type="application/dart" src="main.dart"></script>
</body>
</html>Where things start to get interesting is with our element's definition in my-element.html. Each custom element in polymer.dart has to be in a separate file that imports the Polymer stub code at the top and contains one <polymer-element> tag. The <polymer-element> is a wrapper for our custom element that can use:
- The HTML template: This is required for all custom elements.
- CSS styles (optional): Use this to style only the Shadow DOM encapsulated from the rest of the page. There's a special CSS
:hostkeyword that refers to the currenthostelement. We'll see this in action later. - Dart script (optional): This is your custom code that defines the element's behavior.
To keep it very simple, we'll create a custom element that contains only the HTML template with no styles and no Dart:
<!-- lib/my-element.html -->
<link rel="import" href="../packages/polymer/polymer.html">
<polymer-element name="my-element" noscript>
<template>
<h1>Hello polymer.dart!</h1>
</template>
</polymer-element>Each custom element has to import polymer.html before declaring the element itself. The polymer.html file comes from the JavaScript Polymer project and is part of the polymer.dart package. For larger components with multiple files, you might want to look at directory structure recommendations at https://www.dartlang.org/polymer/app-directories.html.
As polymer.dart expects that your custom element will have some Dart attached to it by default, we have to tell it specifically that this element has no script with the noscript attribute.
Our element's name is going to be my-element (the name has to contain at least one dash, just like in the previous example).
The last part, for now, is main.dart, which will initialize polymer.dart:
// web/main.dart
import 'package:polymer/polymer.dart';
main() async {
// Recommended way of running main() with polymer.dart
// [initPolymer()] returns a Future object that is completed
// when all imports are loaded. New since polymer.dart 0.16.
(await initPolymer()).run(() {
// The rest of the code in the main method.
});
}This may look weird at first sight. The code for main() should be in a callback to the run() method of initPolymer(). This makes use of the so-called Zone-related API, which is like a unified way of handling exceptions from asynchronous calls. It's not important for us, but if you want to read more about this topic, check out https://www.dartlang.org/articles/zones/.
Now, we can run our first polymer.dart application:
We can see that polymer.dart did pretty much the same as what we did with vanilla Web Components. It created a Shadow DOM and cloned the content of the <template> to <my-element>.
But there's already an important difference. We didn't have to write any code specific to this custom element. Everything is done for us in the background by polymer.dart.