These guides are designed to make you immediately productive with Refinery, and to help you understand how all of the pieces fit together.


Refinery guides are a work in progress.

Right now, they assume you are using the 2.1.x version.

We are currently rewriting Refinery guides for the 3.x version, please see the latest version on Github.
Some of these guides contain incomplete information and even errors. You can help by reviewing them and posting your comments and corrections in the comments area of each guide.

Getting Started

Installation Prerequisites

This guide covers getting your system ready for Refinery. Afterwards you will have:

  • A working version of Ruby
  • ImageMagick installed
  • Either the SQLite, MySQL, or PostgreSQL database configured
Getting Started

This guide covers getting up and running with Refinery CMS. After reading it, you should be familiar with:

  • Installing and creating a new Refinery site
  • Switching between the back-end Refinery site editor and the front-end of a site
  • Changing the front end design of a Refinery site
Generate an Extension to Use Your MVCs

This guide explains how to generate and get started with an extension in Refinery. After reading it, you should be familiar with:

  • The basic structure of a Refinery extension
  • Using the Refinery generator to generate a custom extension
  • Extending Refinery’s functionality with custom extensions
  • Crudify, a CRUD module that Refinery provides
How to get help

We all sometimes hit a brick wall. This guide will show you how to:

  • Get support and help by connecting with other Refinery developers
Best Practices and Frequently Asked Questions

This guide covers recommendations on best practices for coding Refinery sites,
and also attempts to document answers to the most frequently asked questions.

Refinery Basics

Changing Page Parts

Refinery sets up two default page parts Body and Side Body.
Sometimes this is not suitable for your project.
This guide will show you how to:

  • Change the default page parts to be something else
  • Add a new page part to a single page
Page Titles and URLs

This guide covers titles and urls in Refinery Pages. After reading it, you should be familiar with:

  • Customizing titles shown on pages and menus
  • Customizing titles shown in the browser window (the html title tag) for SEO purposes
  • Customizing the slugs that are automatically generated by Refinery
  • Excluding a route from Refinery’s list of reserved words
Overriding views

The default HTML Refinery generates on the front end is sometimes not suitable for your design. This guide will show you how to:

  • Override a front end view in Refinery and replace it with your own version
Extending Controllers with Decorators

The default behavior of Refinery or a Refinery extension and its controllers may not be exactly what you are looking for. This guide will show you how to:

  • Extend a Controller to add new behavior
Overriding javascripts

By default, Refinery will provide you with the required javascript files you
need. Sometimes, these defaults do not suffice, and you will need to customize
the Javascript files used by Refinery. This guide will show you how to:

  • Change the default javascript libraries included;
  • Add your own files to be included.
Google Analytics

Google Analytics is a great free way to find out how much traffic your site is getting. This guide will show you how to:

  • Use the built in Refinery setting and layout to easily add Google Analytics support to your existing Refinery site
Translate Refinery

Refinery supports internationalization (I18n for short), which includes translation. This guide will show you how to:

  • Improve upon or add a new translation to Refinery
Extending Models

Sometimes you will want to graft in extra functionality that requires extra data to be stored in your model. This guide will show you how to:

  • Extend an existing model in order to add a new field;
  • Modify views through overrides

This guide will show you how to set a Content-Disposition when working with resources.

Advanced Techniques and Tips

Using Custom View or Layout Templates

Many Refinery sites have more than one look. Sometimes, the content from a page
might have a different container, or the page itself might be laid out
differently. This guide will:

  • Help you decide whether these techniques are appropriate for your site;
  • Guide you as to which technique is the appropriate one to use for your
  • Show you how to enable both techniques.
Troubeshooting Image Problems
Changing Menu Markup

Refinery Extensions

Tabbed Fields

Sometimes you create an extension with a number of wymeditor fields. Having these display one after another can be overwhelming for your clients (or you!).
This guide will show you how to:

  • Organise many visual editors into nice tabs like Refinery’s ‘pages’ extension does
Multiple Resources in an Extension

This guide will show you how to:

  • Create multiple tables on one single extension

Refinery ships with an optional testing extension in the form of a gem called refinerycms-testing which will add generators and rake tasks to your extension that provide it with the same RSpec2 testing environment we use to test Refinery. We abstract common test helpers, controller macros, and factories into this extension so you can use these in tests of your own.

This guide will show you how to:

  • Bootstrap your extension with the Refinery RSpec2 testing environment
  • Run the test suite with Rake for a one time run
  • Run the test suite with Guard for quick TDD iterations
Pretty URLs

It’s very important for Search Engine Optimization (SEO) purposes to have your URLs be human-readable. Refinery CMS ships with software (FriendlyID) that enables these marketing-friendly URLs with only minor modifications.

This guide will show you how to:

  • Implement marketable URLs on a custom extension.
Relating Resources in an Extension

This guide will show you how to:

  • Properly relate two models in a Refinery Extension that you have created
  • Create a drop-down select box in one Refinery Page that relates to data in another Refinery engine model
Generate a custom form
changes to extensions in Refinery 3.0
Adding an image collection to an extension using PageImages
Using a Refinery CMS extension as a standalone extension in your Rails Application

A Refinery CMS extension can be used as a standalone extension in your Rails application.

This guide will show you how to:

  • Bootstrap a rails application with just the use of a Refinery CMS extension like refinerycms-blog

Using Refinery as an Engine

With an existing Rails app

This guide covers integration with Refinery CMS. After reading it, you should be familiar with:

  • Attaching Refinery CMS to an existing Rails application

Updating Refinery

Upgrading to the Latest Stable Version

Refinery constantly changes as we add new features and fix bugs. This guide will show you how to:

  • Keep updated with the latest stable versions as they are released
Upgrading to Edge

If you’re an experienced Refinery developer you might want to live on the edge. This guide will show you how to:

  • Keep your existing Refinery installation on the edge version
Upgrading to Refinery 3.0

Hosting and Deployment


Heroku is a popular hosting choice for many developers. This
guide will show you how to:

  • Install and deploy a Refinery application on the Heroku hosting platform
Amazon S3 for Uploads

Hosting your site’s files on Amazon S3 is a popular option for many, especially
if you’re using a read only file system like Heroku.
This guide will show you how to:

  • Enable and configure Refinery to store files and images on Amazon S3
Full-Page Cache with Apache

If you have a simple Page on a slow Server with Apache you can use the Full
Page Caching for deliver the most pages directly from Apache (without passenger).


Contributing to Refinery

One of Refinery’s key principles is encouraging people to contribute. This guide will show you how to:

  • Contribute to the documentation (such as this guide)
  • Contribute bug fixes or new features
  • Contribute financially
Writing a guide for this website

This guide covers writing your own guide. After reading it, you should be able to:

  • Format a guide.
  • Submit it for approval and inclusion on this website.


Menu Presenter

This guide will show you how to:

  • configure and use Refinery::Pages::MenuPresenter
  • use a decorator to add custom functionality to Refinery::Page class
  • use a decorator to allow attributes in Refinery::Admin::PagesController
  • override Refinery’s view