The Polymer.dart framework provides a set of Polymer (UI and other) components, but it will only work in the most recent versions of browsers: IE9, IE10, Safari 6, Firefox, and the latest Chrome (also for Android). It is important that in Polymer you can only have a single Dart script tag on an HTML document. Get started with creating a new Polymer application polymer1 by selecting the project template Web application (using the polymer library) in Dart Editor:
A new Polymer application
Inspecting pubspec.yaml will reveal the polymer dependency:
dependencies: polymer: any
Pub is invoked automatically, and installs polymer and a whole group of packages needed by polymer (such as mdv, observe, polymer_expressions, shadow_dom, and so on). We'll now examine in detail how a web component is defined in Polymer.
This is what we see when
polymer1.html file is run: again a counter button, defined as a web component (also called a Polymer element):
The clickable counter in polymer1
The main polymer1.html file contains the following important sections:
<link rel="import" href="clickcounter.html"> (1) <script type="application/dart"> export 'package:polymer/init.dart'; </script> (2) <script src="packages/browser/dart.js"></script> </head> <body> <h1>Polymer1</h1> <p>Hello world from Dart!</p> <div id="sample_container_id"> <click-counter count="5"></click-counter> (3) </div> </body>
In addition to the dart.js file we now need polymer/init.dart in line (2) to initialize polymer elements automatically. Alternatively, if you do want to replace it with your own Dart script, be sure to include a call to the initPolymer() method:
main() {initPolymer();
doSomething();
}In line (3), we see the web component <click-counter>, which as before is imported through the <link rel ="import"> tag in line (1).
The name of a component must contain a dash (-); in general, the first half of the name should make it unique (for example, by including a project or a business name) so as to avoid conflicts with the other components. Now, let's turn our attention to the definition of the web component. The structure and style of the <click-counter> web component is defined in clickcounter.html file inside a <template> in a <polymer-element> tag whose name attribute in line (4) is the name of the web component:
<polymer-element name="click-counter"> (4) <template> <style> div { font-size: 24pt; text-align: center; margin-top: 140px; } button { font-size: 24pt; margin-bottom: 20px; } </style> <div> <button on-click="{{increment}}">Click me</button><br> (5) <span>(click count: {{count}})</span> (6) </div> </template> <script type="application/dart" src="clickcounter.dart"></script> (7) </polymer-element>
In general, the <template> section contains markup outlining the UI appearance of the web component. We observe that an HTML file containing a Polymer element definition does not need <html>, <head>, or <body> tags. Line (5) shows that <click-counter> is a button that reacts on the click event by calling an increment method. Line (6) tells us that a count variable is shown with the polymer expression {{count}}. This is the typical syntax {{ expression }} used for data binding to an expression, but as shown in line (5), an event handler is called in the same way.
The behavior of the component is defined in the Dart script clickcounter.dart referenced in the <script> tag in line (7). This does a lot of things:
import 'package:polymer/polymer.dart'; (8) @CustomTag('click-counter') (9) class ClickCounter extends PolymerElement { (10) @published int count = 0; (11) ClickCounter.created() : super.created() { } (12) void increment() { (13) count++; } }
In line (8), the polymer package is imported, @CustomTag in line (9) registers click-counter as an element in the Polymer framework. Our model is represented by the ClickCounter class in line (10), which has to inherit from the PolymerElement class and override its created() constructor in line (12). This is because Polymer Elements are legitimate HTML elements. Note that the name of the Dart class is obtained after converting the first letter of each word separated by - to an uppercase letter, and then removing the -. The Polymer framework provides for synchronization of the model with screen data. In this case, it is the count variable that is annotated with @published in line (11) to indicate the simple, one-way (model to screen) data binding. Finally, it contains the increment method in line (13), which is called at each button click; this will increase the count variable by 1. This change will automatically be shown on the web page. In general, the Dart script implements the behavior of the component and can change (model) data. Each time a custom element is instantiated as in line (3) in the polymer1.html file, an instance of the Dart class is created and associated with the custom element. Data bindings in the template are bound to fields in that instance.
Tip
As a best practice, a web component has two files to separate the HTML markup from the Dart code. In some simple examples, you will see the code embedded in the <script> tag in the HTML file, but this is not recommended. When both files have the same name, it is easier to recognize them as parts of the same component.
Developing web applications with web components is a new approach that will let us divide a page in sections and use a web component for each section. If web components become reusable in different contexts, we may have a catalog of web components that would allow us to select and re-use them in a few lines of code. A page can also contain multiple instances of the same component, each behaving independently from each other. A polymer element is like a supercharged custom element, with functionality provided by the Polymer framework. It automatically allows for simple component registration, and uses the Shadow DOM. This means that its markup is hidden in the web page in which it is embedded, thus providing encapsulation by itself. Polymer uses composability of elements as much as possible, to the extent that the framework advocates proclaim that everything is a component in Polymer. Let's now examine data binding a bit closer.