How To: Getting "mental"

Posted by Sean Cribbs on Tuesday, January 23, 2007 | |

There’s been a lot of discussion lately on the mailing list about “extensions” and the “mental branch”. This is partly because RadiantCMS 0.5.2 was released what seems like eons ago. Secondly, it’s that people are becoming more excited about Radiant but are finding that it doesn’t cover everything they want to do.

In this “How To”, I’ll describe how you can install (or upgrade to) the “mental branch”, and the pros and cons of doing so.

What is “mental”?

The Radiant core team is hard at work on squashing bugs and developing a flexible system for extending Radiant’s capabilities. This is what we mean by the “mental” branch — an experimental fork of the Radiant codebase that is developed separately from the main codebase. Upon the 0.6 “Lapidary” release, the code from “mental” or its successor will be merged back to the main codebase.

What are “extensions”?

Part of what makes RadiantCMS great, in my opinion, is that it fulfills the need for most content-management scenarios with pages, layouts and snippets. It’s flexible and puts minimal restriction on the structure of the output. It reaches the 80% window. However there are those cases in the missing 20% where you might have other needs, for example:

In 0.5.2 and before, page “behaviors” fulfilled many of these concerns. For example, the Mailer behavior processes form-to-email submissions, and the RSS Behavior inserts the headlines from a news feed into a page. However, “behaviors” are focused on processing individual pages and are not well suited to, say, manipulating other models in an administration interface. This is where “extensions” come in.

Choo, Choo!

As John detailed in a recent post on his blog, extensions are vertical slices of a Rails application, or mini-applications if you will, that are inserted into Radiant at runtime. In many ways, they tackle the same problem as Rails Engines, which allow you to drop a pre-built application into your own and use it as if it were the same app. The execution of this feat has been quite arduous, and you can read more about it on John’s blog. Suffice it to say, with a minimal amount of boilerplate, you can have your own custom models, views, controllers, and libraries running inside Radiant. That’s the power of extensions.

So what?

In many instances, the debate over all this is moot. Radiant does what you need it to do. However, if you have one of those special needs that isn’t covered by one of the pre-existing behaviors, the “mental” branch can serve your needs. But first, let’s see if it is really what you need by examining the pros and cons.



I’ll leave it to you to make the decision, but if you’re ready to take the plunge, let’s learn how to set it up.

Step 0: BACKUP!

Whether you are creating a new website with Radiant or are upgrading a current one, take a moment and backup your database, static files, and configuration. Things might go wrong and you might lose a huge chunk of your website. So please, do be careful.

Step 1: Download Radiant “mental”

Make sure the directory you want the installation to reside in is empty, then run one of these commands:

$ svn checkout


$ svn export

The former will get you all of the associated Subversion properties that will let you keep your instance up to date, both with the mental branch and with Edge Rails. If you just want to dump the code out to your directory without all the SVN stuff, use the second command. I highly recommend the former.

Step 2: Setup your database

Whether you are creating a new website or upgrading an existing one, you’ll need to make your database.yml file and make sure the appropriate database is created. You can copy from one of the existing files or create your own, but that discussion is outside the scope of this post.

Once your database is ready to go, in the directory where mental resides, run rake db:migrate. This will bring your database in line with the latest schema. If this is a new website, it will also initialize your database with a simple homepage.

Step 3: Install extensions

If you know you have certain extensions to install, we’ll install those next. Most extensions are distributed using (surprise!) Subversion. If you downloaded mental using ‘svn checkout’, it’s easiest to set an ‘external’ on the vendor/extensions directory. Before you try this, make sure your EDITOR environment variable is set (I like ‘vi’, but you could use ‘emacs’ or ‘pico’ or whatever).

$ svn propedit svn:externals vendor/extensions

Once your editor is open, put the name of each extension on its own line followed by a space, then the URL of its repository location. Here’s an example:

mailer part_assets

Then run ‘svn update vendor/extensions’ and Subversion will download the extensions. Your last step is to make sure the database is up-to-date with the schema that the extensions need. Run this command:

$ rake db:migrate:extensions

Now your extensions should be ready to go!

Step 4: (Re-)Start up your server

This one’s pretty self explanatory. Do whatever you need to do to start your server, then try out your new Radiant!