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
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 and Models with Decorators
-
The default behavior of Refinery or a Refinery extension and its controllers and models may not be exactly what you are looking for. This guide will show you how to:
- Extend a Controller or Model to add new behavior
- Overriding javascripts
-
Refinery by default will provide you with the required javascript files you need. Sometimes you want to provide your own files and this guide will show you how to:
*Change the default javascript libraries included.
*Add your own files to be included on a per page basis. - 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 translations. This guide will show you how to:
- Improve upon or add a new translation to Refinery
Advanced Techniques and Tips
- Adding an Image Gallery to Pages
-
By default pages don’t allow you to make galleries of images. This guide will show you how to:
- Use the portfolio extension to display a gallery of images
- Redirecting Legacy URLs
-
Many Refinery sites replace old ones that have links to these older pages. This guide will show you how to:
- Match old urls and redirect to them appropriate new ones
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.
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
- With an existing Rails + 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 to use an existing User model
- Applying your site layout and css to the Refinery front end generated content
- Ensuring your existing app’s tests still run
- Adding the authentication (and authorization) rules from your app to Refinery’s back end administration content.
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
Hosting and Deployment
- Heroku
-
Heroku is a popular hosting choice for many developers. This guide will show you how to:
- Install and deploy Refinery 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
- 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.