Polymer: Creating a simple list component

Extracted from Google Polymer website:

Polymer is a pioneering library that makes it faster and easier than ever before to build beautiful applications on the web. Polymer is built on top of a set of powerful new web platform primitives called Web Components. Web Components bring unprecedented composability, interoperability, and consumability to the web platform. The result is a monumental increase in developer productivity.

The main concept in Polymer is to give an opportunity to create web applications on top of web components. So you develop several web components and use them to develop your web app. You can use the same web component in several pages or projects.

Polymer is still in development, but it is actually very stable and there is lots of small projects already using it. This small tutorial uses version 0.5.1 of polymer.

In this article I will show how to construct a very simple component, that will receive an object (or JSON string) with person information and render a list with those information.

Important !
If you are new to Polymer, I sugest reading this article first Polymer: Basic Installation. so you can install all necessary tools to play with Polymer.

There is a lot of information about Polymer at  Polymer website

Installing the tools detailed in the previous link makes the work easier.

In the first part of this tutorial, I will construct a new element to show user information. Later in a second part I will make some changes to use other visual components from the Polymer framework and make the visual layout more appealing.

Constructing the new Component (Element)

For this article I will create a new component to show a list of person information (name, address and profession). So create a new file called listcard-person.html with the basic template for a new element.

As you can see I already named the new componet as listcard-person in the html tag name and in the script creator.

Create a new index.html page that will use the listcard-person.html. The basic html without any Polymer info:

Add the links that will be used. The line is webcomponents.js, the main part of Polymer.

We will need another component from google called core-list, because we will use it in our component, so first you must install its dependencies in bower first (check Polymer: Basic Installation for info about Bower).

Finally add the link to our new component

<link rel="import" href="listcard-person.html">

Add the component to the body of index.html, and give it an id

<listcard-person id="personlist" />

At this moment you have an index.html like this

Returning to our listcard-person.html, inside the <template> we will add our component layout. You can use html tags as you wish. As we need to show a list of several people information, we will use another component called <core-list>. This component is provided by google as a starting point to develop an iterator with a data source. Our plan is to pass a JSON or an object to our component with several person information and let the <core-list> traverse all items and render the information.

In <core-list> element you can see that I added a data attribute with a {{personData}} value. This personData is our data source. We will populate a javascript variable (personData) with the people info.
Inside <core-list> template we designed the layout for each person value, and made the bind from our variable to the html. Inside core-list we access the data source values using the model prefix and the field name. Our data source looks like this

we use model.name to retrieve name, model.address to retrieve address and so on.

Now we need to receive the the data and perform the bind. I will show two ways to do that.

Populating the list using attributes

To pass data to the component we can opt to use in-tag attributes for static values. Change index.html

<listcard-person id="personlist"/>
to

As you can see, we will use a new attribute we called initialData to pass the entire JSON string to our new component, and in listcard-person.html we will receive the value.

Change the first line where we define the element from

<polymer-element name="listcard-person" layout vertical>

to

<polymer-element name="listcard-person" layout vertical attributes="initialData">

This inform to the component that we will receive an attribute that is called initialData

Now change the script part. When the component is ready, we will check if the caller provided the initialData attribute. If it does than we will convert the JSON string to an object and will store the value in the personData (our datasource used in <core-list> “data” element).

Now you can save all changes and reload the index.html in the browser. You will see a simple list of all values.

Populating the list using javascript

The second way we can implement to populate the component is calling a javascript function.

In listcard-person.html, add to the script part another function called loadData that will receive the object to be used and associate it with the <core-list> datasource.

Make another change in the index.html to call our new function that will populate the data source.

Change the component definition in index.html again from

to

<listcard-person id="personlist"/>

Add below script tag to index.html. We added a listenet to “polymer-ready” event, that represents the moment when polymer is ready to begin (already donwloaded all dependencies).
At this moment we will find our component (we named it personlist), create a new object with the values we wish to populate and call the loadData method we implemented
in the component.

When you load the page it will populate the component calling loadData.

In next article I will show how to make the output looks beautiful with layout features from Polymer.