Misc Projects

This is a polymer web app that is based around the polymer starter kit. I'll maintain this repo sporadically as and when I have time to work on little cool bits of code that I think of.

Included out of the box:

• Polymer, Paper, Iron and Neon elements
• Material Design layout
• Routing with Page.js
• Unit testing with Web Component Tester
• Optional offline setup through Platinum Service Worker elements
• End-to-end Build Tooling (including Vulcanize)
• Recipes for ES2015 support, Polymer performance, using Chrome Dev Editor, Deploying to GitHub Pages, Deploying to Firebase, and Mobile Chrome Apps

Demo

• Misc Projects is currently live at 4lex.nz/misc-projects

Get the code

Download and extract Polymer Starter Kit to where you want to work. The project comes in two flavours - Light and Full.

Beginners: Try Polymer Starter Kit Light. This doesn't require any extra dependencies nor knowledge of modern front-end tooling. This option is good for prototyping if you haven't build a Polymer app before.

Intermediate - Advanced: Use the full version of Polymer Starter Kit. This comes with all the build tools you'll need for testing and productionising your app so it's nice and lean. You'll need to run a few extra commands to install the tools we recommend but it's worth it to make sure your final app is super optimised.

⚠️ Important: Polymer Starter Kit, and Polymer Starter Kit Light, both contain dotfiles (files starting with a .). If you're copying the contents of the Starter Kit to a new location make sure you bring along these dotfiles as well! On Mac, enable showing hidden files, then try extracting/copying Polymer Starter Kit again. This time the dotfiles needed should be visible so you can copy them over without issues.

Rob Dodson has a fantastic PolyCast video available that walks through using Polymer Starter Kit. An end-to-end with Polymer and Polymer Starter Kit talk is also available.

If you want to use what I've made so far, or contribute:

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 polymer-starter-kit && 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 linting as well as vulcanization, image, script, stylesheet and HTML optimization and minification.

Deploying to Firebase

The app doesn't require a database at the moment, but it's useful to know how to deploy it if need be.

See detail recipe

Service Worker

Polymer Starter Kit offers an optional offline experience thanks to Service Worker and the Platinum Service Worker elements. New to Service Worker? Read the following introduction to understand how it works.

Our optional offline setup should work well for relatively simple applications. For more complex apps, we recommend learning how Service Worker works so that you can make the most of the Platinum Service Worker element abstractions.

Enable Service Worker support?

To enable Service Worker support for Polymer Starter Kit project use these 3 steps:

1. Uncomment Service Worker code in index.html

<!-- Uncomment next block to enable Service Worker support (1/2) -->
<!--
<paper-toast id="caching-complete"
             duration="6000"
             text="Caching complete! This app will work offline.">
</paper-toast>

<platinum-sw-register auto-register
                      clients-claim
                      skip-waiting
                      on-service-worker-installed="displayInstalledToast">
  <platinum-sw-cache default-cache-strategy="networkFirst"
                     cache-config-file="cache-config.json">
  </platinum-sw-cache>
</platinum-sw-register>
-->

2. Uncomment Service Worker code in elements.html

<!-- Uncomment next block to enable Service Worker Support (2/2) -->
<!--
<link rel="import" href="../bower_components/platinum-sw/platinum-sw-cache.html">
<link rel="import" href="../bower_components/platinum-sw/platinum-sw-register.html">
-->

3. Uncomment 'cache-config' in the runSequence() section of the 'default' gulp task, like below: (gulpfile.js)

// Build Production Files, the Default Task
gulp.task('default', ['clean'], function (cb) {
  runSequence(
    ['copy', 'styles'],
    'elements',
    ['jshint', 'images', 'fonts', 'html'],
    'vulcanize', 'cache-config',
    cb);
});

Filing bugs in the right place

If you experience an issue with Service Worker support in your application, check the origin of the issue and use the appropriate issue tracker:

• sw-toolbox
• platinum-sw
• platinum-push-notifications-manager
• For all other issues, feel free to file them here.

I get an error message about "Only secure origins are allowed"

Service Workers are only available to "secure origins" (HTTPS sites, basically) in line with a policy to prefer secure origins for powerful new features. However http://localhost is also considered a secure origin, so if you can, developing on localhost is an easy way to avoid this error. For production, your site will need to support HTTPS.

How do I debug Service Worker?

If you need to debug the event listener wire-up use chrome://serviceworker-internals.

What are those buttons on chrome://serviceworker-internals?

This page shows your registered workers and provides some basic operations.

• Unregister: Unregisters the worker.
• Start: Starts the worker. This would happen automatically when you navigate to a page in the worker's scope.
• Stop: Stops the worker.
• Sync: Dispatches a 'sync' event to the worker. If you don't handle this event, nothing will happen.
• Push: Dispatches a 'push' event to the worker. If you don't handle this event, nothing will happen.
• Inspect: Opens the worker in the Inspector.

Development flow

In order to guarantee that the latest version of your Service Worker script is being used, follow these instructions:

• After you made changes to your service worker script, close all but one of the tabs pointing to your web application
• Hit shift-reload to bypass the service worker as to ensure that the remaining tab isn't under the control of a service worker
• Hit reload to let the newer version of the Service Worker control the page.

If you find anything to still be stale, you can also try navigating to chrome:serviceworker-internals (in Chrome), finding the relevant Service Worker entry for your application and clicking 'Unregister' before refreshing your app. This will (of course) only clear it from the local development machine. If you have already deployed to production then further work will be necessary to remove it from your user's machines.

Disable Service Worker support after you enabled it

If for any reason you need to disable Service Worker support after previously enabling it, you can remove it from your Polymer Starter Kit project using these 4 steps:

1. Remove references to the platinum-sw elements from your application index.
2. Remove the two Platinum Service Worker elements (platinum-sw/..) in app/elements/elements.html
3. Remove 'precache' from the list in the 'default' gulp task (gulpfile.js)
4. Navigate to chrome://serviceworker-internals and unregister any Service Workers registered by Polymer Starter Kit for your app just in case there's a copy of it cached.

Yeoman support

generator-polymer now includes support for Polymer Starter Kit out of the box.

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.

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.