Guides

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. They assume you are using the latest stable version.
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
  • Changing the front end design of a Refinery site
  • Extending Refinery’s functionality with custom extensions
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
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
Resources

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
    situation;
  • Show you how to enable both techniques.

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
Testing

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

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
With an existing Rails 3.1 + Devise app

This guide covers adding functionality provided by Refinery CMS to an existing application, while retaining the existing application’s control over configuration and use of the Devise authentication gem. After reading it, you should be familiar with:

  • Getting Refinery CMS + a Rails 3.1.x app
  • Adding the authentication (and authorization) rules from your app to Refinery’s back end administration content.
  • Ensuring your existing app’s tests still runs

Updating Refinery

Upgrading from version 2.0.x to version 2.1.x

This guide will guide you through the upgrade process from version 2.0.10 to version 2.1.×.

Whats new changed and removed in version 2.1.0

This guide will provide a list of bullet points of the stuff that has been added, changed and removed in version 2.1.0.

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

Hosting and Deployment

Heroku

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).

Shelly Cloud

Shelly Cloud is a platform for hosting Ruby and Rails
apps. This guide will show you how to:

  • Install and deploy a Refinery application on the Shelly Cloud hosting platform

Contributing

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.

Presenters

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
  • override Refinery’s view