Sections for Rails

Build Status Code Climate Coverage Status Dependency Status

A component-oriented infrastructure for the view layer of Ruby on Rails applications.

A section organizes all assets (DOM, styling, behavior, tests etc) for a particular component of a web site (a menu, a navbar, a slideshow etc) together. This makes development easier, components more reusable, and large code bases more managable.

Example

A navigation menu (as an example for a component) within a web site consists of HTML, CSS, and JavaScript code, image resources, as well as unit tests. Traditionally, these files are defined in a directory like this:

/app/assets/images/background.gif                   # Background image.
           /javascripts/menu.js                     # Logic for the menu.
                       /templates/entry.jst.ejs     # Client-side template for menu entries.
           /stylesheets/menu.css                    # Styling.
    /views/shared/_menu.html.erb                    # Server-side template.
/spec/javascripts/menu_spec.js                      # Unit tests.

Sections_rails allows to define these assets together, as a section, inside the /app folder:

/app/sections/menu/_menu.html.erb
                   background.gif
                   entry.jst.ejs
                   menu.css
                   menu.js
                   menu_spec.coffee

To embed this menu into a page, simply do this in your view:

<%= section :menu %>

This command inserts the partial as well as the JS and CSS files from /app/sections/menu into the page.

It does the right thing in all circumstances: In development mode it inserts the individual files into the page, in production mode they are included into the compiled output. And when the menu folder is deleted or moved to another page, all assets of the menu are cleanly deleted or moved with it!

Example applications

The gem source comes with a bundled example Rails app in the demo directory. Start it up and check it out! The source code for the sections is here.

Installation

In your Gemfile: gem 'sections_rails', then set up the directory structure:

$ rails generate sections

The generator

  • creates a new folder /app/sections, in which you put the source code for the different sections.

  • adds the folder /app/sections to the asset pipeline by inserting this line into your application.rb file:

    config.assets.paths << 'app/sections'

  • optionally creates a demo section called hello_world that you can try out as described below.

The current implementation requires two empty asset container files: application_sections.js and application_sections.css. Make sure you require them from your main application.js and application.css files. They are used only when running rake assets:precompile during deployment, should be checked into your code repository, and stay the way they are.

Usage

To show the "hello_world" section created by the sections generator on a page:

<%= section :hello_world %>

If your section renders itself completely in JavaScript, you can omit its partial file. In this case, the sections helper creates an empty div with the section name as its class.

<div class="hello_world"></div>

By default, a section automatically includes partials, css, and js files with the section name if they exist. This convention can be overridden.

Customizing the filename of the section's partial.

<%= section :hello_world, partial: 'another_partial' %>

Customizing the filename of the assets

To tell the section to use foobar.js instead of hello_world.js:

<%= section :hello_world, js: 'foobar.js' %>

Omitting assets

Sections can be told not not include their css or js file when rendered.

<%= section :hello_world, css: false %>

Using additional assets in sections

Sections can contain additional assets, like font or image files. You have to provide the full asset path to use them, even from within the section in which they are stored. For example, to show a file logo.png that is stored in a section called layout:

<%= image_tag 'layout/logo.png' %>

Make sure you add custom extensions like png to the config.assets.precompile setting in config/environments/production.rb, otherwise the asset pipeline will ignore them.

Providing parameters to the partial

<%= section :hello_world, locals: { message: 'Greetings!' } %>

Inline blocks for sections.

You can provide a block to the section:

<%= section :info_window do %>
  <h1>  inline  </h1>
  <div> block   </div>
  <p>   content </p>
<% end %>

This block can be included into the serverside partial of the section using yield.

Creating new sections.

To create a new section, simply create a new folder under /app/sections. There is also a generator for your convenience, which creates a whole scaffolded section.

$ rails generate section admin/chart

Unit tests for sections

Sections should also contain unit test files for the section.

To run your section tests using Konacha, create a symlink to app/sections in spec/javascript.

Troubleshooting

My section contains a file that doesn't show up on production

Rails sometimes doesn't precompile static files (for example images) in certain directories. To fix this, for example if your sections contain GIF files, tell Rails to precompile files of this type by adding this line to your config/production.rb file:

config.assets.precompile += %w( *.gif )

How to contribute

Send unit-tested pull requests! The unit tests of this project are run using rake.

Roadmap

  • Support for multiple application assets, for example page-specific compiled asset files instead of one global one.
  • Support for serverside controller logic for sections, for example by integrating with https://github.com/apotonick/cells.
  • More natural integration into the asset pipeline.

Authors