Working with Refinery

The CMS market is a pretty saturated landscape. I feel confident saying that, at one time or another, every developer has dirtied their hands using WordPress, Joomla or some other PHP solution. In the Ruby world, there are far fewer options and one of the more mature is Refinery CMS.

Not only does Refinery offer a slick interface for the client, by implementing the CMS as Rails Engines it makes it one of the most flexible I, personally, have utilized.

Getting Started

Refinery has two flavours of install: You can use the custom binary which ships with Refinery refinerycms <name_of_your_application> or add CMS functionality to an existing application. In my day-to-day work, I find the latter is the more common option. I see it as a blessing that I’m rarely required to create just a CMS. An application that also requires a content controlled ‘Shop window’, well that is more common and much more interesting.

Adding the CMS functionality to a rails application is a breeze. Simply add the Refinery gem, gem 'refinerycms' to your Gemfile and run bundle install.

Just a quick note on the install of the Refinery gem: I had a head scratching moment when I ran into dependancy errors regarding jquery-rails. There are a couple of issues in the project describing similar errors. If you run into the same problems, a good old fashioned bundle update sorts the dependancies, just make sure you have your Gemfile content versioned well.

Once installed you get a custom rails generator for the content managed area of the application. It’s simply rails generate refinery:cms --fresh-installation. If, like me, you watch the output of these things like a hawk, you will have seen the migrations for Refinery copied into your application and subsequently ran. The first job is to see if it has all went well. That’s simply a case of starting up the server and checking the administration area of your application. By default will be localhost:3000/refinery. On a fresh install you will be prompted to create a default user and set a password, once that is complete you will be directed to the main admin area. All is well with the world of administration, but what are our users going to see, and on which url?

Configuring the CMS

Looking at the config/routes.rb file, we can see that the CMS has been installed at the root of our application. The rails generate refinery:cms install added the line mount Refinery::Core::Engine, :at => '/' into the routes. So navigating to the root of the domain we will see the content managed area. In most cases the root will be desired location to mount the CMS, but by all means feel free to change it to whatever suits your needs, mount Refinery::Core::Engine, :at => '/cms_content_here' and so on.

There is a whole smorgasbord of configuration settings available to you after install. Check these settings out by simply looking in the freshly created config/initializers/refinery directory. There are too many to go into real detail, but there are few I always find myself tweaking.

Really Simple Configs (I change these every time)

Of course, you will want to change the site name, with is ‘Company Name’ by default. This is such quick change it’s almost criminal in international law not to have this in place after a fresh install. In the core initializer (config/intailizers/refinery/core.rb) change the line config.site_name = "Company Name".

Google analytics are usually also mandatory and Refinery CMS saves you the pain of managing this configuration in a view. In the same core initialiser change the line config.google_analytics_page_code = "UA-xxxxxx-x" to suite your unique analytics code.

Fresh out the box Refinery uses the local file system for asset storage. As we are knowledgeable citizens of the web we know sometimes it’s just better to store our assets in “the cloud”. Refinery makes it really simple to utilise S3 accounts. In the core initialiser (config/initalizers/refinery/core.rb) we see this entry:

config.s3_backend = !(ENV['S3_KEY'].nil? || ENV['S3_SECRET'].nil?)


Basically if the S3 key is available as an environment variable for your application then it will use S3 for your images and resources, otherwise it’s back to the default filesystem. You can even fine grain the control of what is stored on S3 as similar configuration is available in the images (config/initalizers/refinery/images.rb) and resources (config/initalizers/refinery/resources.rb) config.

config.s3_backend = Refinery::Core.s3_backend
config.s3_bucket_name = ENV['S3_BUCKET']
config.s3_access_key_id = ENV['S3_KEY']
config.s3_secret_access_key = ENV['S3_SECRET']
config.s3_region = ENV['S3_REGION']


These details do not necessarily have to live in the environment variables. If you are uneasy using commands like export S3_KEY='my_key, you can simply add the ENV parameters to your environment. For example, add ENV['S3_KEY']='my_key' to the config/environments/production.rb file ( or to whatever environment you like ).

The Look and Feel

Although the back-end of the Refinery CMS is clean and pretty polished, the front-end is extremely bland. An essential part of achieving a branded look is customising the HTML markup. In any two step views you have certain elements building up the layout, header, footer, sidebar and so on. Refinery provides a number of rake tasks to override the views, layout elements and the layout itself. Running the task

rake refinery:override view=layouts/application


Will provide a copy of the Refinery default layout ERB file in the views/layouts/application.html.erb.

I also like to use Refinery’s ability to support multiple layouts. Again we look to the initialisers to configure this. In config/initializers/refinery/pages.rb you simply provide a alternative layout like so.

config.layout_template_whitelist = ["application", "three_col_layout"]
config.use_layout_templates = true


Then. when creating a new page via the CMS administration area you select the desired layout type. Similarly, you can alter the view type allowing for more intricate and customised content areas.

All that said, from my own personal experience it tends to be only the homepage (or 1 or 2 others) that break the mold in terms of layout. In these cases, creating and allowing modification of page layouts may be a little overkill, as well as dangerous.

Extending Refinery

In the above use case we want to set a custom layout for the home page only. The best way to achieve this is to decorate the PagesControllerof Refinery. You may well have noticed the decorators/controllers/refinery directories after the refinery install. Within this directory, we can create a pages_controller_decorator.rb and extend the behaviour of the default controller provided by Refinery.


Refinery::PagesController.class_eval do
layout 'homepage', only: [:home]
end

This kind of extending provides a lot of control with surprisingly little effort. It works well for adding more common yet sophisticated functionality to our pages such as fetching a twitter feed or handling a custom form submission.

Polishing Off the Refinery Tour

You have probably got the gist that Refinery is a full featured CMS solution. One of its benefits is that the documentation is pretty comprehensive. The guides are laid out a la Rails, clean and simple to follow, albeit lacking in some of the more advanced areas.

Fortunately the Refinery CMS message board in my experience is helpful and friendly place to go looking for information. As Refinery utilizes engines, you will find extending and customising your CMS solution relatively straight forward as very rarely does it depart from the Rails way of doing things.

I hope this article has inspired you to give Refinery a try the next time you need a CMS.