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)