Extensions

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:

• Integration with some back-end data service
• Management of a complex data structure that doesn’t fit into the Radiant page-layout-snippet structure (or fits poorly)
• Receiving and processing input from the website visitor through forms or other means
• Complex manipulation of content information that would be impossible or too cumbersome using Radius

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.

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.

Installing Extensions

A number of extensions are available for download on the Thirdparty Extensions page.

Using Subversion Externals

If you are using Subversion for your Radiant project, the best way to install an extension is to use “svn:externals”.

cd /path/to/radiant
svn propedit svn:externals vendor/extensions

Your editor should start up. Then add a line for the extension you’d like to use:

extension_name http://example.com/svn/extension_name/trunk

Save your changes then do an update:

svn update vendor/extensions

Alternatively

You can use Subversion to export the extension into your vendor/extensions directory. This is the approach to take if you are not using Subversion for your project, but you want to use an extension from someone else’s repository:

cd /path/to/radiant
svn export http://example.com/svn/extension_name/trunk vendor/extensions/extension_name

Installation for Extensions that Don’t Use Subversion

If the extension author provides a .zip or .tar.gz file, just extract it into your vendor/extensions directory

cd /path/to/radiant
cd vendor/extensions
tar zxf /path/to/extension.tar.gz

Migrate Your Database for New Extensions

An extension may require that you update your database. Radiant provides a simple migration to get you up to speed:

$ rake db:migrate:extensions

Now your extensions should be ready to go! (Extension developers should remember to always update their README files or provide adequate information on the use and function of your extension elswhere).

Note on extension directory naming

In order to correctly load extensions, Radiant needs that the extension’s directory name matches the extension’s (class) name.

The matching rule is the standard Rails camelcase <-> snakecase rule. For example, for an extension called “Foo” the extension directory name must be named “foo”. And for an extension named “FooBar”, the directory name must be “foo_bar”. If you fail to follow this convention, Radiant will fail to load the extension and the application won’t start.

How to know an extension’s real name? For that look inside the extension directory for a file whose name ends in “_extension.rb”. That’s the extension’s main load file. The extension’s real name is the name before that ending. In the previous examples, that file would be called “foo_extension.rb” and “foo_bar_extension.rb” respectively.

Creating Your Own Extensions

See the Creating Radiant Extensions tutorial.