In this step we are going to use our first Polymer element, a very simple custom beer-list-item
.
By using it you will see how easily you can add Polymer widgets to your normal web applications.
In this step we are adding two dependencies, Polymer to get the WebComponents polyfill and the Polymer library core fun functionalities, and Bootstrap to make our app prettier.
As usual, you set these dependencies in the bower.json
file of your working directory:
{
"name": "polymer-beers",
"version": "0.0.0",
"license": "http://polymer.github.io/LICENSE.txt",
"dependencies": {
"bootstrap": "~3.3.6",
"polymer": "~1.4.0"
}
}
We are adding a custom beer-list-item
Polymer element that will be stored in the elements
folder.
A Polymer element definition is composed of two parts inside a dom-model
declaration:
-
A
template
defining the local DOM for the element and the CSS rules that apply to this local DOM. -
A
Polymer
element registration linking thedom-model
and it's behavior and making it available to the application.
You will get (lots of) more details on custom element definition on further steps, by now this should be enough.
Our custom element is very simple at this step:
<!-- Import Polymer library -->
<link rel="import" href="../../bower_components/polymer/polymer.html">
<dom-module id="beer-list-item">
<template>
<style>
.beer {
margin: 10px;
padding: 10px;
border: solid 1px black;
border-radius: 10px;
min-height: 50px;
}
</style>
<div class="beer">
<h2>{{name}}</h2>
<p>{{description}}</p>
</div>
</template>
<script>
Polymer({
is: 'beer-list-item',
properties: {
name: String,
description: {
type: String,
value: ""
}
}
})
</script>
</dom-module>
Using Polymer elements is quick and painless, you only need to follow three steps:
- Load the polyfill Web Components to have support for older browsers
<!-- Polyfill Web Components lite, adding support for older browsers -->
<script src="../bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
- Import the elements you want to use, i.e.
beer-list-item
<!-- Import `beer-list-item` element -->
<link rel="import" href="./elements/beer-list-item.html">
- Use the element as a new HTML tag
<beer-list-item
name="Affligem Blond"
description="Affligem Blonde, the classic clear blonde abbey ale, with a gentle roundness and 6.8%..."
></beer-list-item>
<beer-list-item
name="Affligem Tripel"
description="The king of the abbey beers. It is amber-gold and pours with a deep head and original..."
></beer-list-item>
You're going to replace the <ul>
and the <li>
items that you created in step-01 with two beer-list-item
elements, one for each beer.
In order to do it, you need to follow the steps previously described in Using Polymer elements, loading the polyfill and importing the beer-list-item
element in the header section of index.html
and then using the newly registered <beer-list-item>
in the HTML body for both beers.
Data binding binds a property or sub-property of a custom element (the host element) to a property or attribute of an element in its local DOM (the child or target element).
A binding is created with a binding annotation in the host element’s local DOM template:
<dom-module id="beer-list-item">
<template>
<div class="beer">
<h2>{{name}}</h2>
<p>{{description}}</p>
</div>
</template>
</dom-module>
A binding annotation consists of a property name enclosed in curly brackets ({{}}
) or square brackets ([[]]
).
-
Square brackets ([[]]) create one-way bindings. Data flow is downward, host-to-child, and the binding never modifies the host property.
-
Curly brackets ({{}}) create automatic bindings. Data flow is one-way or two-way, depending whether the target property is configured for two-way binding.
To bind to a child property, specify the attribute name that corresponds to the property, with an annotation as the attribute value:
<beer-list-item
name="Affligem Tripel"
description="The king of the abbey beers. It is amber-gold and pours with a deep head and original..."
></beer-list-item>
Here we are defining an instance of beer-list-item
component binding the component name
property to "Affligem Tripel"
and the description
to "The king of the abbey beers. It is amber-gold and pours with a deep head and original..."
.
For more information about data binding, see the Polymer documentation
Any property that’s part of your element’s public API should be declared in the properties
object of the Polymer element registration.
In this properties
object you associated the property name to a string defining the property type or to an object describing more details of the property, as:
- Property type.
- Default value.
- Property change observer. Calls a method whenever the property value changes.
- Read-only status. Prevents accidental changes to the property value.
- Two-way data binding support. Fires an event whenever the property value changes.
- Computed property. Dynamically calculates a value based on other properties.
- Property reflection to attribute. Updates the corresponding attribute value when the property value changes.
<script>
Polymer({
is: 'beer-list-item',
properties: {
name: String,
description: {
type: String,
value: ""
}
}
})
</script>
For more information about properties, see the Polymer documentation
Try modifying the element to show the beer name in red.
You will see that you need to do it inside the style
block of the dom-model
definition for the element. Following the encapsulation principle, global CSS rules don't pass the element frontier.
You have added a Polymer custom web component to an otherwise static app. Now go to step-03 to see how to create another element to automatically generate the beer list.