Polymer Starter Kit for Gobstones Web elements

A starting point for building elements for Gobstones Web.

Included out of the box:

• Polymer, Paper, Iron and Neon elements
• Unit testing with Web Component Tester
• End-to-end Build Tooling (including Vulcanize)
• Support for ES2015
• Deploy of docs and demo to gh-pages
• Deploy of bower module to github.

Demo

See the dummy demo

Tutorials

Check out the Polymer Starter Kit tutorials on polymer-project.org:

• Set up the PSK
• Create a page
• Deploy the PSK to the web

Getting Started

• Clone the dev branch on this repository.

Install dependencies

Quick-start (for experienced users)

With Node.js installed, run the following one liner from the root of your Polymer Starter Kit download:

npm install -g gulp bower && npm install && bower install

Prerequisites (for everyone)

The full starter kit requires the following major dependencies:

• Node.js, used to run JavaScript tools from the command line.
• npm, the node package manager, installed with Node.js and used to install Node.js packages.
• gulp, a Node.js-based build tool.
• bower, a Node.js-based package manager used to install front-end packages (like Polymer).

To install dependencies:

1. Check your Node.js version.

node --version

The version should be at or above 0.12.x.

2. If you don't have Node.js installed, or you have a lower version, go to nodejs.org and click on the big green Install button.

3. Install gulp and bower globally.

npm install -g gulp bower

This lets you run gulp and bower from the command line.

4. Install the starter kit's local npm and bower dependencies.

cd gs-element-starter && npm install && bower install

This installs the element sets (Paper, Iron, Platinum) and tools the starter kit requires to build and serve apps.

Development workflow

Serve / watch

gulp serve

This outputs an IP address you can use to locally test and another that can be used on devices connected to your network.

Run tests

gulp test:local

This runs the unit tests defined in the app/test directory through web-component-tester.

To run tests Java 7 or higher is required. To update Java go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and download JDK and install it.

Build & Vulcanize

gulp

Build and optimize the current project, ready for deployment. This includes vulcanization, image, script, stylesheet and HTML optimization and minification.

Application Theming & Styling

Polymer 1.0 introduces a shim for CSS custom properties. We take advantage of this in app/styles/app-theme.html to provide theming for your application. You can also find our presets for Material Design breakpoints in this file.

Read more about CSS custom properties.

Styling

1. main.css - to define styles that can be applied outside of Polymer's custom CSS properties implementation. Some of the use-cases include defining styles that you want to be applied for a splash screen, styles for your application 'shell' before it gets upgraded using Polymer or critical style blocks that you want parsed before your elements are.
2. app-theme.html - to provide theming for your application. You can also find our presets for Material Design breakpoints in this file.
3. shared-styles.html - to share styles between elements and index.html.
4. element styles only - styles specific to element. These styles should be inside the <style></style> inside template.

<dom-module id="my-list">
  <template>
    <style>
      :host {
        display: block;
        background-color: yellow;
      }
    </style>
    <ul>
      <template is="dom-repeat" items="{{items}}">
        <li><span class="paper-font-body1">{{item}}</span></li>
      </template>
    </ul>
  </template>
</dom-module>

These style files are located in the styles folder.

Unit Testing

Web apps built with Polymer Starter Kit come configured with support for Web Component Tester - Polymer's preferred tool for authoring and running unit tests. This makes testing your element based applications a pleasant experience.

Read more about using Web Component tester.

Dependency Management

Polymer uses Bower for package management. This makes it easy to keep your elements up to date and versioned. For tooling, we use npm to manage Node.js-based dependencies.

Components installed by Bower live in the app/bower_components directory. This location is specified by the .bowerrc file. Many projects which follow Yeoman conventions place the bower_components directory outside of the app directory and then mount it using a server. This causes problems for tools like Vulcanize and web-component-shards which rely on relative paths. We've chosen to simplify things and have bower_components live inside of app to resolve these issues.

Deploy

After a new push to the prod branch, an automatic deploy process will get started on TravisCI, generating:

• Docs and demos will be deployed to gh-pages
• A bower module ready to be used will be deployed on the master branch. This branch SHOULD NOT BE USED MANUALLY, only by TravisCI.

Frequently Asked Questions

Where do I customise my application theme?

Theming can be achieved using CSS Custom properties via app/styles/app-theme.html. You can also use app/styles/main.css for pure CSS stylesheets (e.g for global styles), however note that Custom properties will not work there under the shim.

A Polycast is also available that walks through theming using Polymer 1.0.

Where do I configure routes in my application?

This can be done via app/elements/routing.html. We use Page.js for routing and new routes can be defined in this import. We then toggle which <iron-pages> page to display based on the selected route.

Why are we using Page.js rather than a declarative router like <more-routing>?

<more-routing> (in our opinion) is good, but lacks imperative hooks for getting full control over the routing in your application. This is one place where a pure JS router shines. We may at some point switch back to a declarative router when our hook requirements are tackled. That said, it should be trivial to switch to <more-routing> or another declarative router in your own local setup.

Where can I find the application layouts from your Google I/O 2015 talk?

App layouts live in a separate repository called app-layout-templates. You can select a template and copy over the relevant parts you would like to reuse to Polymer Starter Kit.

You will probably need to change paths to where your Iron and Paper dependencies can be found to get everything working. This can be done by adding them to the elements.html import.

Something has failed during installation. How do I fix this?

Our most commonly reported issue is around system permissions for installing Node.js dependencies. We recommend following the fixing npm permissions guide to address any messages around administrator permissions being required. If you use sudo to work around these issues, this guide may also be useful for avoiding that.

If you run into an exception that mentions five optional dependencies failing (or an EEXIST error), you may have run into an npm bug. We recommend updating to npm 2.11.0+ to work around this. You can do this by opening a Command Prompt/terminal and running npm install npm@2.11.0 -g. If you are on Windows, Node.js (and npm) may have been installed into C:\Program Files\. Updating npm by running npm install npm@2.11.0 -g will install npm into %AppData%\npm, but your system will still use the npm version. You can avoid this by deleting your older npm from C:\Program Files\nodejs as described here.

If you get a browser console error indicating that an element you know you have installed is missing, try deleting the bower_components folder, then run bower cache clean followed by bower install to reinstall. This can be especially helpful when upgrading from a prior version of the Polymer Starter Kit.

If the issue is to do with a failure somewhere else, you might find that due to a network issue a dependency failed to correctly install. We recommend running npm cache clean and deleting the node_modules directory followed by npm install to see if this corrects the problem. If not, please check the issue tracker in case there is a workaround or fix already posted.

I'm having trouble getting Vulcanize to fully build my project on Windows. Help?

Some Windows users have run into trouble with the elements.html file in their dist folder not being correctly vulcanized. This can happen if your project is in a folder with a name containing a space. You can work around this issue by ensuring your path doesn't contain one.

There is also an in-flight issue where some are finding they need to disable the inlineCss option in our configuration for Vulcanize to correctly build. We are still investigating this, however for the time-being use the workaround if you find your builds getting stuck here.

How do I add new JavaScript files to Starter Kit so they're picked up by the build process?

At the bottom of app/index.html, you will find a build block that can be used to include additional scripts for your app. Build blocks are just normal script tags that are wrapped in a HTML comment that indicates where to concatenate and minify their final contents to.

Below, we've added in script2.js and script3.js to this block. The line <!-- build:js scripts/app.js --> specifies that these scripts will be squashed into scripts/app.js during a build.

<!-- build:js scripts/app.js -->
<script src="scripts/app.js"></script>
<script src="scripts/script2.js"></script>
<script src="scripts/script3.js"></script>
<!-- endbuild-->

If you are not using the build-blocks, but still wish for additional files (e.g scripts or stylesheets) to be included in the final dist directory, you will need to either copy these files as part of the gulpfile.js build process (see the copy task for how to automate this) or manually copy the files.

Licensing

Like other Google projects, Polymer Starter Kit includes Google license headers at the top of several of our source files. Google's open-source licensing requires that this header be kept in place (sorry!), however we acknowledge that you may need to add your own licensing to files you modify. This can be done by appending your own extensions to these headers.

Contributing

Polymer Starter Kit is a new project and is an ongoing effort by the Web Component community. We welcome your bug reports, PRs for improvements, docs and anything you think would improve the experience for other Polymer developers.