Polymer
About the Tutorial Polymer.js is a JavaScript library created by Google that allows reusing the HTML elements for building applications with components.
This tutorial covers most of the topics required for a basic understanding of Polymer.js and to get a feel of how it works.
Audience This tutorial is designed for software programmers who want to learn the basics of Polymer.js and its programming concepts in a simple and easy way. This tutorial will give you enough understanding on the components of Polymer.js with suitable examples.
Prerequisites Before proceeding with this tutorial, you should have a basic understanding of HTML, CSS, JavaScript, Document Object Model (DOM) and any text editor. As we are going to develop web-based application using Polymer.js, it will be good the readers have understanding on how internet and web-based applications work.
Copyright & Disclaimer Copyright 2017 by Tutorials Point (I) Pvt. Ltd.
All the content and graphics published in this e-book are the property of Tutorials Point (I) Pvt. Ltd. The user of this e-book is prohibited to reuse, retain, copy, distribute or republish any contents or a part of contents of this e-book in any manner without written consent of the publisher.
We strive to update the contents of our website and tutorials as timely and as precisely as possible, however, the contents may contain inaccuracies or errors. Tutorials Point (I) Pvt. Ltd. provides no guarantee regarding the accuracy, timeliness or completeness of our website or its contents including this tutorial. If you discover any errors on our website or in this tutorial, please notify us at [email protected]
i
Polymer
Table of Contents
About the Tutorial ...... i
Audience ...... i
Prerequisites ...... i
Copyright & Disclaimer ...... i
Table of Contents ...... ii
1. POLYMER ─ OVERVIEW ...... 1
2. POLYMER ─ INSTALLATION ...... 2
Installing Polymer Using Polymer CLI ...... 2
Installing Polymer Using Bower ...... 3
Building for Deployment ...... 4
3. POLYMER ─ ELEMENTS ...... 5
App Elements ...... 6
Polymer - App Layout ...... 6
Polymer - App Route ...... 12
Iron Elements ...... 14
Iron A11y Keys ...... 15
Iron Ajax ...... 18
Iron Collapse ...... 20
Iron Image ...... 24
Iron Dropdown ...... 29
Iron Flex Layout ...... 32
Iron Form ...... 34
Iron Icon ...... 39
ii
Polymer
Iron Swipeable Container ...... 42
Paper Elements ...... 45
Paper Badge ...... 47
Paper Button ...... 51
Paper Card ...... 55
Paper Checkbox...... 59
Paper Drawer Panel ...... 62
Paper Dropdown Menu ...... 68
Paper Fab ...... 70
Paper Icon Button ...... 74
Paper Input ...... 77
Paper Listbox...... 80
Paper Material ...... 83
Paper Progress ...... 89
Paper Radio Button ...... 93
Paper Ripple ...... 95
Paper Slider ...... 99
Paper Spinner ...... 101
Paper Tabs ...... 104
Paper Toast ...... 107
Paper Toggle Button ...... 111
Google Web Components...... 114
Google Analytics Query ...... 115
Google Client Loader ...... 120
Google Chart ...... 122
Google Hangout Button ...... 125
iii
Polymer
Google Map...... 128
Google Signin ...... 132
Google Streetview Pano ...... 133
Google Youtube ...... 134
Gold Elements ...... 136
Gold CC CVC Input ...... 137
Gold CC Input ...... 140
Gold Email Input ...... 145
Gold Phone Input ...... 149
Neon Elements ...... 153
Platinum Elements ...... 156
Molecules Elements ...... 160
4. POLYMER ─ CUSTOM ELEMENTS ...... 167
Custom Element Lifecycle ...... 167
Element Upgrades ...... 169
Defining an Element ...... 169
Lifecycle Callbacks ...... 173
Declaring Properties ...... 173
Attribute Deserialization ...... 175
Configuring Boolean Properties ...... 175
Configuring Default Property Values ...... 175
Read-only Properties ...... 177
Reflecting Properties to Attributes ...... 181
Attribute Serialization ...... 181
iv
Polymer
5. POLYMER ─ SHADOW DOM & STYLING ...... 182
Shadow DOM and Composition ...... 182
Event Retargeting ...... 185
Shadow DOM Styling ...... 188
DOM Templating ...... 188
Style an Element's Shadow DOM ...... 189
Style Slotted Content ...... 191
Using Style Modules ...... 193
Use Custom Properties ...... 196
6. POLYMER ─ EVENTS ...... 198
Custom Events ...... 200
Gesture Events ...... 203
7. POLYMER ─ DATA SYSTEM ...... 210
Data Paths ...... 210
Data Flow Example ...... 211
Linking Two Paths ...... 215
Data Binding...... 216
v
Polymer 1. POLYMER ─ OVERVIEW
Polymer.js is a JavaScript library created by Google that allows reusing the HTML elements for building applications with components.
Polymer is an open-source JavaScript library developed by Google developers and was initially released on May 27, 2015. The stable release is 1.7.0 and it was released on September 29, 2016.
Why Use Polymer.js? It allows to create our own custom elements easily using the HTML, CSS, and JavaScript for adding interactions to the element.
It is created by Google that provides cross-browser compatible applications along with the web components.
It provides both one-way and two-way data binding.
It provides Polymer command line interface for managing the projects from simple components to complicated web applications.
Features of Polymer.js It is a JavaScript library built on top of the web standards APIs that allow building custom HTML elements.
It provides the polyfills (web component specifications) for creating our own customized and reusable elements.
It uses the web component standards for the creation of reusable widgets in web documents and web applications.
It uses Google material design for the development of hybrid mobile application.
It distributes the custom elements across the network and the users can use these elements with the help of HTML Imports.
6
Polymer 2. POLYMER ─ INSTALLATION
It's easy to configure Polymer in your system. Following are the two ways to install Polymer.
The Polymer CLI (Command Line Interface) The Bower
Installing Polymer Using Polymer CLI Step 1: Install Polymer using the following npm command.
npm install -g polymer-cli@next
Step 2: Check the successful installation and version using the following command.
polymer --version
If it has installed successfully, then it will show the version as:
0.18.0-pre.13.
Step 3: Create a directory with the name of your choice and switch to that directory.
mkdir polymer-js cd polymer-js
Step 4: To initialize your project, run the following command in your polymer-jsdirectory:
polymer init
After executing the above command, it will show something like this:
C:\polymer-js>polymer init ? Which starter template would you like to use? 1) polymer-1-element - A simple Polymer 1.0 element template 2) polymer-2-element - A simple Polymer 2.0 element template 3) polymer-1-application - A simple Polymer 1.0 application template 4) polymer-2-application - A simple Polymer 2.0 application 5) polymer-1-starter-kit - A Polymer 1.x starter application template, with navigation and "PRPL pattern" loading
7
Polymer
6) polymer-2-starter-kit - A Polymer 2.x starter application template, with navigation and "PRPL pattern" loading 7) shop - The "Shop" Progressive Web App demo Answer: 4
Step 5: Select the polymer-2-application from the above given options. Now, start your project using the following command.
polymer serve
Installing Polymer Using Bower
Step 1: To start from scratch using Bower method, install the Bower using the following command.
npm install -g bower
Step 2: Install the Polymer using the following command.
npm install -g polymer-cli@next
Step 3: Check the successful installation and version of Polymer, using the following command.
polymer --version
If it has installed successfully, then it will show the version as:
0.18.0-pre.13.
Step 4: To install the latest Polymer 2.0 RC release from bower, use the following command.
bower install Polymer/polymer#^2.0.0-rc.3
Step 5: Create a index.html file and add the following code in the
tag.// it loads the polyfills // it import Polymer
Step 6: Start your project using the following command.
polymer serve
8
Polymer
Building for Deployment To build your project for deployment, polymer build command is an easier way, which will minify, compile, or bundle your code depending on the command line flags.
To create a universal build that works on all browsers, use the following command.
polymer build --js-compile
The above command will build the project to build/default and you can start this directory, using the following command.
polymer serve build/default
Polymer 2.0 uses ES6 and HTML Custom Elements. For best practice, it is always good to use ES6 to browsers with full ES6 support and compile ES5 to old browsers that don't support ES6. The following table shows the best strategy for your project.
Strategy Easiest for cross-browser support Most optimal for WC v1 performance
Server Any server works, including static ones Differential serving required
Deployed Code ES5 transpiled ES6
Polyfill Loader webcomponents-es5-loader.js webcomponents-loader.js
9
Polymer 3. POLYMER ─ ELEMENTS
Polymer elements are a set of visual and non-visual elements designed to work with the layout, user interaction, selection, and scaffolding applications. These include everything from a simple button to a dialog box with neat visual effects. The following table shows different types of polymer elements.
Sr. Types & Description No.
app elements 1 The app elements are useful when building entire applications.
iron elements 2 These are the basic building blocks for creating an application.
paper elements 3 The paper elements are a set of UI components designed to implement Google's material design guidelines.
google Web components 4 The google Web component are a stock of web components for Google APIs & services.
gold elements 5 The gold elements are built for e-commerce-specific use cases.
neon elements 6 It is used for implementing animated transitions for Polymer elements using web animations.
platinum elements 7 The platinum elements provide features to turn your web page into a true webapp.
molecules elements 8 The molecule element helps to develop an application easily and is used to connect a group of plugins to the Polymer application.
10
Polymer
App Elements The app elements are useful while building an entire application. The following table lists different types of polymer elements. These components support features such as routing, data storage, and more.
Sr. No. Types & Description
app-layout 1 The app-layout elements are useful for building high-quality, responsive layouts just with markup.
app-route 2 These are for managing the routing within an app, mapping URLs to views.
Polymer - App Layout
The app-layout elements are comprised of components such as toolbars, drawers, and headers. These are used for building high-quality, responsive layouts just with markup. Some of the elements are listed in the following table.
Sr. Elements & Description No.
app-box 1 This element works as container and has scroll effects, visual effects based on the scroll position.
app-drawer 2 This is a navigation drawer which will slide in and out from left or right.
app-drawer-layout 3 This will position the app-drawer and other content.
app-grid 4 This is used for creating responsive and fluid grid layouts using custom properties.
app-header 5 This element works at the top of the screen as a container for app-toolbars and has scroll effects, visual effects based on the scroll position.
11
Polymer
app-header-layout 6 This element acts as a cover that positions the app-header and other content.
app-scrollpos-control 7 This element is used for saving and restoring the scroll position when multiple pages share the same document scroller.
app-toolbar 8 It is a horizontal toolbar which contains items that can be used for labeling, navigating, searching, and other actions.
Example To use app-layout elements you have to move into the project directory using the following command in the command prompt.
bower install PolymerElements/app-layout --save
The above command will install the app-layout elements in bower_components folder. Then, you have to import the file using tag in your index.htmlfile.
13
Polymer
Output Refresh the Polymer server and following will be the output.
Polymer - App Route The app-route element utilizes an object, which describes a state about the current route, via the route property. It will determine the state using pattern property and determines some data related to the route, and a tail that contains the rest of the route as shown in the following code.
14
Polymer
The explanation of the above instances is listed in the following table.
Sr. Field & Description No.
app-location 1 It is an element that provides synchronization between the browser location bar and the state of an app, and produces a route value.
Pattern 2 The route.path property is matched by comparing it to the pattern property.
app-route 3 It sets the data property with an object, whose properties correspond to the parameters in pattern property. It is responsive to bi-directional changes to the data objects they produce.
Tail 4 It represents the remaining part of the route state, after the pattern has been applied to a matching route.
Hashes vs Paths The portion of the URL pathname is used by an app-location route with the help of backend server. The app-location can be configured to use the hash part using the following attribute.
15
Polymer
Iron Elements The iron elements are used to create an application and are also called as core elements, when matched with the "Developer Preview" version.
The following table lists different types of iron elements:
Sr. No. Type & Description
iron-a11y-keys 1 These elements are used to process keyboard commands using cross-browser interface.
iron-ajax 2 The iron-ajax elements are useful in making the ajax calls.
iron-collapse 3 The iron-collapse elements are used to collapse a content. To show or hide the content use opened or toggle().
iron-image 4 These elements are used for displaying a single image.
iron-dropdown 5 These are low-level elements used to reveal the hidden dropdown content.
iron-flex-layout 6 These elements are useful to provide CSS flexible box layout.
iron-form 7 The iron-form element is an HTML element used to validate and submit any custom elements.
iron-icon 8 These elements are used to display a single icon.
iron-swipeable-container 9 It is a container that allows swapping of its nested children, i.e. native or custom elements.
Iron A11y Keys The
The keys attribute indicates by what combination of keys the event will be triggered. It accepts modifier keys such as Shift, Control, Alt, Meta and some common keyboard keys such
16
Polymer
as a-z, 0-9, F1-F12, Page Up, Page Down, Left Arrow, Right Arrow, Home, End, Escape, Space, Tab, and Enter.
All the keys should be shortened and should be in lowercase. For example, Right Arrow is for right, Page Up is for pageup, Control is for ctrl, Escape is for esc, F5 is for f5, etc.
Example To use the iron-a11y-keys element, navigate to your project folder in the command prompt and use the following command.
bower install PolymerElements/iron-a11y-keys --save
The above command installs the iron-a11y-keys element in bower_components folder. Next, import the iron-a11y-keys file in your index.html using the following command.
The following example demonstrates the use of iron-a11y-keys element.
Press any of the below keys and check console.
shift + enter, enter, esc, pageup, pagedown, up, down, left, right, space.
17
Polymer
Output To run the application, navigate to your project directory and run the following command.
polymer serve
18
Polymer
Now, open the browser and navigate to http://127.0.0.1:8081/. Following will be the output.
Iron Ajax The
When you set auto to true, a request is made by an element when its properties url, params, or body are changed. As you can see, the component has several attributes available:
url: An attribute where you place the url to the API endpoint.
params: An attribute where you can pass the JSON with the request parameters.
handle-as: Specifies what data must be stored in the response property. By default, the data is stored in the json format.
19
Polymer
on-response: An attribute which can tell the iron-ajax component by what method the response is handled.
Changing multiple attributes sequentially causes automatically generated requests to be debounced.
You can call generateRequest on the element to trigger a request explicitly.
Example In the following example, we have a link to the iron-ajax and paper-input components used from the CDN.
You typed: {{q}} Echo: {{echo}}
Output To run the application, navigate to your project directory and run the following command:
polymer serve
Now open the browser and navigate to http://127.0.0.1:8081/. Following will be the output.
21
Polymer
Iron Collapse The
The max-height/max-width of the collapsible element is automatically adjusted by the iron- collapse element.
The custom properties and mixins to be used for styling is as follows:
--iron-collapse-transition-duration: It is the duration of the animation transition. The default value is 300ms.
Example To implement iron-collapse element, navigate to your project folder in the command prompt and use the following commands:
bower install PolymerElements/iron-collapse --save bower install PolymerElements/paper-toggle-button --save
The above command installs both the elements in bower_components folder. Then you have to import both the files in your index.html file as shown below:
The following example demonstrates the use of iron-collapse element:
22
Polymer
Iron Collapse Example
This is polymerjs iron-collapse.
23
Polymer
Output To run the application, navigate to your project directory and run with the following command:
polymer serve
Now open the browser and navigate to http://127.0.0.1:8081/. Following will be the output.
When you click the toggle button, following will be the output.
24
Polymer
Iron Image The
The sizing option either crops (cover) or letterboxes (contain) the image to fit within its specified size whereas the preload option blocks the image from getting rendered. Meanwhile, you can either use the element's CSS background-color as the placeholder or you can prefer a data-URI. The fade option fades out the image/color of the placeholder after rendering the image.
The
Example To use the iron-image element, install the iron-image element using bower and import it in your index.html file. The following code displays a plain image.
25
Polymer
Iron-Image Example
You will get the output as shown in the following screenshot.
Use the option sizing = "cover"
Example using sizing = "cover"
You will get the output as shown in the following screenshot.
Use the option sizing = "contain"
Polymer
Example using sizing = "contain"
You will get the output as shown in the following screenshot.
The following code displays the grey background as well as base-64 encoded placeholder until the image is loaded.
The following code fades out the image after the image is rendered. 28
Polymer
The following table shows the custom properties of
Sr. No. Custom properties & Description Default
--iron-image-placeholder: 1 {} It is a mixin to be used to style for #placeholder.
--iron-image-width: 2 auto Use this property to set the width of the image, wrapped by the iron-image.
--iron-image-height: 3 auto Use this property to set the height of the image, wrapped by the iron-image.
Iron Dropdown
The
The
Example To implement iron-dropdown element, navigate to your project folder in the command prompt and use the following command.
bower install PolymerElements/iron-dropdown --save
The following example demonstrates the use of iron-dropdown element:
29
Polymer
Iron-dropdown Example
Hello !!!
This is an iron-dropdown
example of Polymerjs.
As shown in the example, the class named .dropdown-content will be hidden till you call an open method on an element.
30
Polymer
Output To run the application, navigate to your project directory and run the following command:
polymer serve
Now open the browser and navigate to http://127.0.0.1:8081/. When you click the Click me button, a dropdown will be displayed.
Iron Flex Layout The
The flexbox can be used in two different ways:
Layout classes: It is a stylesheet providing certain rules of class-based flexbox where the layout properties are directly defined in the markup.
Custom CSS mixins: It is a stylesheet containing custom CSS mixins, which we can apply inside a CSS rule with the help of @apply function.
Example To use the iron-flex-layout element, navigate to your project folder in the command prompt and use the following command:
bower install PolymerElements/iron-flex-layout --save
The above command installs the iron-flex-layout element in bower_components folder. Next, import the iron-flex-layout file in your index.html using the following command:
The following example demonstrates the use of iron-flex-layout element: 31
Polymer
Iron-Flex-Layout
Delta
Epsilon (flex)
Zeta
32
Polymer
Output To run the application, navigate to your project directory and run the following command:
polymer serve
Now open the browser and navigate to http://127.0.0.1:8081/. Following will be the output.
Iron Form
The
By default, the native button element submits the following form:
33
Polymer
End of ebook preview If you liked what you saw… Buy it from our store @ https://store.tutorialspoint.com
34