Support for Polymer-enabled web components in Rails
Ruby
Latest commit f63b3e9 Jul 28, 2014 @nevir disable for now.
Permalink
Failed to load latest commit information.
lib
.gitignore Application template & bare bones gem Jun 13, 2014
Gemfile
LICENSE.txt Application template & bare bones gem Jun 13, 2014
README.md
Rakefile
application-template.rb gumbo 1.1 release ready Jun 23, 2014
polymer-rails.gemspec

README.md

THIS PROJECT DOES NOT WORK YET

polymer-rails

Make your Rails projects sing with Polymer and sprockets-htmlimports!

Please note that polymer-rails is very much an alpha project at this point. You'll be living on the bleeding edge; pulling gems directly from GitHub, fending off bugs, and dealing with half-implemented behaviors. That's the joy of open source!

Getting Started

New Rails Projects

You can make use of the application template to quickly whip up new Polymer-enabled projects:

rails new -m https://raw.githubusercontent.com/nevir/polymer-rails/master/application-template.rb PROJECT

Existing Projects

Add polymer-rails (and bleeding edge dependencies) to your Gemfile:

gem 'polymer-rails', git: 'https://github.com/nevir/polymer-rails'
gem 'sprockets-htmlimports', git: 'https://github.com/nevir/sprockets-htmlimports'

Then initialize it via:

rails generate polymer:init

Before initializing your project, you may want to read on to understand the flags you can pass, and how they affect the project layout.

What's Different

polymer-rails projects introduce a modified directory structure:

app/components

The bread and butter of your newly Polymerized app: all of your app's web components should be placed here.

Note that this directory is added to the Sprockets paths, so anything under it is relative to the /assets URL by default.

vendor/assets/components

Third party components (managed by Bower) reside here.

To add a dependency, modify your bower.json, and then run bower install. Cake!

app/assets/manifests (optional)

In this new world of web components, you should find that very little code ends up under app/assets/[javascripts|stylesheets]. To ease that transition, polymer-rails combines your asset manifests into this single directory.

Or, if you would rather not combine your manifests, polymer-rails will plunk the HTML import manifests into app/assets/components.

This is only performed for projects generated via the application template, or with the --combine-manifests option of the polymer:init generator.

app/assets/(components|manifests)/application.html

Like you should be used to with the other manifests, this file manages your app-wide dependencies. Simply <link href="..." rel="import"> any dependency, and Sprockets will take care of the rest.

Note that there is currently no support for require_tree style imports! You'll have to import each component directly.

jQuery & Turbolinks Begone!

The DOM is sexy, you don't need no silly abstractions any more, right?

Projects generated via the application template do not include jQuery or turbolinks. You can also use --no-default-js and --no-turbolinks to handle this when running the polymer:init generator.

Ok, Now What? (Component Generator)

polymer-rails also includes a component generator to make your life easy:

rails generate polymer:component MyComponent

And, like any dutiful generator, it also allows for you to define a quick skeleton of your component by defining properties:

rails generate polymer:component BetterComponent foo:string bar:object

Hell, it even supports slim templates if you have slim-rails (>= 2.1.5) installed!

Configuring polymer-rails

Take a look at config/initializers/polymer.rb for the options you can configure.