Comparing version 19 and version 18

h2. 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":http://www.wiseheartdesign.com/2006/12/6/rails-needs-something-better-than-engines/. 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.

h2. Installing Extensions

A [[Thirdparty Extensions|number of extensions]] are available for download.

h3. 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 [-r REV_NUMBER] http://example.com/svn/extension_name/trunk


Alternatively if you can’t get that to work here’s another way:


svn propset svn:externals "extension_name -rRevison# http://repo/extension" vendor/extensions/.


For example, to get the page_attachments extension:


svn propset svn:externals "page_attachments -r869 http://svn.radiantcms.org/radiant/trunk/extensions/page_attachments" vendor/extensions/.


Save your changes then do an update:


svn update vendor/extensions


h3. 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. You can either export or checkout—export gives you only the files (good for tags), but means you’ll have to update manually. checkout includes .svn junk, but you can update easily using svn update (good for trunk).


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


h3. 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


h3. 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


h3. Edit config/environment.rb (if necessary)

It may be necessary to explicitly load extensions, for instance, to ensure that dependencies are satisfied in the correct order.  For example, several extensions depend on the Shards extension, so to ensure that Shards loads before the extensions that depend on it, uncomment and edit the following line in config/environment.rb like so:


config.extensions = [ :shards, :textile_filter, :markdown_filter, :all ]


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).

h3. 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. You'll get an error when migrating the database like:


Could not load extension from file: some_extension.
#


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.

h2. Creating Your Own Extensions

See the [[Creating Radiant Extensions]] tutorial.

h2. Ideas For Future Extensions

See [[Extension Ideas]].

h2. Uninstalling Extensions

Right now the easiest way is to just remove the directory.  If the  extension migrations changed something, run this first:


rake radiant:extensions:extension_name:migrate VERSION=0


Be careful depending on this; it's possible the extension will fail to uninstall everything. Use a DB backup!

Back to Page