Pieces

This gem will take your HTML and CSS components and compile them into a static site.

Build static sites and blogs
Produce styleguides for your rails applications – read how to
Mock up designs

Define your HTML and CSS together

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

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 views as they are better known in the rails world.

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

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

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

<html>
  <head>
    <title>{{title}}</title>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

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

config/pieces.yml:

index:
  _pieces:
    - layouts/application:
        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/routes.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 pieces init

Now mount pieces in your config/routes.rb:

Rails.application.routes.draw do
  mount Pieces::Rails.new.mount, at: '/styleguide'
end

Edit your config/pieces.yml to demo some of your components.

Now boot up rails:

bundle exec rails s

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

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 pieces 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 pieces 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/application:
        _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/application.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)