Your Component & Polymer

Appmaker components are built with the help of a framework called Polymer. It's a neat framework for building custom HTML elements. In this guide, we'll show you the basics of what you need to know about Polymer! We'll be using the Counter component from the Start Here repo.

You can jump to the full Polymer docs, or follow along!

We'll take a look at...

1. Working with Attributes
2. Data Binding
3. Web Events
4. Selecting Nodes
5. Lifecycle Methods

Working with Attributes

Polymer has some cool tricks for handling attributes. The counter component has three: unit, increment, and value.

<polymer-element name="ceci-counter" extends="ceci-element" attributes="unit increment value">

####Getting or setting an attribute

To set a default value, we can add it to the polymer element tag like this:

<polymer-element name="ceci-counter" extends="ceci-element" attributes="unit increment value" value="5">

You can also set a default value using the ready lifecycle method,

We can also set an attribute value in the Polymer definition...

value : 0,

Or use the this.attributeName shorthand inside of a method:

this.value = 0;

We can also use the time-honored classic get and set methods:

this.setAttribute("value","0")

Tracking attribute value changes

When an attribute value changes, Polymer will automatically look for and fire an attributeChanged function with the corresponding name. Here's how the counter component handles changes to the increment attribute:

incrementChanged: function(oldValue, newValue) {
  this.increment = Number(this.increment) || 0;
}

Data Binding

Polymer lets you bind special template variables in your element markup to it's attributes, properties and methods. The counter component uses this data binding to display the value attribute and the displayUnit property, like this...

<div class="count-wrapper">
  <span class="count">{{value}}</span>
  <span class="count-label">{{displayUnit}}</span>
</div>

When the count changes, the element will be automatically updated.

Web Events

Polymer provides a shorthand for binding common web events to methods. The following demonstrates using a click handler to fire off a method. Notice that you can use the data binding stuff from above to refer to methods as well:

<button on-click="{{clickHandler}}" />

clickHandler : function(){ console.log("I done been clicked!") }

You can use this shorthand for all common web events like:

• keypress
• mouseenter
• And many more!

###Selecting Nodes Polymer has some cool shorthand for selecting nodes with an id attribute. You can select a node with id="jumbo" using...

this.$.jumbo

For other types of selectors, it's best to use the shadowRoot combined with a querySelector. So, for selecting a node with class="important", we'd use:

this.shadowRoot.querySelector(".important")

Lifecycle Methods

Polymer has some neat lifecycle methods that you'll probably want to make use of in your component.

The Ready Method

You'll probably make use of the ready method. The counter sure does:

ready: function() {
  this.increment = Number(this.increment) || 1;
  this.value = Number(this.value) || 0;
  this.super();
  this.displayUnit = this.unit;
  this.updateUnit();
}

The ready method is a great place to initialize all your component's properties and attributes.

The attached Method

The counter doesn't use this method, but we've found it to be more useful than the ready method if you need to select or modify the element's DOM.

attached : function(){
  this.shadowRoot.querySelector(".boing").style.display = "block";
}