This add-on is operated by NoCoffee

The perfect tool to edit static pages

Last updated 02 October 2017

Boxcab is the little CMS for your Ruby on Rails Heroku application deserves. See it as PerchCMS for Heroku applications. Basically, it allows non-tech people to edit the content of pages through a nice UI.

There is nothing to host, no migration to run. It works with Rails 3, Rails 4 and Rails 5. The content can also be accessed via a RESTful API.

Don’t take our word for it, try the editor here.

Provisioning the add-on

Boxcab can be attached to a Heroku application via the CLI:

$ heroku addons:create boxcab
-----> Adding boxcab to sharp-mountain-4005... done, v18 (free)

Once Boxcab has been added, BOXCAB_SITE_HANDLE and BOXCAB_API_KEY variables will be available in the app configuration. This can be confirmed using the heroku config:get command.

$ heroku config:get BOXCAB_SITE_HANDLE
$ heroku config:get BOXCAB_API_KEY

Local setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service. Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command for each value that you want to add to your .env file.

$ heroku config:get BOXCAB_SITE_HANDLE -s  >> .env
$ heroku config:get BOXCAB_API_KEY -s  >> .env

Ruby on Rails installation

Boxcab works with any Ruby on Rails application from version 3.

Install the Boxcab gem by adding the following entry into your application Gemfile:

gem 'boxcab-rails'

Run the Boxcab installation generator and follow the instructions:

$ bundle install
$ heroku local:run rails generate boxcab:install

Start your application server with the following command:

$ heroku local:run rails server

Scenario 1: make the home page of your application editable

Open the controller in charge of rendering your home page and insert the following code (boxcab_pages_here) after the class definition:

class YourHomeController < ApplicationController
  ...
  boxcab_pages_here
  ...

Then, open the template of your view and wrap some text you want to make editable with our boxcab_content helper tag.

Example:

...
<!-- Previously: h2This is the title of my page/h2, now: -->
<h2><%= boxcab_content 'title', type: 'string', hint: 'Title of the home page', default: 'This is the title of my page' %></h2>
...

Now, commit your changes with Git and re-deploy your application on Heroku.

Preview your home page in your browser to register your page in the Boxcab editor.

$ heroku open

To edit the title of your home page, go to your Boxcab editor interface, select your page and click on the “Pencil” icon.

$ heroku addons:open boxcab

Happy editing!

Scenario 2: create a simple controller to display your static pages

This tutorial is largely inspired by the Treehouse article.

$ touch app/controllers/static_pages_controller.rb

Place the following in the app/controllers/static_pages_controller.rb file:

class StaticPagesController < ApplicationController
  boxcab_pages_here
  def show
    render template: "static_pages/#{params[:page]}"
  end
end

Add an entry in your config/routes.rb file:

Rails.application.routes.draw do
  get "/pages/:page" => "static_pages#show"
end

Now, let’s add the “About us” page.

$ mkdir app/views/static_pages
$ touch app/views/static_pages/about-us.html.erb

The view contains the following code:

<h1><%= boxcab_content "About us", type: "string" %></h1>
<img src="<%= boxcab_content "banner", type: "image", default: "http://placehold.it/400x100" %>" />
<div>
  <%= boxcab_content "body", type: "text", html: true do %>
  <p>Lorem ipsum....</p>
  <% end %>
</div>

Commit your changes and (re-)deploy your application on Heroku.

Register your page by previewing it:

$ open https://example.herokuapp.com/pages/about-us

To edit your “About us” page, go to your Boxcab editor interface.

$ heroku addons:open boxcab

Et voilà!

Scenario 3: integrate High Voltage

High Voltage is a Rails engine for static pages. Boxcab works smoothly with High Voltage. Simply use your boxcab_page and boxcab_content helper tags in your High Voltage views.

Removing the add-on

Boxcab can be removed via the CLI.

$ heroku addons:destroy boxcab
-----> Removing boxcab from sharp-mountain-4005... done, v20 (free)

Support

All Boxcab support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at contact@boxcab.io.