Pieces

Pieces is a gem that will take your HTML and CSS components and compile them into a static site or styleguide.

Build static sites and blogs
Produce styleguides for your rails applications
Mock up designs

With Pieces, you define the view of your application with components. Even your layout is just another component.

Welcome early adopters

I'd really appreciate feedback so please do try Pieces out for your current or next project. Obviously it's new and changing but I adhere very closely to semantic versioning and your styleguide should be a safe place to try new things. Thanks in advance, Luke.

Installation

If installing Pieces into a rails app, add it to your Gemfile:

gem 'pieces'

If building a standalone site, install globally:

gem install pieces

Quick example

Let's start by defining some "pieces", or components, or views as they are better known in the rails world. You'll notice Pieces looks for files in the same places rails does.

app/views/article/article.html.erb:

<article class="article">
  <h1 class="article__title"><%= title %></h1>
  <div class="article__content"><%= content %></div>
</article>

Ideally you should have a one to one relationship between components, and stylesheets. For example, .article should be defined like so.

app/assets/stylesheets/components/article.css:

.article {
  padding: 1em;
}

.article__content {
  padding-top: 1em;
}

You can use .css, .scss, .sass and .less with Pieces. In fact anything supports by Sprockets since that is what we use under the hood.

We also need to pull this stylesheet into your styleguide. By default pieces will look for pieces.css.

app/assets/stylesheets/pieces.css:

/*= require_tree ./components */

And we need a layout to pull the components together.

app/views/layouts/pieces.html.erb:

<html>
  <head>
    <title>{{title}}</title>
    <link rel="stylesheet" src="/assets/pieces.css" />
  </head>
  <body>
    <%= yield %>
  </body>
</html>

We pull the pieces together with a configuration file. Here you can define nested components and data to be used to generate a static site.

config/pieces.yml:

index:
  _pieces:
    - layouts/pieces:
        title: 'My Articles'
        _pieces:
          - article: { title: 'A title', content: '<p>Content.</p>' }
          - article: { title: 'Another title', content: '<p>More content.</p>' }

With these three files in place and having installed pieces on your system (gem install pieces) you can run:

pieces server

Now visit http://localhost:8080 to see your site! If you change your config/pieces.yml or views they will be reflected on the site.

Use as styleguide for rails

Firstly, ensure you have added Pieces to your Gemfile:

gem 'pieces'

Next you need to initialize your application to use Pieces:

bundle
bundle exec rails g pieces:rails:install

Edit your config/pieces.yml to demo some of your components. Please see the examples in this README as to how it should look. Detailed documentation coming soon. Thanks for your patience!

Now boot up rails:

bundle exec rails s

And then visit http://localhost:3000/styleguide

To build a static version of your site:

bundle exec pieces build

This will build your styleguide into build/.

You can also run pieces server rather than rails for faster development:

bundle exec pieces s

And then visit http://localhost:8080

Do you use vagrant?

If you do you should update Pieces::Rails in your config/routes.rb as follows:

mount Pieces::Rails.mount(force_polling: true), at: '/styleguide' unless Rails.env.production?

This will tell listen, the gem that watches for changes, to poll your app for changes. This is required for vagrant!

Create new static site

To create a new static site with Pieces:

gem install pieces
pieces init hello_world

This will install config/pieces.yml, a layout and example header and footer into hello_world/ for you.

Once you've built the components and routes for your site all you have to do is run:

pieces build

Your site will be built into build/ directory. You can then use these HTML files for your site.

Whilst developing you won't want to keep running pieces build. Pieces comes with a server inbuilt that reloads everytime you make a change.

To run it:

pieces server

Now visit http://localhost:8080 in your browser.

Configuration

Using configuration found in config/pieces.yml Pieces' will compile your modular components ala BEM (or whatever you prefer) into a static HTML site.

At the top level of your pieces.yml you define your output files, or "routes". The following example will build both index.html and about.html.

index:
  _pieces:
    - intro: { title: 'Welcome to my site' }

about:
  _pieces:
    - intro: { title: 'About me' }

Both index.html and about.html make use of a piece called "intro". This piece will be found in either app/views/intro.html.*, app/views/intro/intro.html.* or app/views/application/intro.html.*. The * can be any format supported by tilt.

You can generate your HTML into directories quite easily:

portfolio/a-client:
  _pieces:
    - carousel: {}
    - case_study: {}
portfolio/another-client:
  _pieces:
    - carousel: {}
    - case_study: {}

Likewise you can structure your components in directories:

about:
  _pieces:
    - header: {}
    - copy/intro: {}
    - galleries/photo: {}
    - footer: {}

"copy/intro" and "galleries/photo" will be found in app/views/copy/intro.html.* and app/views/galleries/photo.html.* respectively.

You can place your content in a layout quite easily with nested pieces.

about:
  _pieces:
    - layouts/pieces:
        _pieces:
          - header: {}
          - copy/intro: {}
          - galleries/photo: {}
          - footer: {}

The child pieces will be rendered in order and passed into the parent "layouts/application" piece as yield. If you had app/views/layouts/pieces.html.erb then you can call yield like so:

<html>
  <body>
    <%= yield %>
  </body>
</html>

More Examples

Original example using .erb and .mustache (liek wtf!)
Boilerplate example used by pieces init
Rails example using Pieces as a styleguide

Contributing

Fork it ( https://github.com/drpheltright/pieces/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Author

Luke Morton (again)