Getting Started with Polymer

Let's talk about web components. What are they? Why should we use them on the Web and what kind of problems can they solve?

Imagine for a moment, what if you could write less code and make more things than now, what if you could just create a <website> component and give it some attributes and create your entire website in a second. You think it is possible only in the future? Nope, it's happening now! Web components are here and they will solve all your problems.

There is no issue with browser support because now (at the time of writing this chapter) all modern browsers support web component polyfills.

Look at the following screenshot of code blocks from Gmail:

If you can read and understand this code, the only thing I would say to you is that you're a hero, because I can't!

What if I showed you code similar to the following? (I like this one, by the way):

This code is written using the features of web components and is way easier to read/understand/execute. Now, compare both the examples. Do you see any difference? I guess you already know which one is better.

Web components allow us to create complex UI widgets and applications. We can fill in the gaps with our own reusable components and then use them whenever we want.

There is a saying that:

Web components are a new era of web development and, in this book, we will discuss the benefits you can get using Polymer from Google. You can create your own elements that contain templates, encapsulated styles, and logic (JS). They also take advantage of a rich collection of ready-made elements (take a look at http://customelements.io).

"The platform of the future" is a set of standards that allows us to describe new types of DOM elements with their properties and methods that encapsulate their DOM and styles.

This means that the styles you have in a document will always render as you intend them to and your HTML code is safe from other users of external JavaScript code.

Web components have four specifications and we will discuss them in this chapter. They are as follows:

In this section, we will discuss what we can do with templates. However, let's answer a few questions before this.

What are templates and why should we use them?

Templates are basically fragments of HTML, but let's call these fragments the "zombie" fragments of HTML as they are neither alive nor dead. What is meant by "neither alive nor dead"? Let me explain this with a real-life example.

Once, when I was working on the ucraft.me project (it's a website built with a lot of cool stuff in it), we faced some rather new challenges with the templates. We had a lot of form elements, but we didn't know where to save the form elements content. We didn't want to load the DOM of each form element, but what could we do? As always, we did some magic; we created a lot of div elements with the form elements and hid it with CSS. But the CSS display: none property did not render the element, it loaded the element. This was also a problem because there were a lot of form element templates and it affected the performance of the website.

I recommended to my team that they work with templates. Templates can contain HTML content, but they do not load the element nor render.

We call template elements "dead elements" because they do not load the content until you get their content with JavaScript. Let's move ahead and let me show you some examples of how you can create templates and do some stuff with their contents.

Imagine that you are working on a big project where you need to load some dynamic content without AJAX. If I had a task such as this, I would create a PHP file and get its content by calling the jQuery .load() function. However, now you can save your content inside the <template> element and get the content without any jQuery or AJAX, but instead with a single line of JavaScript code. Let's create a template.

In index.html, we have <template> and some content we want to get in the future, as shown in the following code block:

<template class="superman">
  <div>
   <img src="assets/img/superman.png" class="animated_superman" />
  </div>
</template>

The time has now come for JavaScript! Execute the following code:

<script>
  // selecting the template element with querySelector()

  var tmpl = document.querySelector('.superman');
  //getting the <template> content
  var content = tmpl.content;
  // making some changes in the content
  content.querySelector('.animated_superman').width = 200;

  // appending the template to the body
  document.body.appendChild(content);
</script>

So, that's it! Cool, right? The content will load only after you append the content to the document. So, do you realize that templates are a part of the future web? If you are using Chrome Canary, just turn on the flags of experimental web platform features and enable HTML imports and experimental JavaScript.

There are four ways to use templates, which are:

Templates do not have these disadvantages. We will work with DOM and not with the strings. We will then decide when to run the code.

In conclusion:

The Shadow DOM specification is a separate standard. A part of it is used for standard DOM elements, but it is also used to create web components. In this section, you will learn what the Shadow DOM is and how to use it.

The Shadow DOM is an internal DOM element that is separated from an external document. It can store your ID, styles, and so on. Most importantly, the Shadow DOM is not visible outside of its scope without the use of special techniques. Hence, there are no conflicts with the external world; it's like an iframe.

Inside the browser

The Shadow DOM concept has been used for a long time inside browsers themselves. When the browser shows complex controls, such as an <input type = "range"> slider or a <input type = "date"> calendar within itself, it constructs them out of the most ordinary styled <div>, <span>, and other elements.

They are invisible at first glance, but they can be easily seen if the checkbox in Chrome DevTools is set to display Shadow DOM:

In the preceding code, #shadow-root is the Shadow DOM.

Getting items from the Shadow DOM can only be done using special JavaScript calls or selectors. They are not children but a more powerful separation of content from the parent.

In the preceding Shadow DOM, you can see a useful pseudo attribute. It is nonstandard and is present for solely historical reasons. It can be styled via CSS with the help of subelements—for example, let's change the form input dates to red via the following code:

<style>
  input::-webkit-datetime-edit {
    background: red;
  }
</style>

<input type="date" />

Once again, make a note of the pseudo custom attribute. Speaking chronologically, in the beginning, browsers started to experiment with encapsulated DOM structure inside their scopes, then Shadow DOM appeared which allowed developers to do the same.

Now, let's work with the Shadow DOM from JavaScript or the standard Shadow DOM.

Creating a Shadow DOM

The Shadow DOM can create any element within the elem.createShadowRoot() call, as shown by the following code:

<div id="container">You know why?</div>

<script>
  var root = container.createShadowRoot();
  root.innerHTML = "Because I'm Batman!";
</script>

If you run this example, you will see that the contents of the #container element disappeared somewhere and it only shows "Because I'm Batman!". This is because the element has a Shadow DOM and ignores the previous content of the element.

Because of the creation of the Shadow DOM, instead of the content, the browser has shown only the Shadow DOM.

If you wish, you can put HTML content via JavaScript inside this Shadow DOM. To do this, you need to specify where it is to be done. The Shadow DOM is done through the "insertion point" and it is declared using the <content> tag; here's an example:

<div id="container">You know why?</div>

<script>
  var root = container.createShadowRoot();
  root.innerHTML = '<h1><content></content></h1><p>Winter is coming!</p>';
</script>

Now, you will see "You know why?" in the title followed by "Winter is coming!".

Here's a Shadow DOM example in Chrome DevTool:

The following are some important details about the Shadow DOM:

• The <content> tag affects only the display and it does not move the nodes physically. As you can see in the preceding picture, the node "You know why?" remained inside the div#container. It can even be obtained using container.firstElementChild.

• Inside the <content> tag, we have the content of the element itself. In this example, the string "You know why?".

With the select attribute of the <content> element, you can specify a particular selector content you want to transfer; for example, <content select="p"></content> will transfer only paragraphs.

Inside the Shadow DOM, you can use the <content> tag multiple times with different values of select, thus indicating where to place which part of the original content. However, it is impossible to duplicate nodes. If the node is shown in a <content> tag, then the next node will be missed.

For example, if there is a <content select="h3.title"> tag and then <content select= "h3">, the first <content> will show the headers <h3> with the class title, while the second will show all the others, except for the ones already shown.

In the preceding example from DevTools, the <content></content> tag is empty. If we add some content in the <content> tag, it will show that if there are no other nodes.

Check out the following code:

<div id="container">
  <h3>Once upon a time, in Westeros</h3>
  <strong>Ruled a king by name Joffrey and he's dead!</strong>
</div>

<script>
  var root = container.createShadowRoot();

  root.innerHTML = '<content select='h3'></content> \
  <content select=".writer"> Jon Snow </content> \
  <content></content>';
</script>

When you run the JS code, you will see the following:

• The first <content select='h3'> tag will display the title

• The second <content select = ".hero"> tag would show the hero name, but if there isn't element with this selector, it will take the default value: <content select=".hero">

• The third <content> tag displays the rest of the original contents of the elements without the header <h3>, which it had launched earlier

Once again, note that <content> moves nodes on the DOM physically.

<div id="container">Polycasts</div>

<script>
  // create a new Shadow DOM tree for element
  var root = container.createShadowRoot();

  root.innerHTML = '<h1><content></content></h1> <strong>Hey googlers! Let\'s code today.</strong>';
</script>

<script>
  // read data from Shadow DOM for elem
  var root = container.shadowRoot;
  // Hey googlers! Let's code today.
  document.write('<br/><em>container: ' + root.querySelector('strong').innerHTML);
  // empty as physical nodes - is content
  document.write('<br/><em>content: ' + root.querySelector('content').innerHTML);
</script>

In this section, we will discuss another great feature of web components.

A reader with a critical mind would say, "Why do we need more standard types of elements? I can create any element right now! In any of the modern browsers, I can create any HTML tag I want using custom tags (<customtag>) or create elements from JavaScript using document.createElement('customtag')."

However, the default element with a nonstandard name (for example, <customtag>) is seen by the browser as something vague and incomprehensible. It corresponds to the HTMLUnknownElement class and it does not have any special methods.

The standard of custom elements allows you to describe the elements of its new properties and methods, declare your DOM and construction similarity, and much more.

Let's look at the following examples.

New item

For the description of a new element, we will use document.registerElement (name, {prototype: proto}), which can be explained as follows:

• name: This is the name of the new tag, such as super-tag. It must contain a dash (-). The specification requires a dash to avoid future conflict with the standard elements of HTML. You cannot create an item or timer with the name myTag. The DOM will identify this element as an unknown element.

• prototype: This is the prototype object for the new element and it must be inherited from the HTMLElement property, standard properties, and methods of the element.

Let me show you some examples of how to create custom elements and play with them using JavaScript.

At first, we need to create the custom <show-logo> element that has two attributes (id and logo). Let's go ahead and take a look at the ways in which we can choose to create a custom element, as follows.

HTML

<!—Creating Framework Logos tag -->
<!-- You can use names like (polymer, angular-js, backbone, ember, underscore, bower) -->
<show-logo id="showLogo" logo="polymer"></show-logo>

JavaScript

var logo = Object.create(HTMLElement.prototype);
logo.show = function(){
    // Creating info text
    var info = document.createElement('p');
    info.innerHTML = 'Hover me to feel the Logo!';

    var fwork = this.getAttribute('logo');

    var img = document.createElement('img');
    img.src = 'frameworks/logo/' + fwork + '.png';
    img.width = 300;
    img.height = 240;

    this.appendChild(img);
    this.appendChild(info);
    
    this.onmouseover = function(){
        this.audio.play(); 
    };
    this.onmouseout = function(){
        this.audio.pause();
    };
};
logo.audio = new Audio('logo/music/logo.ogg');

// Registering our Framework Logo element
document.registerElement('show-logo', {prototype: logo});
showLogo.show();

You can see the result in the following figure:

Here, we have our <show-logo> component, which contains an image that we have given as the logo attribute. The logo gets the image from the attribute value. You can try this live in the Examples page in the Chapter 1 folder in the accompanying code bundle of this book, available on the Packt website or on GitHub.

Let's have a look at what we did here. We created and registered our <show-logo> component, which has the .show() method. The .show() method creates some information and an image and appends it to our custom element. We also have audio attached here that starts playing when we hover over the element.

In the end, we will call our component's .show() method and it will create our scene.

If your new element is not defined in HTML, you can register it through registerElement(). The browser has a special mode to "upgrade" the existing elements.

When the browser sees an element with an unknown name that has a dash (-) (these elements are called unresolved), then:

• It puts this special CSS pseudo class as :unresolved and CSS might show that it is still "not loaded"

• When we call registerElement(), the elements will be updated automatically to the correct class

In the following example, the registration element takes 3 seconds after the document is loaded, as shown here:

<style>
  / * Style for: unresolved element (prior to registration) * /
  say-hello:unresolved {
    color: white;
    background: #cc0000;
  }
  say-hello {
    transition: all 4s;
  }
</style>
<say-hello id="hello">Hey, guys!</say-hello>
<script>
  // Registration will take place in 3 seconds
  setTimeout(function() {
    document.registerElement("say-hello", {
      prototype: {
        __proto__: HTMLElement.prototype,
        sayHelloAgain: function() { alert('I said HEY!'); }
      }
    });

    // the new type of elements is a method sayHelloAgain
    hello.sayHelloAgain();
  }, 3000);
</script>

Now, you can create <say-hello> elements in JavaScript and call createElement(), as follows:

var time = document.createElement('say-hello'); 

<script>
  var proto = Object.create(HTMLButtonElement.prototype);
  proto.count = function() {
    this.innerHTML++;
  };  

  document.registerElement("timer-tag", {
    prototype: proto,
    extends: 'button'
  });
</script>

<button is="timer-tag" id="counter">0</button>

<script>
  setInterval(function() {
    counter.count();
  }, 1000);

  counter.onclick = function() {
    alert("Current value: " + this.innerHTML);
  };
</script>

<script>
  var proto = Object.create(HTMLElement.prototype);

  proto.count = function() {
    this.counter++;
    this.innerHTML = this.counter;
  };

  proto.createdCallback = function() {
    this.counter = 0;
  };

  proto.attachedCallback = function() {
    setInterval(this.count.bind(this), 1000);
  };

  document.registerElement("timer-tag", {
    prototype: proto
  });
</script>

<timer-tag id="timer">0</timer-tag>

The new specification of HTML imports describes how to insert one document into another using the HTML tag <link rel="import">.

Yeah, you're right! There's an <iframe> element in the HTML code, so why should we use HTML imports instead of iframes?

With <iframe>, everything is okay. However, the meaning of <iframe> is a separate document:

It's useful when you want to show one page's content on another.

However, what if you want to build another document as a natural part of this? This can be done with a single scripting space and with the same style, but at the same time, it will be a new document.

For instance, it is necessary to load the external parts of the document (web components) from the outside. This is an excellent component because you will not to have to face origin problems with different domains. If we really want to connect an HTML page in one domain with another, we should be able to do it without having to "dance with a tambourine."

In other words, <link rel="import"> is an analogue of <script> for the connection of full documents, templates, libraries, web components, and so on. Everything will become clear when we look at the details.

Let's consider the following example of insertion:

<link rel="import" href="imported.html">

HTML loaded via <link rel="import"> has a separate document, but the scripts it contains are carried out in the general context of the page.

The file (imported.html) is loaded via <link rel = "import">, is processed, the scripts are run, and the DOM implementation is built. However, it is not shown and is recorded in the property link.import.

We will decide when and where to insert it.

In the following example, the <link rel="import" href="import.html"> code imports the import.html document and, after downloading it, calls the load() function. This function selects interesting parts of the loaded document through link.import.querySelector('custom-tag') and appends them into the current index.html file, as shown in the following example code:

<script>
  function load() {
    var element = link.import.querySelector('custom-tag')
    document.body.appendChild(element);
  };
</script>
<link rel="import" id="link" onload="load()" href="import.html">

The import.html file has elements and script that "revives" import.html, as shown here:

<!DOCTYPE HTML>
<html>
<body>
  <custom-tag id="counter">0</custom-tag>
  <script>
    var document = document.currentScript.ownerDocument;
    var counter = localDocument.getElementById('counter');

    var counterId = setInterval(function() {
      counter.innerHTML++;
    }, 1000);
  </script>
</body>
</html>

Here are some important details:

In this example, the main document is controlling the imported document, but the imported document can control itself and use document.body.appendChild(timer) to append itself inside the parent document. In this way, we don't need the onload event.

<link rel="import" href="paper-button.html">
<link rel="import" href="paper-radio-button.html">

<paper-button>...</paper-button>
<paper-radio-button>...</paper-radio-button>

Shadow DOM uses the standard styling specifications of CSS scoping. You can check the specifications at https://drafts.csswg.org/css-scoping/.

Default styles in the Shadow DOM apply only to its contents.

Consider the following example:

<p>Once upon a time,</p>
<p id="text">we are learned about Web Components</p>

<template id="template">
  <style>
    p {
      color: blue;
    }
  </style>
  <h1><content></content></h1>
  <p>Hello, from Shadow Root!</p>
</template>

<script>
  var root = text.createShadowRoot();
  root.appendChild(template.content.cloneNode(true));
</script>

When you open the document, the blue color will apply to only the <p> element inside the template. Let me note that as the color of the element, which is located directly in the Shadow DOM, and the items that appear in the Shadow DOM use the <content> tag, the style will not work; they have their own styles on the outer page.

<style>
  span { border: 1px solid black; }
</style>

<p id="text"><strong>Valar Marghulis!</strong></p>

<template id="template">
  <style>
    ::content strong { color: green; }
  </style>
  <h1><content></content></h1>
  <span>Valar Dohaeris!</span>
</template>

<script>
  text.createShadowRoot().appendChild( template.content.cloneNode(true) );
</script>

Here we are, finishing with the first chapter. As we haven't covered the concept of web components just yet, we will discuss Polymer in Chapter 3, Introduction to Polymer, the favorite framework of web components. It has a lot of components and features that use web components and even make it super powerful.

In the next chapter, we will cover the concepts of Material Design by Google and consider how to create an awesome app with these design concepts.

While we are here, let me mention two points about web components. First, you can make components, make elements with Shadow DOM in your page, import other HTML and make a lot of templates. When I started to write this book, modern browsers had problems supporting web components, but it's okay now! You can use them for sure. Second, please don't use any libraries to make web components. For example, jQuery has problems with the Shadow DOM components. It's always better to use JavaScript instead.

See you in the next chapter!