Polymer 1.0: dom-repeat tutorial part 1

cat-appender is the name of the element we are creating

Dom-repeat is one of the most useful helper elements in Polymer, in this post series we’ll go through a working example adding, removing and retrieving data, step by step explaining what is happening and linking to the appropriate documentation page for more in-depth details.

This post is part 1 of a 2-part series, it will discuss how to setup the element and basic dom-repeat.

First off, I’m assuming that you know what polymer is and that you have Created an element project.

The element we are going to work on is repeating unordered list items, it is called “cat-appender” (because I like cats, but feel free to name it whatever you like :3).

Here's a demo of what the final result will look like, I’ve removed all the clutter to focus on the element itself.

Enough talking, let’s dive in:

Setting up the element

We will start by setting up the element, that is giving it the required properties and template.

Here’s what the element prototype looks like (at the end of cat-appender.html in the demo) :

<script>
  Polymer({
    is: 'cat-appender',
    properties:{
      kitties: Array
    }
  });
</script>

We have a sole property defined in the properties object, that’s the array that will go inside the “dom-repeat” in a moment, it’s an array of objects as you may have guessed.

Here’s what the template looks like (cat-appender.html in the demo still):

Inside your <dom-module> and <template> elements

<ul>
  <template is="dom-repeat" items="[[kitties]]" as="kitty">
    <li>
      [[kitty.name]] : [[kitty.age]]
    </li>
  </template>
</ul>

I assume that you came to this post because you’ve read about basic dom-repeat somewhere, so I’m going with a quick explanation about what’s going on here:

• We are telling Polymer that we want to repeat the enclosed markup with the <template is="dom-repeat">.
• We provide the data we want to iterate on as the “items” property, here, it is the “kitties” property that we defined earlier for the element prototype, it takes its value from the parent (the “host” element when used in a page).
• “as” property gives an alias to the default “item” that is used to reference the current item that the dom-repeat is iterating over at the moment, this property is commonly used in nested dom-repeats to reference parent template, but I thought it’s worth mentioning.
• Inside we are rendering an <li> for every item (object) in the array, notice that we’ve used the alias “kitty” instead of the default “item” that we would’ve used otherwise.

Docs for this section:

• Basic dom-repeat
• Property binding
• "as" property

Notes on data binding annotations

Choosing an annotation for data binding may seem confusing at first, make sure that you read through the documentation and get your head around it.

As a simple rule: one-way data binding ( [[ ]] ) will be suitable when the goal is to show (read) or use the data without modifications, like when we used it to iterate over the kitties array in the dom-repeat.

While automatic binding ( {{ }} ) is most useful when binding to data that will change, like an input value or an element property (not attribute, see attribute binding if you want to investigate), or when binding to array items (As they are always two-way).

Now, on the file that you’ll show your element in (index.html in the demo):

<link rel="import" href="cat-appender.html">

<h3>Cat list</h3>
<cat-appender 
kitties='[{"name": "Simba", "age": 29}, {"name": "Mufasa", "age": 35}, {"name": "Sylvester", "age":71} ]' >
</cat-appender>

That code imports the element that we just created, and shows it on the page (if you have created an element project, you already have it setup in your demo directory), we then give it an array of objects (cats with names and ages, in this case) as a property.

Note:

• Single quotes are being used for the property itself, that’s because this array is being deserialized into a JSON string, which must have double quotes.
• Also the property names for the objects are enclosed in double quotes, it will not deserialize properly if you remove the quotes (because it’s a JSON string, not a Javascript object). Further reading

We now have a template that is repeated on an array, nothing very interesting so far.
In the next part we will let the user add a cat, remove a cat and retrieve the cats in the list through our “API”, stay tuned, it’s coming very soon..

Update: part 2 is here