Today I’d like to share how I created my first element with Polymer 2. This post covers the following topics:
- Create a new element using Polymer CLI
- Useful resources for development
- Understand Polymer element
- Handle and fire events
- Dependency management
- AJAX request (advanced)
Before getting started, you need to ensure you’ve npm, bower and Polymer CLI installed in your machine. For example, in Mac OS:
brew install node npm install -g email@example.com npm install -g firstname.lastname@example.org
I fixed the version of Polymer and bower to adapt Nuxeo’s requirement. However, you might want to adjust them, or simply take the latest version.
Init Polymer Element
Initialize a Polymer element using Polymer CLI:
$ polymer init
It will ask you “Which starter template would you like to use?”, you can choose:
- polymer-2-element - A simple Polymer 2.0 element template
- polymer-2-application - A simple Polymer 2.0 application
- polymer-2-starter-kit - A Polymer 2.x starter application template, with navigation and “PRPL pattern” loading
- shop - The “Shop” Progressive Web App demo
I chose polymer-2-element. Once chosen, Polymer CLI will run
for you to install the required dependencies. Now, you can start the development
polymer-demo $ polymer serve info: Files in this directory are available under the following URLs applications: http://127.0.0.1:8081 reusable components: http://127.0.0.1:8081/components/polymer-demo/
- browser supports
Understand Polymer Element
Once you’ve create the structure of a Polymer Element, you will want to understand how it works. This sections describes how to do it using your browser console (I’m taking Chrome as example).
You can inspect the elements inside the shadow DOM. The source code is available in browser console:
Query Shadow DOM
You can test you element by querying its shadow DOM. This is also done in the browser console:
Query host property
Query local DOM style sheets:
More information can be found on MDN: ShadowRoot - Web APIs.
Automatic Node Binding
Polymer automatically builds a map of statically created instance nodes in its
local DOM, to provide convenient access to frequently used nodes without the
need to query for them manually. Any node specified in the element’s template
with an id is stored on the
this.$ hash by
For example, given the following template:
You can find the description inside the local DOM:
Or outside the local DOM, such as in browser console:
Elements use events to communicate state changes up the DOM tree to parent elements. Polymer elements can use the standard DOM APIs for creating, dispatching, and listening for events. Polymer also provides annotated event listeners, which allow you to specify even listeners declaratively as part of the element’s DOM template.
To add even listener to local DOM children, user
on-<event> annotatons in your
<myElement on-myEvent="myFunc"> ... </myElement>
Then write a function the handle such event in your element:
But, which events can I use?
There’re several resources that can help you. Firstly, MDN: Event
reference. This article offers a list of events that can be sent; some are
standard events defined in official specifications, while others are events used
internally by specific browsers. Secondly, check the JSDoc of the target element
(or its parent element), all the events are document as
@event. For example,
it has events
For more detail, see Polymer 2.0 - Handle and fire events.
Polymer CLI 1.6 uses Bower for dependency management. You need to declare your
bower.json. There’re two kinds of dependencies:
devDependenciesare for the development-related scripts, e.g. unit testing, packaging scripts, documentation generation, etc.
dependenciesare required for production use, and assumed required for dev as well.
The structure of
bower.json file, generated by Polymer CLI, is as follows. You
can add new dependency to either dependencies or devDependencies based on your
New developers (like me) might feel difficult to understand the semantic
versioning of npm — for example
~2.2. The best way to start is to
use npm semver calculator (https://semver.npmjs.com/), which provides concrete
examples for you.
The following sections are advanced configurations.
Proxy in Polymer CLI. When developing AJAX in element with Polymer CLI, you
need to provide a proxy to redirect all requests. Use
--proxy-path to define
the top-level path that should be redirected to the proxy-target. e.g.
api/v1 when you want to redirect all requests of https://localhost/api/v1/;
--proxy-target to define host URL to proxy to:
$ polymer serve \ --proxy-path='api/v1' \ --proxy-target='https://localhost:8080/api/v1/'