Working with Refinery

Share this article

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?

Refinery Admin area
The slick looking admin area of Refinery

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.

Changing the layout for a page in Refinery
Once the config is setup correctly you ca fine tune the content layout

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.

Dave KennedyDave Kennedy
View Author

Dave is a web application developer residing in sunny Glasgow, Scotland. He works daily with Ruby but has been known to wear PHP and C++ hats. In his spare time he snowboards on plastic slopes, only reads geek books and listens to music that is certainly not suitable for his age.

RefineryCMS
Share this article
Read Next
How to Deploy Apache Airflow on Vultr Using Anaconda
How to Deploy Apache Airflow on Vultr Using Anaconda
Vultr
Cloud Native: How Ampere Is Improving Nightly Arm64 Builds
Cloud Native: How Ampere Is Improving Nightly Arm64 Builds
Dave NearyAaron Williams
How to Create Content in WordPress with AI
How to Create Content in WordPress with AI
Çağdaş Dağ
A Beginner’s Guide to Setting Up a Project in Laravel
A Beginner’s Guide to Setting Up a Project in Laravel
Claudio Ribeiro
Enhancing DevSecOps Workflows with Generative AI: A Comprehensive Guide
Enhancing DevSecOps Workflows with Generative AI: A Comprehensive Guide
Gitlab
Creating Fluid Typography with the CSS clamp() Function
Creating Fluid Typography with the CSS clamp() Function
Daine Mawer
Comparing Full Stack and Headless CMS Platforms
Comparing Full Stack and Headless CMS Platforms
Vultr
7 Easy Ways to Make a Magento 2 Website Faster
7 Easy Ways to Make a Magento 2 Website Faster
Konstantin Gerasimov
Powerful React Form Builders to Consider in 2024
Powerful React Form Builders to Consider in 2024
Femi Akinyemi
Quick Tip: How to Animate Text Gradients and Patterns in CSS
Quick Tip: How to Animate Text Gradients and Patterns in CSS
Ralph Mason
Sending Email Using Node.js
Sending Email Using Node.js
Craig Buckler
Creating a Navbar in React
Creating a Navbar in React
Vidura Senevirathne
A Complete Guide to CSS Logical Properties, with Cheat Sheet
A Complete Guide to CSS Logical Properties, with Cheat Sheet
Ralph Mason
Using JSON Web Tokens with Node.js
Using JSON Web Tokens with Node.js
Lakindu Hewawasam
How to Build a Simple Web Server with Node.js
How to Build a Simple Web Server with Node.js
Chameera Dulanga
Building a Digital Fortress: How to Strengthen DNS Against DDoS Attacks?
Building a Digital Fortress: How to Strengthen DNS Against DDoS Attacks?
Beloslava Petrova
Crafting Interactive Scatter Plots with Plotly
Crafting Interactive Scatter Plots with Plotly
Binara Prabhanga
GenAI: How to Reduce Cost with Prompt Compression Techniques
GenAI: How to Reduce Cost with Prompt Compression Techniques
Suvoraj Biswas
How to Use jQuery’s ajax() Function for Asynchronous HTTP Requests
How to Use jQuery’s ajax() Function for Asynchronous HTTP Requests
Aurelio De RosaMaria Antonietta Perna
Quick Tip: How to Align Column Rows with CSS Subgrid
Quick Tip: How to Align Column Rows with CSS Subgrid
Ralph Mason
15 Top Web Design Tools & Resources To Try in 2024
15 Top Web Design Tools & Resources To Try in 2024
SitePoint Sponsors
7 Simple Rules for Better Data Visualization
7 Simple Rules for Better Data Visualization
Mariia Merkulova
Cloudways Autonomous: Fully-Managed Scalable WordPress Hosting
Cloudways Autonomous: Fully-Managed Scalable WordPress Hosting
SitePoint Team
Best Programming Language for AI
Best Programming Language for AI
Lucero del Alba
Quick Tip: How to Add Gradient Effects and Patterns to Text
Quick Tip: How to Add Gradient Effects and Patterns to Text
Ralph Mason
Logging Made Easy: A Beginner’s Guide to Winston in Node.js
Logging Made Easy: A Beginner’s Guide to Winston in Node.js
Vultr
How to Optimize Website Content for Featured Snippets
How to Optimize Website Content for Featured Snippets
Dipen Visavadiya
Psychology and UX: Decoding the Science Behind User Clicks
Psychology and UX: Decoding the Science Behind User Clicks
Tanya Kumari
Build a Full-stack App with Node.js and htmx
Build a Full-stack App with Node.js and htmx
James Hibbard
Digital Transformation with AI: The Benefits and Challenges
Digital Transformation with AI: The Benefits and Challenges
Priyanka Prajapat
Quick Tip: Creating a Date Picker in React
Quick Tip: Creating a Date Picker in React
Dianne Pena
How to Create Interactive Animations Using React Spring
How to Create Interactive Animations Using React Spring
Yemi Ojedapo
10 Reasons to Love Google Docs
10 Reasons to Love Google Docs
Joshua KrausZain Zaidi
How to Use Magento 2 for International Ecommerce Success
How to Use Magento 2 for International Ecommerce Success
Mitul Patel
5 Exciting New JavaScript Features in 2024
5 Exciting New JavaScript Features in 2024
Olivia GibsonDarren Jones
Tools and Strategies for Efficient Web Project Management
Tools and Strategies for Efficient Web Project Management
Juliet Ofoegbu
Choosing the Best WordPress CRM Plugin for Your Business
Choosing the Best WordPress CRM Plugin for Your Business
Neve Wilkinson
ChatGPT Plugins for Marketing Success
ChatGPT Plugins for Marketing Success
Neil Jordan
Managing Static Files in Django: A Comprehensive Guide
Managing Static Files in Django: A Comprehensive Guide
Kabaki Antony
The Ultimate Guide to Choosing the Best React Website Builder
The Ultimate Guide to Choosing the Best React Website Builder
Dianne Pena
Exploring the Creative Power of CSS Filters and Blending
Exploring the Creative Power of CSS Filters and Blending
Joan Ayebola
How to Use WebSockets in Node.js to Create Real-time Apps
How to Use WebSockets in Node.js to Create Real-time Apps
Craig Buckler
Best Node.js Framework Choices for Modern App Development
Best Node.js Framework Choices for Modern App Development
Dianne Pena
SaaS Boilerplates: What They Are, And 10 of the Best
SaaS Boilerplates: What They Are, And 10 of the Best
Zain Zaidi
Understanding Cookies and Sessions in React
Understanding Cookies and Sessions in React
Blessing Ene Anyebe
Enhanced Internationalization (i18n) in Next.js 14
Enhanced Internationalization (i18n) in Next.js 14
Emmanuel Onyeyaforo
Essential React Native Performance Tips and Tricks
Essential React Native Performance Tips and Tricks
Shaik Mukthahar
How to Use Server-sent Events in Node.js
How to Use Server-sent Events in Node.js
Craig Buckler
Five Simple Ways to Boost a WooCommerce Site’s Performance
Five Simple Ways to Boost a WooCommerce Site’s Performance
Palash Ghosh
Elevate Your Online Store with Top WooCommerce Plugins
Elevate Your Online Store with Top WooCommerce Plugins
Dianne Pena
Unleash Your Website’s Potential: Top 5 SEO Tools of 2024
Unleash Your Website’s Potential: Top 5 SEO Tools of 2024
Dianne Pena
How to Build a Chat Interface using Gradio & Vultr Cloud GPU
How to Build a Chat Interface using Gradio & Vultr Cloud GPU
Vultr
Enhance Your React Apps with ShadCn Utilities and Components
Enhance Your React Apps with ShadCn Utilities and Components
David Jaja
10 Best Create React App Alternatives for Different Use Cases
10 Best Create React App Alternatives for Different Use Cases
Zain Zaidi
Control Lazy Load, Infinite Scroll and Animations in React
Control Lazy Load, Infinite Scroll and Animations in React
Blessing Ene Anyebe
Building a Research Assistant Tool with AI and JavaScript
Building a Research Assistant Tool with AI and JavaScript
Mahmud Adeleye
Understanding React useEffect
Understanding React useEffect
Dianne Pena
Web Design Trends to Watch in 2024
Web Design Trends to Watch in 2024
Juliet Ofoegbu
Building a 3D Card Flip Animation with CSS Houdini
Building a 3D Card Flip Animation with CSS Houdini
Fred Zugs
How to Use ChatGPT in an Unavailable Country
How to Use ChatGPT in an Unavailable Country
Dianne Pena
An Introduction to Node.js Multithreading
An Introduction to Node.js Multithreading
Craig Buckler
How to Boost WordPress Security and Protect Your SEO Ranking
How to Boost WordPress Security and Protect Your SEO Ranking
Jaya Iyer
Understanding How ChatGPT Maintains Context
Understanding How ChatGPT Maintains Context
Dianne Pena
Building Interactive Data Visualizations with D3.js and React
Building Interactive Data Visualizations with D3.js and React
Oluwabusayo Jacobs
JavaScript vs Python: Which One Should You Learn First?
JavaScript vs Python: Which One Should You Learn First?
Olivia GibsonDarren Jones
13 Best Books, Courses and Communities for Learning React
13 Best Books, Courses and Communities for Learning React
Zain Zaidi
5 jQuery.each() Function Examples
5 jQuery.each() Function Examples
Florian RapplJames Hibbard
Implementing User Authentication in React Apps with Appwrite
Implementing User Authentication in React Apps with Appwrite
Yemi Ojedapo
AI-Powered Search Engine With Milvus Vector Database on Vultr
AI-Powered Search Engine With Milvus Vector Database on Vultr
Vultr
Understanding Signals in Django
Understanding Signals in Django
Kabaki Antony
Why React Icons May Be the Only Icon Library You Need
Why React Icons May Be the Only Icon Library You Need
Zain Zaidi
View Transitions in Astro
View Transitions in Astro
Tamas Piros
Getting Started with Content Collections in Astro
Getting Started with Content Collections in Astro
Tamas Piros
What Does the Java Virtual Machine Do All Day?
What Does the Java Virtual Machine Do All Day?
Peter Kessler
Become a Freelance Web Developer on Fiverr: Ultimate Guide
Become a Freelance Web Developer on Fiverr: Ultimate Guide
Mayank Singh
Layouts in Astro
Layouts in Astro
Tamas Piros
.NET 8: Blazor Render Modes Explained
.NET 8: Blazor Render Modes Explained
Peter De Tender
Mastering Node CSV
Mastering Node CSV
Dianne Pena
A Beginner’s Guide to SvelteKit
A Beginner’s Guide to SvelteKit
Erik KückelheimSimon Holthausen
Brighten Up Your Astro Site with KwesForms and Rive
Brighten Up Your Astro Site with KwesForms and Rive
Paul Scanlon
Which Programming Language Should I Learn First in 2024?
Which Programming Language Should I Learn First in 2024?
Joel Falconer
Managing PHP Versions with Laravel Herd
Managing PHP Versions with Laravel Herd
Dianne Pena
Accelerating the Cloud: The Final Steps
Accelerating the Cloud: The Final Steps
Dave Neary
An Alphebetized List of MIME Types
An Alphebetized List of MIME Types
Dianne Pena
The Best PHP Frameworks for 2024
The Best PHP Frameworks for 2024
Claudio Ribeiro
11 Best WordPress Themes for Developers & Designers in 2024
11 Best WordPress Themes for Developers & Designers in 2024
SitePoint Sponsors
Top 10 Best WordPress AI Plugins of 2024
Top 10 Best WordPress AI Plugins of 2024
Dianne Pena
20+ Tools for Node.js Development in 2024
20+ Tools for Node.js Development in 2024
Dianne Pena
The Best Figma Plugins to Enhance Your Design Workflow in 2024
The Best Figma Plugins to Enhance Your Design Workflow in 2024
Dianne Pena
Harnessing the Power of Zenserp for Advanced Search Engine Parsing
Harnessing the Power of Zenserp for Advanced Search Engine Parsing
Christopher Collins
Build Your Own AI Tools in Python Using the OpenAI API
Build Your Own AI Tools in Python Using the OpenAI API
Zain Zaidi
The Best React Chart Libraries for Data Visualization in 2024
The Best React Chart Libraries for Data Visualization in 2024
Dianne Pena
7 Free AI Logo Generators to Get Started
7 Free AI Logo Generators to Get Started
Zain Zaidi
Turn Your Vue App into an Offline-ready Progressive Web App
Turn Your Vue App into an Offline-ready Progressive Web App
Imran Alam
Clean Architecture: Theming with Tailwind and CSS Variables
Clean Architecture: Theming with Tailwind and CSS Variables
Emmanuel Onyeyaforo
How to Analyze Large Text Datasets with LangChain and Python
How to Analyze Large Text Datasets with LangChain and Python
Matt Nikonorov
6 Techniques for Conditional Rendering in React, with Examples
6 Techniques for Conditional Rendering in React, with Examples
Yemi Ojedapo
Introducing STRICH: Barcode Scanning for Web Apps
Introducing STRICH: Barcode Scanning for Web Apps
Alex Suzuki
Using Nodemon and Watch in Node.js for Live Restarts
Using Nodemon and Watch in Node.js for Live Restarts
Craig Buckler
Task Automation and Debugging with AI-Powered Tools
Task Automation and Debugging with AI-Powered Tools
Timi Omoyeni
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form