Lets Start Building a Polymer App! (Part 2)

This is the part 2 of my series of building a Polymer App using the Polymer App Toolbox.

In the upcoming posts, I will take a closer look into the /src folder of the Polymer-app project and deconstruct the lines of code in the file my-app.html. Specifically in this post, I will cover the topics of HTML Imports, Encapsulation, Shadow DOM, Polyfills, and Templates.

So lets begin!

Here is what the file structure of the Polymer-app project looks like right now:

Lets open up the file my-app.html and take a closer look inside. The file begins with a list of HTML imports:

<link rel=”import” href=”../bower_components/polymer/polymer.html”>
<link rel=”import” href=”../bower_components/app-route/app-location.html”>
<link rel=”import” href=”../bower_components/app-route/app-route.html”>
<link rel=”import” href=”../bower_components/app-layout/app-drawer-layout/app-drawer-layout.html”>
<link rel=”import” href=”../bower_components/app-layout/app-drawer/app-drawer.html”>
<link rel=”import” href=”../bower_components/app-layout/app-scroll-effects/app-scroll-effects.html”>

HTML Imports

HTML imports are a way to include and reuse HTML documents in other HTML documents rather than making Ajax requests or loading an iframe. It is similar to how we add other resources like javascript <script> and stylesheets <link rel=”stylesheet”> etc. This capability makes the page load faster, provides an opportunity to reuse code, and calls for an easier integration.

Going back to the my-app.html file, we come across the following line of code:

<dom-module id=”my-app”>

In order to understand what is happening here, we now need to go into the topic of Shadow DOM. But in order to understand Shadow DOM, we first need to talk about the important Object Oriented concept of Encapsulation.


The concept of encapsulation is one of the fundamentals of object oriented programming. It is also called information hiding. It is used to hide the values or state of an object inside a class, preventing unauthorized direct access (recall public vs private) Usually only the object’s own methods can directly inspect or manipulate its fields.

Hence through encapsulation, an object exposes an interface to the outside world which can then be used to interact with its data. By maintaining this interface, an object can restrict outside code from wiping out its private data. HTML for a long while did not offer such functionality but now through Shadow DOM encapsulation is possible in web development.

Shadow DOM

When HTML gets converted to the DOM, every element is considered to be a node. A node tree is when a group of these nodes are nested inside one another. Here is a simple DOM structure if we represent it as a tree:

Each node in the DOM is also an object whose properties can be changed via javascript. A DOM tree can also be composed of one or more DOM nodes that implement a certain functionality. These nodes are not encapsulated from the rest of the page. This means that the stylesheets and scripts that are not supposed to be meant for particular DOM nodes, might accidentally apply and hence modify the node functionality.

Here is where Shadow DOM comes to the rescue! It helps by separating content from presentation as it is basically the ability to take a DOM subtree and hide it from the main document scope. And hence it allows us to encapsulate HTML, CSS, and JavaScript and create our own tags which are are referred to as Web Components.

Shadow DOM is great but when developing we have to keep in mind the costs related to adding new functionalities especially ones that are new and not available in every browser.


Polyfill is a term introduced by Remy Sharp in his 2009 book Introducing HTML5. It implies filling in missing browser functionality by adding additional code.

Turns out that it is very hard to polyfill shadow DOM as it requires a lot of code, certain functionalities are not available, and there are performance costs.

Now let us go back to the Polymer code in the file my-app.hmtl:

<dom-module id=”my-app”>

Polymer Framework helps create custom elements via Shadow DOM. Each element has it’s own local DOM where the <dom-module> tag is the declarative portion of the element’s definition and the id attribute is the name of the element.

In our example, my-app is the name of the custom element that we are creating in this file.

The next line of code declares a new tag:



HTML’s new template tag allows the user to declare fragments of markup which are parsed as HTML but go unused at runtime and can be instantiated when needed. Template will not render it’s contents by itself and will not fetch any resources.

In the next blog I will take a closer look at the code inside this template tag in the my-app.html file, so stay posted!

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.