Pieces

Pieces is a gem that will take your HTML and CSS components and compile them into a static site or styleguide. It can work with or without rails.

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

Define the view of your application with reusable components. Even your layout is just another component. Use Pieces to pull together these components into websites, styleguides and mock ups.

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
How does Pieces work?
Create a UI styleguide for rails
Create a static site

Other links

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

How it works

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.

Using with rails

Want to create a styleguide or UI design pattern library for your rails app? If so you're in the right place. Styleguides pull together reusable components into micro site that documents how and when to use them.

To get started ensure you have added Pieces to your application's 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

Create 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.

pieces

Development

Runtime

Pieces

Build static sites and blogs

Produce styleguides for your rails applications

Mock up designs

Welcome early adopters

Table of Contents

Installation

How it works

Using with rails

Create static site