JosefJezek
7/26/2015 - 12:34 PM

Polymer 1.0 : Custom elements

Polymer 1.0 : Custom elements

Polymer 1.0 : Custom elements

Simplest possible workflow

Minimal steps required to create a custom elemenet in Polymer 1.0, without any aid from tools like Yeoman and Gulp.

I have used the Quick tour of Polymer as a reference.

Prerequisites

  • Install Node.
  • Install a light weight HTTP server
    npm install -g serve

Project setup

DescriptionCommand_____________________________
Install or update Bowernpm install -g bower
npm update -g bower
Create a project foldermkdir my-project
cd my-project
Init a new project with Bowerbower init
Install Polymer + web-componentsbower install --save Polymer/polymer
Create file for the custom element and
append code listed below
touch greeting-element.html
Create index.html and
append code listed below
touch index.html
Start the HTTP serverserve
... or, if you're on a Mac, you can instead use the python SimpleHttpServerpython -m SimpleHTTPServer 3000
Open browser with URLhttp://localhost:3000/
Output should beHello Stranger!
Hello Leif!
Updating packagesbower update

greeting-element.html

Code to create the custom element.

<link rel="import" href="bower_components/polymer/polymer.html">
<dom-module id="greeting-element">
  <style>
    :host {
      display: block;
    }
    h1 {
      color: blue;
    }
  </style>
  <template>
    <h1>Hello <span>{{greeting}}</span>!</h1>
  </template>
  <script>
    Polymer({
      is: 'greeting-element',

      properties: {
        greeting: {
          type: String,
          value: "Stranger"
        }
      }
    });
  </script>
</dom-module>

index.html

Import the greeting-element, <link rel="import" href="greeting-element.html"></link>, into index.html and start your custom element.

<!DOCTYPE html>
<html>
<head>
  <title>Example Polymer custom element</title>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, minimum-scale=1.0, initial-scale=1, user-scalable=yes">

  <script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
  <link rel="import" href="greeting-element.html"></link>
</head>
<body>
  <greeting-element></greeting-element>
  <greeting-element greeting="Leif"></greeting-element>
</body>
</html>

Create Polymer element with Yeoman element generator

Using the Yeoman element generator requires us to follow the folder layout from a Yeoman generated Polymer project. So before we can create a Yeoman element, we must scaffold a new Polymer project using generator-polymer.

As an alternative to using Yeoman to scaffold your project, you can download the Polymer Starter Kit and skip the next section.

Yeoman generator for Polymer projects

generator-polymer is a scaffolding tool for Yeoman, which generates a sample Polymer 1.0 project using Polymer Start Kit, letting you easily create and customize Polymer (custom) elements via the command-line and import them using HTML Imports. This saves you time writing boilerplate code so you can start writing up the logic to your components straight away. Use the following steps to set up a new Polymer app, generating all the boilerplate you need to get started.

DescriptionCommand______________________________
Install or update toolsnpm install -g yo bower grunt-cli
npm update -g yo bower grunt-cli
Install or update gulpnpm install -g gulp
npm update -g gulp
Install or update Yeoman generator for Polymer projectsnpm install -g generator-polymer
npm update -g generator-polymer
Create a project foldermkdir my-project
cd my-project
Sets up a new Polymer appyo polymer
Start the HTTP servergulp serve
Open browser with URLhttp://localhost:3000/

A short introduction to generator-polymer is provided here: Setting up your Production-ready Polymer 1.0 Application Development

Create Polymer element with Yeoman element generator

DescriptionCommand______________________________
Generate element.yo polymer:el yo-greeting-element
The generated element,yo-greeting-element.html is created in folder
./app/elements/yo-greeting-element
If you don't wish to use the standard folder layout, go ahead and move the generated element to another folder (but remember to update the href in line 1 of the generated html).

Create reusable Polymer element with Yeoman seedelement generator

Generates a reusable polymer element based on the seed-element workflow. This should only be used if you're creating a standalone element repo that you intend to share with others via bower. If you're just building a Polymer app, stick to the Element generator.

DescriptionCommand______________________________
Install or update tools and Polymer generatornpm install -g yo bower grunt-cli
npm update -g yo bower grunt-cli
Install or update Yeoman generator for Polymer projectsnpm install -g generator-polymer
npm update -g generator-polymer
Create a project foldermkdir my-project
cd my-project
Scaffolding Polymer seed-elementyo polymer:seed my-seed-element
Install Polyservenpm install -g polyserve
npm update -g polyserve
Start Polyservepolyserve
Open browser at
localhost:8080/components/my-seed-element/
Publish to reusable element to github

Useful Bower commands

Command_______________________________________Description
bower initCreate new project in working dir
bower installInstall package dependencies from bower.json in working dir
bower install polymer --savePolymer + web-components. Always on an new project
bower install polymerelements/paper-elements --saveInstall and add add package dep to bower.json in working dir,
bower install polymerelements/iron-elements --saveAll elements in package iron-elements.
bower install --save PolymerElements/paper-buttonOne particular element.
bower info polymerelements/paper-elementsPackage info
bower info GoogleWebComponents/google-mapComponent info
bower updateUpdate package dependecies in project
bower uninstall paper-elements --removeRemove package from project
bower uninstall paper-icon-button --removeRemove component from project
bower list polymerelements/paper-elementsShow package info
bower list paper-icon-buttonShow component info
bower searchSearch bower db for dependency, e.g. bower search jquery
bower pruneUninstall dependencies not listed in bower.json. As an alternative; just delete the bower_components folder and run bower install
bower register <component> git://github.com/<user>/<component>.gitRegister component, see: http://bower.io/docs/creating-packages/#register
bower infoGet info about registered component

Some useful links