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 engines
endprologue.
WARNING. This guide is based on Refinery CMS 0.9.9.16 so some of the code shown here may not work in earlier versions of Refinery.
This guide is designed for beginners who want to get started with a Refinery CMS site from scratch. It does not assume that you have any prior experience with Refinery. However, to get the most out of it, you need to have some prerequisites installed:
- The Ruby language version 1.8.7 or higher (1.9.2 recommended)
TIP: Ruby 1.9.1 is not usable because it outright segfaults on Rails 3.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing.
- The RubyGems packaging system
- A working installation of the SQLite3 Database
- A working installation of ImageMagick
TIP: On Linux, ImageMagick is usually included by default. On Mac OS X, use this install script.
TIP: It is recommended that developers use RVM to manage Ruby versions and gems. Once RVM is installed on your system, and you’ve created a gemset for the project, create an .rvmrc file in the site’s root directory. Its contents should look something like:
rvm use —create ruby-1.9.2@refinery
Refinery is a Ruby on Rails web application. If you have no prior experience with Rails, you will find a very steep learning curve diving straight into Refinery. There are some good free resources on the Internet for learning Rails, including:
Refinery CMS, often shortened to Refinery, is an open source content management system written in Ruby as a Ruby on Rails web application with JQuery used as the JavaScript library. Refinery runs on Rails 3.0.
Refinery differs from similar projects by targeting a non-technical end user and allowing the developer to create a flexible website rapidly by staying as close as possible to the conventions of the Ruby on Rails framework.
The Refinery philosophy includes several guiding principles:
- “The Rails Way” where possible – Refinery embraces conventions used in Rails, allowing any Rails programmer to leverage existing knowledge to get up and running quickly.
- End user focused interface – Refinery’s user interface is simple, bright and attractive so end users feel invited and not overwhelmed.
- Awesome developer tools – Refinery makes it easy for developers to add functionality and change the front end look and feel.
- Encourage and Help Others – Refinery has an active community on Google Groups and IRC. If you ever have a question there is someone able and willing to assist.
Refinery comprises of several Rails Engines that sit under /vendor/refinerycms. Each engine acts like a mini Rails application with their own routes and views. Refinery is architected like this so that it keeps out of the way of any custom development you will do in the /app directory.
The engines Refinery comes with are:
- Authentication – manages users and sessions within Refinery.
- Core – contains default layouts, views, javascripts and CSS. This engine also has an engine API for extending Refinery and everything Refinery needs to hook into Rails.
- Dashboard – shows you what’s recently been updated.
- Images – handles image upload, insertion and processing images using Dragonfly.
- Pages – allows you to manage pages including the structure of your site displayed in the front end.
- Resources – handles file upload and storage.
- Settings – manages various settings you can configure in Refinery.
If you follow this guide, you’ll create a Refinery site called rickrockstar that will have a custom design and an events engine to allow Rick to tell his fans when his next gig is.
Before you can start building this site, you need to make sure that you have Refinery itself installed.
The easiest way to install Refinery is to take advantage of RubyGems.
- gem install refinerycms
TIP. If you’re working on Windows, you should be aware that the vast majority of Refinery development is done in Unix environments. If at all possible, we suggest that you develop on a Linux based operating system.
The best way to use this guide is to follow each step as it happens, no code or step needed to make this example application has been left out, so you can literally follow along step by step.
To begin, open a terminal, navigate to a folder where you have rights to create files, and type:
$ refinerycms rickrockstar
NOTE: This step may take some time to load as it needs to download and install all the ruby gems Refinery depends on.
TIP: You can see all of the switches that the refinerycms command accepts by running refinerycms with no options or arguements.
This will create a new Rails application with Refinery built in called Rick Rock Star in a directory called rickrockstar. It also automatically runs bundle install which will find and install all Refinery’s ruby gem dependencies. Finally, it creates your database and seeds it with some basic defaults to get you started.
NOTE: In this guide we are using an SQLite3 database for data storage, because it is a zero configuration database that just works. Refinery also supports MySQL and PostgreSQL “out of the box”.
Refinery will create a folder in your working directory called rickrockstar. Switch to this folder:
$ cd rickrockstar
Open up that folder and explore its contents. You’ll notice what you have is a very standard Rails application.
One of the traditional places to start with a new project is by getting some text up on screen quickly, to do this, you need to get your Refinery application server running.
You actually have a functional Refinery application already installed. To see it, you need to start a web server on your development machine. You can do this by running:
$ rails server
NOTE: There is a bug in the current release of Refinery that may cause your database to not be set up properly. If this happens, try running rake db:create and then rake db:migrate.
This will fire up an instance of the WEBrick web server by default. To see your application in action, open a browser window and navigate to http://localhost:3000. You should be greeted with a screen prompting you to create your first Refinery user.
TIP: To stop the web server, hit Ctrl+C in the terminal window where it’s running.
If you see this screen it means you have setup everything correctly and your Refinery CMS site is up and running.
Fill out the sign up form to create your first user. This will be the super user of Refinery, meaning this user will be able to create other users later on.
Once you’ve created your first user you’ll see Refinery’s “Dashboard”.
The screen above prompts you with a message to set your site name. Click the “go here” link and set the value in the dialog to “Rick Rock Star”. This name will be shown in both the back and front end header as well as the browser title.
Click “Save”
Now you’re setup, click around the various tabs in the backend and become familiar with what comes out of the box.
While exploring one of the first things I do is reorder the tabs to reflect what I will be working on the most. Click the tab with the two green arrows, and then drag the backend tabs, for example “Users” or “Settings”, into an order which makes more sense to you.
Click the reorder button again when you’re done to save.
You’re currently in the back end Refinery site editor. To see your front end site click “Switch to your website”.
As you can see Refinery is already displaying a basic menu and layout ready for you to customise.
NOTE: If you get a 404 error on the homepage, try running the rake db:seed and then restarting the server:
The layout Refinery provides out of the box is very barebones. We’ll now guide you through customising the front end design to give Rick the beautiful site we promised.
By default Refinery has a range of views built in to display the front end site you currently have. But more times than often you want to customise them with your own layout and design.
TIP: Overriding Refinery views is a common pattern which is worth keeping in mind at all times. If Refinery isn’t displaying something how you’d like, just override it.
If you request http://localhost:3000/about this maps by default to Refinery’s pages_controller.rb show action.
So as you would expect the view for this action is located in app/views/pages/show.html.erb. You won’t be able to see this file because Refinery is providing it for you. Next let’s override that view and replace it with our own.
Refinery comes with a rake task called refinery:override which allows you to copy files out of Refinery and into your own application to change. Let’s override the pages show view:
$ rake refinery:override view=pages/show
$ Copied view template file to app/views/pages/show.html.erb
Now edit app/views/pages/show.html.erb and it will look like this:
<%= render :partial => “/shared/content_page” %>
Refinery has a content_page partial it uses just to get you started. But we’ll soon remove this and use our own ERB view instead.
Every view in Refinery has an instance variable called @page available. The best way to explain how this works is just to show you.
Replace the contents of app/views/pages/show.html.erb with this:
As you can see we’re going to render a view with some HTML5 tags and along with some content coming from the CMS (those are the lines that mention @page).
@page has what we call PageParts associated with it. To see what I mean go to http://localhost:3000/refinery/pages and then click edit on the page titled “About”.
When you edit the about page you’ll see something like this:
You’ll notice two tabs on the page “Body” and “Side Body”. These are Page Parts, or in other words a single piece of content attached to this page that you can render in your view. There is a “Body” tab with some content on this screen, to render that same content in your view you put:
<%=raw @page.content_for(:body) %>
As mentioned earlier, a key principle in Refinery is to stick to “The Rails Way” where possible. This is apparent in the way you style your views too. You style your site exactly how you would style any Rails application, using public/stylesheets/application.css
Open up public/stylesheets/application.css and add this:
@import url(‘refinery/application.css’);
body {
background: #DDD;
font-family: Verdana;
font-size: 13px;
line-height: 18px;
}
#body_content, #side_body_content {
float: left;
width: 45%;
background: white;
color: #333;
padding: 20px;
}
#menu ul {
list-style: none;
padding: 0px;
}
#menu ul li {
float: left;
margin-right: 10px;
}
#menu ul li a {
display: block;
padding: 5px 10px;
text-decoration: none;
}
#menu ul li.selected a, #menu ul li a:hover {
background: #CCC;
}
TIP: When on the home page of your site, Refinery automatically loads an extra stylesheet located in public/stylesheets/home.css as often sites have a different style on the home page.
Now when you view your front end at http://localhost:3000 you’ll notice your site has a grey background, with a horizontal menu and two white content areas.
We just overwrote the pages/show view and replaced it with our own version. We learnt how to use @page to display content entered in the backend.
Finally we added a (super) simple style that changes the colour of the background and uses our pages/show view to split into two even columns.
Think of a Refinery engine as a mini Rails application running in your vendor/engines directory. Each engine specifies its own routes in the config directory and has its own views and controllers in its own app directory. Engines can even serve up their own images, stylesheets and javascripts from the engines public directory.
Refinery ships with an engine generator that makes adding your own functionality a breeze. It works just like the Rails scaffold generator.
$ rails generate refinery_engine singular_model_name attribute:type [attribute:type …]
TIP: to see all the options supported by the refinery_engine generator just run rails g refinery_engine
Here is a list of the different field types are what they give you:
| field type | description |
| text | a multiline visual editor |
| resource | a link which pops open a dialog which allows the user to select an existing file or upload a new one |
| image | a link which pops open a dialog which allows the user to select an existing image or upload a new one |
| string and integer | a standard single line text input |
If you remember, we told Rick that we’ll give him an area to post up events he’ll be at. Although he could technically create a new page in Refinery to add this content there, areas that have special functionality are much better suited as an engine.
Rick is going to want to enter the following information about each event:
- The event title
- The event date
- A photo
- A little blurb about the event.
Run this command to generate the events engine for Rick1:
$ rails generate refinery_engine event title:string date:datetime photo:image blurb:text
create vendor/engines/events/app/controllers/admin/events_controller.rb
create vendor/engines/events/app/controllers/events_controller.rb
create vendor/engines/events/app/models/event.rb
create vendor/engines/events/app/views/admin/events/form.html.erb
create vendor/engines/events/app/views/admin/events/event.html.erb
create vendor/engines/events/app/views/admin/events/sortable_list.html.erb
create vendor/engines/events/app/views/admin/events/edit.html.erb
create vendor/engines/events/app/views/admin/events/index.html.erb
create vendor/engines/events/app/views/admin/events/new.html.erb
create vendor/engines/events/app/views/events/index.html.erb
create vendor/engines/events/app/views/events/show.html.erb
create vendor/engines/events/config/locales/en.yml
create vendor/engines/events/config/locales/lolcat.yml
create vendor/engines/events/config/locales/nb.yml
create vendor/engines/events/config/locales/nl.yml
create vendor/engines/events/config/routes.rb
create vendor/engines/events/db/migrate/create_events.rb
create vendor/engines/events/db/seeds/events.rb
create vendor/engines/events/features/manage_events.feature
create vendor/engines/events/features/step_definitions/event_steps.rb
create vendor/engines/events/features/support/paths.rb
create vendor/engines/events/lib/generators/refinerycmseventsgenerator.rb
create vendor/engines/events/lib/events.rb
create vendor/engines/events/lib/tasks/events.rake
create vendor/engines/events/public/.gitkeep
create vendor/engines/events/readme.md
create vendor/engines/events/refinerycms-events.gemspec
-——————————-
Now run:
bundle install
rails generate refinerycmsevents
rake db:migrate
-——————————-
As the output shows next run:
$ bundle install
$ rails generate refinerycms_events
$ rake db:migrate
A refinerycms_events generator is created for you to install the migration to create the events table.
TIP: When new engines are added it’s a good idea to restart your server for new changes to be loaded in.
Now go to the backend of your Refinery site http://localhost:3000/refinery and you’ll notice a new tab called “Events”. Click on “Add new event” and you’ll see something like this:
You’ll see the entire form has been generated for you based off the field types you specified when generating the events section. The blurb has a visual editor, the date field is a date picker and the photo allows you to pick or upload a new photo from a built in Refinery dialog.
Add a couple of mock events to your events engine.
Now click on “Switch to your website”, and navigate to http://localhost:3000/events
You’ll notice not only has Refinery generated the backend “Events” tab but also a new menu item called “Events” and two new front end views index.html.erb and show.html.erb located in vendor/engines/events/app/events/ for you to customise.
As you can see, Refinery makes it insanely easy to quickly add new engines to manage various areas of a site.
But I’ve noticed one problem. The “2011 Music Awards” is showing up in the middle when it makes more sense to order the events with the latest event at the top. To fix this we need to understand what’s happening under the hood of a Refinery engine. Let’s dive in.
Any Refinery engine, even the built-in ones, that focus on Create, Read, Update and Delete are driven by crudify. Crudify is a highly reusable module included with Refinery that gives you all the standard CRUD actions as well as reordering, searching and paging.
Open up vendor/engines/events/app/controllers/admin/events_controller.rb and look at it’s contents:
class Admin::EventsController < ::Admin::BaseController
crudify :event
end
Most of the time crudify’s defaults are bang on, but if you need to, you can easily customise how it works2.
But default crudify assumes your records will be sortable. But events are not manually sortable, it makes more sense to order them by their event date. Update the contents of the file to this:
class Admin::EventsController < ::Admin::BaseController
crudify :event, :order => “date DESC”,
:sortable => false
end
This will tell crudify to sort by our event date field and to turn off manual sorting by the user.
Finally edit vendor/engines/events/app/controllers/events_controller.rb and replace the find_all_events method with this one:
class EventsController < ApplicationController
- code
protected
def find_all_events- Order by event date
@events = Event.order(“date DESC”)
end
- code
end
Now when you look at http://localhost:3000/events you’ll notice they’re now being sorted by the event date.
Now that you’ve made your first Refinery application with a custom events engine, you should feel free to update it and experiment on your own. But you don’t have to do everything without help.
If you need assistance getting up and running with Refinery follow the How to get help with Refinery Guide and for professional support & consulting contact Resolve Digital (the creators of Refinery).
1 If you want to know more about the Engine’s file structure, check out the separate documentation on Engines.
2 There’s a separate doc on configuring and overriding Crudify.