Boxcab
Last updated October 02, 2017
The Boxcab add-on is currently in beta.
Table of Contents
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.
More information on the boxcab_content
tag can be found in our online documentation
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
If you don’t preview the page in production, Boxcab won’t be able to generate the form used to edit the content of your page.
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.
It takes a few seconds for our platform to process your page so you might have to wait a little before your pages show up in the editor.
$ 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.
This will destroy all associated data and cannot be undone!
$ 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.