Note: You can run rake ray:help:shortcuts for a list of shorter versions of the most common commands.

Installing extensions

Most of what you’re likely to be doing with Ray is installing extensions, so Ray tries to make this as easy as possible. You don’t even need to know the name or author of the extension you want to install.

Take a look at the output from this command and you’ll see what I mean.

rake ray:extension:install name=meta

==============================================================================
I couldn't find an extension named 'meta'.
The following is a list of extensions that might be related.
Use the command listed to install the appropriate extension.
==============================================================================
  extension: metaweblog
     author: skrat
description: Radiant extension to allow publishing/adding pages via MetaWeb...
    command: rake ray:extension:install name=metaweblog
==============================================================================
  extension: seo_help
     author: saturnflyer
description: Provides extra tags for page meta information.
    command: rake ray:extension:install name=seo_help
==============================================================================

What happened was Ray searched for an extension named “meta”, didn’t find one, then searched through all the available extensions for the ones that include “meta” in their name or description. Notice on the last line of each extension listing is the Ray command you’d run to install that extension. Don’t worry, if you know the name of the extension you want it will be installed “no questions asked.”

Searching for extensions

While not installing extensions you’ll probably spend a fair amount of time looking for extensions that fulfill your various desires. Of course, you can just jump on GitHub, search around and then come back to the terminal to install your finds; but why bother ever leaving the terminal?

rake ray:extension:search term=blog
  
==============================================================================
  extension: metaweblog
     author: skrat
description: Radiant extension to allow publishing/adding pages via MetaWeb...
    command: rake ray:extension:install name=metaweblog
==============================================================================
  extension: import-mephisto
     author: martinbtt
description: Radiant extension that aids in the process of migrating from t...
    command: rake ray:extension:install name=import-mephisto
==============================================================================
  extension: blog
     author: saturnflyer
description: Adds features for blogging
    command: rake ray:extension:install name=blog
==============================================================================
  extension: blogtags
     author: santry
description: An extension that provides some useful blogging tags for the R...
    command: rake ray:extension:install name=blogtags
==============================================================================

Again the Ray command you’d run to install an extension is listed on the last line of each extension listing. I imagine you’re now asking, “But how do I spend a rainy day exploring the 150+ extensions for Radiant?”

rake ray:extension:all

Additionally, you can use:

rake ray:extension:home name=blog

to quickly open your default browser to the Github page for any extension. Which is handy when the truncated descriptions from the search aren’t completely useful, you want more information or need help with an extension.

Disabling extensions

Regardless whether or not you used Ray to install an extension, Ray can disable it for you. Disabling an extension is a safe operation in that no data is destroyed, it’s just moved to a location where Radiant doesn’t look for extensions.

rake ray:extension:disable name=extension_name

Enabling extensions

After you’ve disabled an extension with Ray you can enable it again just as easily. Enabling an extension is only possible if you disabled it with Ray; it is not for installing new extensions.

rake ray:extension:enable name=extension_name

Uninstalling extensions

As with disabling it doesn’t matter whether or not you used Ray to install an extension, Ray can uninstall it for you. Uninstalling an extension destroys as much data associated with the extension as possible, and is therefore not recommend in all but the most extreme cases when you are sure you’re really done with an extension.

rake ray:extension:uninstall name=extension_name

Due to the nature of extensions it’s not possible to guarantee all the static assets (javascripts, stylesheets, images, etc.) will be deleted. Since these files reside in various locations throughout your site/public directory Ray chooses to take a conservative approach when tracking files down for deletion. Therefore, if you’re really dedicated to getting rid of all traces of an extension you’ll still need to poke around in site/public to manually verify the uninstallation of static assets.

Updating extensions

Ray makes updating your installed extensions simple.

rake ray:extension:update           # update Ray
rake ray:extension:update name=xyz  # update the xyz extension
rake ray:extension:update name=all  # update all extensions (except Ray)

Currently Ray itself can only be updated with Git but I’d like to change this in the near future. All other extensions can be updated with Git or HTTP.

Bundling extensions

Bundling extensions is handy for site maintainers who want to spend a little less time re-installing a site’s extensions every time they load it up on a new system. The idea is provide a single file that describes the extensions and extension dependencies that Ray can then examine and act upon.

To use this feature you’ll need to create a file called extensions.yml inside your site/config directory. Here’s an example extensions.yml file.

---
- name: aggregation
- name: link-roll
- name: help
- name: markdown
- name: page_attachments
  lib: mini_magick
- name: blog
  hub: netzpirat
  remote:
    - saturnflyer

If you have an existing extensions.yml file you use with Ray 1.x you’ll need to update it before it’s compatibile with Ray 2.x; mostly this will just require deleting things that Ray can now determine on its own.

Once you’ve created your extensions.yml file you can install those extensions by running the command:

rake ray:extension:bundle

Please refer to the Legacy Information page for details on upgrading a Ray 1.x extensions.yml bundle file.