Code Climate

Cardboard is a simple CMS Engine for your Rails 4 applications.


  • Build for Rails 4
  • Make your site and your admin area the standard rails way (no complex engines)
  • Create pages and site settings in seconds
  • Repeatable page parts
  • Write your views in haml/slim/erb...! (no restrictive DSL or templating language)
  • Your customers will love the UI/UX
  • Super easy to extend and customize
  • It's like your favorite admin interface gem just had a baby with a CMS

alt text

Updating from 0.2 -> 0.3

Some changes were made to the database. Before updating make sure to have a look at the new migration


  • An authentication solution. For example, here is what you need to do to get Devise installed.
  • imagemagick (on mac do brew install imagemagick)
  • Rails 4 and Ruby 2.0


Add the gem to the Gemfile

gem "cardboard_cms"

And run bundle install.

Run the generator to install cardboard and it's migrations:

rails g cardboard:install
rake db:migrate

Edit your config/cardboard.yml file then run

rake cardboard:seed


Get a page

Add a file in your app/views/pages (or app/views/templates) with filename matching the identifier of the page. Inside this file you can access the page with:


Fetch a page part


Fetch a repeatable page part

Repeatable parts returns an active record collection. This means that regular Rails methods such as where, limit, first, each, etc can be used on page parts

- current_page.get('slideshow').each do |slide|
  p= image_tag slide.attr('image1').thumb('600x300').url, alt: slide.attr('description') if slide.attr('image1')

Fetch a single field

If this part is not repeatable you can use both

# Or

Image Fields methods

Images returned by image type fields are Dragonfly objects. As such, it's possible to edit them directly from the view.

if image = current_page.get('intro.image1')
  image.url                 # URL of the modified image
  image.thumb('40x30#').url  # resize, crop if necessary to maintain aspect ratio (centre gravity)
end # Hint: remember to check if image is not nil before calling methods on it

More options and methods are available at Dragonfly's Documentation

File field methods

Similarly to images, files are also Dragonfly objects. This allows such methods as:

file.format              # => :pdf                # => "some.pdf"
number_to_human_size(file.size) # => "486 KB"

Create Pages

To add pages to cardboard edit config/cardboard.yml. See an sample cardboard.yml in

    title: Default page title
        repeatable: true
            type: image
            required: true
            default: CrashTest.jpg
            type: rich_text

pages, parts and fields take identifiers (home_page, slideshow and image1) used to reference the data form the views. Choose these names carefully!


Each page section starts with the name of it's unique identifier. This name is used to reference the page in the code an thus should not change throughout the life of the project.

Key Type Default Definition
parts hash nil a list of page parts
title string identifier name of the page as shown in the nav bar
position integer auto-increment position of the page on the nav bar (the lowest position is the home page!)
parent_id string nil identifier of the parent page (used for nested pages)
controller_action string pages#identifier go to a specific controller example "blog#index". In that case, the page identifier is passed in the params


Templates are declared exactly like pages. They allow for the creation of pages directly from the admin interface. One key difference between templates and pages is the location of the view files which will be under app/views/templates.


Each part sub-section starts with the name of it's unique identifier. This name is used to reference the part in the code an thus should not change throughout the life of the project.

Key Type Default Definition
fields hash nil list of fields that make this part's form
position integer auto-increment position of the part on the admin page
repeatable boolean false can the client add multiple of these parts (example a slide in a slideshow)


Each field sub-section starts with the name of it's unique identifier. This name is used to reference the field in the code an thus should not change throughout the life of the project.

Key Type Default Definition
label string identifier form field label
hint string nil form field hint
placeholder string nil form field placeholder
position integer auto-increment position of the field within the part (only for the admin area)
required boolean true must this field have a value for the form to save
type string string choose between: boolean, date, decimal, file, image, integer, rich_text, text, string, resource_link (needs value: resource_linked (same as the controller name ex: pianos)), external_link (needs value:
default string nil set the value but don't overwrite (only set if nil). Put default images in /assets/images/defaults and default files in /assets/files/defaults
value string nil USE ONLY FOR types resource_link and external_link (this will overwrite user input, in most cases use the default key instead)

Create Resources

To add an admin area for a model simply type (make sure the model exists first and migrations have been run)

rails g cardboard:resource model_name

Then customize the controllers/cardboard/model_name_controller.rb and associated views to your heart's desire.

The default cardboard resource scaffold help you quickly get started by making the most of the following gems.

Gem Description
InheritedResources Inherited Resources speeds up development by making your controllers inherit all restful actions so you just have to focus on what is important.
Simple Form Forms made easy! It's tied to a simple DSL, with no opinion on markup.
Kaminari A Scope & Engine based, clean, powerful, customizable and sophisticated paginator
Ransack Object-based searching and filtering
Dragonfly On-the-fly image processing and file uploading

You can customize the menu for this resource by adding to the controller class:

  menu  label: "Test", priority: 1

You can also choose to remove a resource from the menu

  menu  false


You can customize the sorting for this resource by adding to the controller class:

  default_order "name DESC" # default: 'updated_at desc'

You can pass any ransack sort order, which includes associations. Example:

  default_order "user_name" # belongs to a user

Filter helper

You can show filters on your resource index page simply by adding cardboard_filters, with the model class, the main field to search (has to be a text or string field), and options.

= cardboard_filters User, :name

title: change the page's title (optional)

new_button: Options for the button used to create a new resource element. Can be false to remove it, or label and url can be modified (optional).

predicate: defaults to cont (contains). Note: On non text fields, this field is required


= cardboard_filters User, :name, title: "Employees", new_button: {label: "Add an employee"}

Pagination Helper

We use kaminari, so all you need to do is add to your index view:

= paginate @users

Column sorting helper

Cardboard's controllers inherit from a @q variable which gives access to the ransack gem.

= sort_link @q, :name, "Product Name"

Custom resource helpers

To add custom helpers for your resource simply create a helper with the same name. Example:

module Cardboard
  module PianosHelper

Make sure this file is located under app/helpers/cardboard

Custom CSS/JS

The css/js for the resources is the same as the cardboard admin interface. If you'd like to extend or overwrite some of these, simply edit the cardboard.css.scss or cardboard.js files located in your assets folder. These files were generated during the cardboard installation.

Note: Make sure to remove *= require_tree . from your application.css, you don't want your cardboard css and js to leak into your main app!

Create Settings

You can create new settings that will be editable from the admin panel.

In your config/cardboard.yml

    type: boolean
    default: true

all options/types from fields are available

Then you can use this setting in your views or controllers like so:


View Helpers

Access Pages


you can put your controller instance variables at the top of your view or in a decorator

|- decorators
  |- controllers
    |- pages_decorator
PagesController.class_eval do
  def page_identifier
    @example = "cool"

Page Path

In your controllers you may want to redirect to a specific page. You can do so with the following:

cardboard.edit_page_path(@page) #link to let your admins edit the page they see

Meta tags (SEO)

To add SEO meta tags simply add a yield as follows to your layout file:

 = yield(:seo)

Feel free to make it fit as you want in your site design

- if current_admin_user && current_page
  div style="float:right"
    = link_to "Edit this page", cardboard.edit_page_path(current_page)
= nested_pages do |page, subpages|
    = link_to(page.title, page.url) if page.in_menu?
    = subpages

or similarly with UL and LI tags

  = nested_pages do |page, subpages|
      = link_to(page.title, page.url) if page.in_menu?
      - if subpages
        ul= subpages

Use the page identifier defined in the cardboard.yml file (or see yoda)

  = link_to_page "page_identifier", class: "btn" do |page|
    "hello #{page.title}"

  # or, to simply use the page title

  = link_to_page "page_identifier", class: "btn"


You can (and should) add a can_manage_cardboard method to your user model. By default users can manage all areas of the admin panel.

def can_manage_cardboard?(area)
  case area
  when :pages
  when :settings
  when :resource_identifier #should be plural


You can add whatever you want on the dashboard by simply adding

|- cardboard
   |- dashboard
       |- index.html.slim

Customizing Cardboard

Overwrite views

You can easily change the default behavior of the app by overwriting the views. For example say you'd like to change the my account page. Simply add a views/cardboard/my_account/edit.html.slim and edit it at will.

Deploy with capistrano

namespace :cardboard do
  desc "seed the database"
  task :seed do
    run "cd #{current_path}; bundle exec rake cardboard:seed RAILS_ENV=#{rails_env}"
after "deploy", "cardboard:seed"


Copyright (c) 2013 by SmashingBoxes