Refinery’s Getting Started guide proceeds by telling you how to start overriding views for your pages - but first, let’s see what I can do just with CSS. First, what is the structure of the basic page?

    <div id="page_container">
      <header>
        <h1 id='logo'><a href="/">Site Name</a></h1>
        <nav id='menu' class='menu clearfix'>
          <ul>
            <li class='selected first' id='item_0'><a href="/">Home</a></li>
            <li class='last' id='item_1'><a href="/about">About</a></li>
          </ul>
        </nav>
      </header>
      <section id='page'>
        <section id='body_content'>
          <h1 id='body_content_title'>Home</h1>
          <section id='body_content_left'>
            <div class='inner'>
              <p>
                Welcome to our site. This is just a place holder page while we gather our content.
              </p>
            </div>
          </section>
          <section id='body_content_right'>
            <div class='inner'>
              <p>
                This is another block of content over here.
              </p>
            </div>
          </section>
        </section>
      </section>
      <footer>
        <p>Copyright © 2011 Site Name</p>
      </footer>
    </div>

That’s a pretty nice structure. There are some HTML5 semantic tags - header, footer, section. The entire thing is wrapped into a div with the id page_container. Content sections are delimited with sections and divs with ids that should make it pretty easy to pick them out with CSS selectors. The navigation is an unordered list that should be easy to style into a list or a set of tabs. The out of the box page is plain black and white but is laid out with two columns side by side. So there must be some styling coming from somewhere. Let’s look in the normal place for rails stylesheets: $RAILS_ROOT/public/stylesheets/. The generator created 4 files in that directory: application.css formatting.css home.css theme.css Very nice - but all they have are comments in them saying how they should be used. For example, application.css should be used to override front end styles while formatting.css will be included in the front end styles AND in the WYSIWYG editor on the back end. That sounds like a nice structure. But so far, I don’t see actual CSS. Looking more closely, I see we are including styles from /stylesheets/refinery/application.css. Where is that coming from? Ahhh that comes from the refinery-core gem which, being an engine, has a full rails application structure within the gem. The public/stylesheets directory inside that gem is where all the backend styling is coming from - as well as this one refinery/application.css file.

Interesting. But can I change things? Yup. If I edit the application.css file in my public/stylesheets/application.css directory, I can affect the look if the site. I can set backgrounds, override column widths, etc. The guide even provides a very basic set of tabbed navigation. So, for the sites where I already have a design, it is a pretty straightforward matter of converting their styles into CSS that matches the default page structure for the RefineryCMS pages. If I had a particularly complicated design, I could override the RefineryCMS views to fit with my CSS. But in the first instance, the site I am converting uses a series of nested tables , so changing the layout to something more modern is a good idea anyway.

Refinery also claims to support SASS stylesheets - there is even a section in the getting started guide specifically about stylesheets. However after some confusion about where to place the code in that guide, I discovered I really didn’t need it - at least in development mode. All I needed to do was add gem 'sass' to my Gemfile and rerun bundle install. Some deep Rails magic automatically recompiles my SASS templates at each page load which made modifying the design pretty fast. However, I am still struggling to figure out how to make this work out in production mode.

Refinery has an excellent set of documentation. I am on a new server but one with a very old ruby, so I had to start by installing RVM, installing ruby 1.8.7 and creating a gemset to use for my refinery projects. I chose 1.8.7 because of some of the slow start up problems with rails on 1.9.2 - but later I found that Heroku was recommending 1.9.2. Oh well, I’ll fix that later.

So following the Getting Started guide, I did: gem install refinerycms and then refinerycms refinerytest -d postgresql -u cnk -p sekrit The flags I used were not in the getting started guide - but I found them using refinerycms --help. I already have a Postgresql database (9.0.4) installed and I have admin access to it. So using those flags, I was able to specify Postgresql rather than SQLite, configure it, and then the installer could run the migrations for me. The one flag that appears to be missing is a host flag for the database configuration. So the automatic database configuration and migration only works if your database is available on localhost. If it isn’t, no matter, the installer will tell you that you need to complete the configuration and then run rake db:migrate. (Note, a flag for host was added just a little while after I did this setup.)

The installer finishes by suggesting you run rails server and look at your site at http://localhost:3000. The installer did not create an initial admin user in the migrations. That means there isn’t a standard username and password - which is nice for security. To fix this, the refinery server startup detects there isn’t an existing user and prompts you to add one. Once you have created the initial user, you are redirected to the refinery admin section where you can see the recent activity (e.g. the addition of your admin user). At the top of the page is a suggestion that you update the name of your site - and a link to the settings editor where you can do that.

So far, I am really impressed. The install and setup process is quite smooth and well documented - with well placed hints at strategic points along the way. Very professional. My initial impression of the admin interface is that it is clean, well organized, and pretty intuitive. In the upper left hand corner is a link to view the public version of the site…. Ugh!

The back end is nicely laid out and themed - good tabbed interface, very professional looking. But the front end is completely unstyled (or almost completely). That probably makes sense in the context that Refinery was developed in - for a professional web consulting shop who almost certainly has designers on retainer if not on staff. For my current site conversion project the lack of styles is also probably a good thing. But for some other projects I have in mind, the lack of even basic styling means that the first thing I am going to have to do is come up with a design. Not my favorite part about web work. In my professional life I have mostly had the good fortune to work on teams who had designers - really good designers - so it isn’t a skill I have developed. I know from a previous experience with Radiant that it comes out of the box looking pretty good.

The problem with content management systems is that everyone wants something simple - but it also needs to have XYZ feature. And since everyone’s ‘must have’ feature is different than someone else’s ‘must have’, pretty soon you have a giant feature set and everyone is complaining it isn’t simple any more. So for the last ten years, I have been building custom content management systems in a variety of languages. Most recently, I have been building and extending content management systems in Ruby on Rails. Because of some specific integration needs, I think that was a good choice for us at the time - and may continue to be because of our installed base (35 groups and counting). However I thought it might be nice, for my personal sites, to evaluate some of the generally available options for modern Rails CMSs.

About two and a half years ago, there was a series of quite insightful blog posts comparing three Rails CMS offerings on a blog named helpfully “Which Ruby CMS Should I Use”. Youssef Chaker decided to build a basic conference registration site with social media features in BrowserCMS, Radiant, and AdvaCMS and blog about his experience. Ironically that site did not use any of the CMSs under evaluation. Instead he used Jekyll, the “blog aware, static site generator” written in ruby. Since I have always maintained (or some might say neglected) my personal web sites using emacs + version control, I may include Jekyll in my evaluation just for fun.

While I may decide that Jekyll is the perfect tool for me, I don’t think it will be a good choice for the project I have in mind: transferring some friends’ professional web sites into a CMS so they can edit them themselves instead of paying a web designer to make simple content updates. Each of them has a current site with some standard content - and then they are linking out to a blog site. Originally I think the blog was intended as a blog. But it evolved into the only place to get new information because it was the only part of the site that the owner could update themself.

With that audience in mind, I am looking for a CMS that is:

• Easy for the end user to update page content. If they change their phone number, they should be able to hop into the admin interface, go to the “Contact” page and change the phone number in 10 minutes or less.
• They should be able to upload new pictures and place them into new or existing pages.
• It should be easy to embed YouTube videos in their pages if they want.
• The blog should function as a basic blog (tags, reverse chronological listings). I am not sure if they will want to take the time to manage comments or not, so the comment feature should do some spam detection OR allow moderation OR be configurable so it can be turned off completely.
• It should be easy for me to transfer their current site design to the new site.
• Easy for me to set up (this is a side project for me). This means it should run a fairly recent version of Rails and not have any particularly exotic dependencies.
• Support for hosting on Heroku would be nice.
• And the CMS should not get in the way of me adding custom features to the site using standard Rails development techniques. I don’t currently envision doing any custom development on these sites but I don’t want to have to move them to something else if we do come up with some cool idea - for example a distance learning tool.
• Similarly, the tool shouldn’t get in the way if we want to integrate a small e-commerce or donations component.

Looking around there are a couple of projects that look interesting. Radiant has stood the test of time but is still under active development. I like RefineryCMS’s engine-based design. I was a big fan of engines back in the Rails 1.1.6 days but gave up on them when it became too difficult to move them forward to Rails 1.2. I was really pleased when the Merb team championed the concept and got them accepted into the Rails 3 rewrite. I am also interested in trying AdvCMS - though I am a little concerned there hasn’t been a new release since I last tried (and failed) to install it.

Update December 2020: A few years ago, I was transferred to a group that primarily uses Python and a few years later, my boss discovered Wagtail, a CMS built on top of Django. It has been a great platform to use for work and I think it is also an excellent choice for people to use building and maintaining their own web sites - if they know how to host a web site. That is a very big “if” and I am afraid that my current recommendation for most of my non-tech friends would be to create something on SquareSpace and go back to managing their primary business.