Ray is just a rake file with some tasks that simplify the installation, disabling, enabling, uninstallation and searching
of Radiant extensions. Although Ray relies on GitHub (as the extension host) it does not rely on the git
command line tools; if you don’t have git installed then the Ruby Open-URI library is used to download
compressed archives.
In other words, you need at least git or tar installed in addition to the normal Radiant stack;
Windows users probably need one of those “unixy” environment things since Ray does occasionally call out to
system tools (I really don’t know about Windows though). Ray only supports git;
although I’d gladly accept a patch that used git’s tools to access CVS, SVN or whatever else it can handle.
If you need to install extensions from other sources, such as Subversion, you should use Radiant’s built-in
script/extension install command which can handle a wide variety of installation types.
If you have Radiant 0.6.8 or newer simply run
script/extension install ray
If you’re on an older version of Radiant and have git installed, move to your Radiant site’s
vendor/extension directory and run
git clone git://github.com/johnmuhl/radiant-ray-extension.git ray
If you prefer to manage your extensions as git submodules, move to your Radiant site’s
vendor/extension directory and run
git submodule add git://github.com/johnmuhl/radiant-ray-extension.git ray
If you don’t have git installed download the
tar or
zip
archive from GitHub, unpack it and place it in vendor/extensions/ray.
Ray does not have any installation tasks to run, in fact you don’t even need to restart Radiant in order to start using the tasks.
cd vendor/extensions/ray
git pull origin master
Delete your existing version, then download the
tar or
zip
archive from GitHub, unpack it and place it in vendor/extensions/ray.
Note: You can run rake ray:help:shortcuts for a list of shorter versions of the most common
commands.
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.”
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:allAdditionally, you can use:
rake ray:extension:home name=blogto 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.
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_nameAfter 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_nameAs 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.
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 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.
Note: If your extension dependencies have their own dependencies it’s best if each extension only includes it’s immediate dependents and let the dependencies cascade until they have all been satisfied; i.e. if your extension requires X which requires Y which requires Z only declare your dependence on X and have Y declare it’s dependence on Z and so on.
While extension bundling is for site maintainers, extension dependencies are for extension authors. As you can probably
guess it lets you tell Ray about your extension’s dependencies. All you need is a dependency.yml file in
the root directory of your extension. Here’s an example dependency file:
- extension: my_extension_helpers
You can list as many dependencies as you need and they can include gems as well as other extensions. In the case of
extensions you may also use the hub option if you depend on a forked version of a repository.
- extension: this_extension_helps_a_ton
hub: extension_forker
- extension: some_other_voodoo
- gem: this_one
- gem: that_too
The absence of support for plugin dependencies is intentional. You are much better off adding plugins to your extension as
git submodules and letting Ray deal with them during the normal installation of your extension. As an added
bonus your plugin dependencies will also be recognized and respected by Radiant’s built-in script/extension
install.
Note: dependencies.yml is an acceptable file name and .yaml is an acceptable
file extension.
The most important of Ray’s setup tasks, rake ray:setup:download, will be run for you automatically the
first time you try to install an extension. However you might not have had git installed when you initially
installed Ray. If that’s the case you can change your preference by running:
rake ray:setup:download
Ray’s other setup task, rake ray:setup:restart, can be used to have Ray automatically restart your
server whenever necessary, such as after you install a new extension. Currently, Ray supports restarting a single Mongrel,
a Mongrel cluster, Phusion Passenger, Thin or Unicorn; note: single Mongrels, Thin and Unicorn need to be running in daemon
mode.
rake ray:setup:restart server=mongrel_cluster
rake ray:setup:restart server=mongrel
rake ray:setup:restart server=passenger
rake ray:setup:restart server=thin
rake ray:setup:restart server=unicorn
Before you get going with remote branches in Ray you’ll need to make sure you’ve setup at least your GitHub
username in your global git configuration file.
git config --global github.user your_github_username
That will add a bit of code to your ~/.gitconfig file. Ray can then use that information to determine when
you’re installing your own extensions. Now when you install from your own repositories Ray will use your private
URL instead of the public one; which means you can push your local changes back to your GitHub repository.
Now you can install your extensions as you normally would with Ray. Then tell Ray which other users you want to track.
rake ray:extension:install name=extension
rake ray:extension:remote name=extension hub=other_user
As you add remotes Ray will setup tracking branches named like “other_user/branch_name” for each branch the
remote user has in their repository. Nothing is merged by Ray and you’ll be returned to your current branch after the
remote is setup. Just like when you’re using git directly you’ll want to make sure your
current branch is clean (commit or stash) before adding remotes; and afterward use your normal git
workflow to inspect and merge changes.
Once you’ve setup a remote repository on an extension you’ll want to pull down the changes occasionally. You can pull in the remote repositories for either a specific extension or all extensions with remotes setup.
# pull remotes on a single extension
rake ray:extension:pull name=extension_name
# pull remotes on all extensions
rake ray:extension:pull
Ray does not merge anything into your master branch, after pulling in changes use your normal
git workflow to inspect and merge these changes.
For the most part each Ray release is “compatible” with the previous one. Occasionally though things change between versions, you can find out all about what “breaking” changes the latest version has here.
In some cases, a shortcut that existed in Ray 1.x will no longer be present in Ray 2.×. Although the command is still there in long form you may find this to be a particular hassle, in that case please create a ticket complaining about it and I’ll give you your shortcut back.
extensions.yml?”
All users of the extension bundling mechanism will need to update their extensions.yml before Ray 2.x can
understand them. This is mainly because the original format was not very well considered; you’ll find most of your
updating gets done with the delete key.
For example, the old demonstration extensions.yml which looked like:
---
- name: aggregation
- name: link-roll
- name: help
hub: saturnflyer
- name: markdown
hub: johnmuhl
lib: rdiscount
vendor: markdown_filter
- name: page_attachments
plugin: attachment_fu
plugin_repository: technoweenie
lib: mini_magick
- name: blog
hub: netzpirat
remote: saturnflyer/radiant-blog-extensionIn Ray 2, the same extensions.yml looks basically the same; just with more less:
---
- name: aggregation
- name: link-roll
- name: help
- name: markdown
- name: page-attachments
lib: mini_magick
- name: blog
hub: netzpirat
remote:
- saturnflyer
You don’t need to list the lib on the RDiscount Markdown filter because it
declares it’s own dependencies. For an extension that requires a gem but
doesn’t declare it’s dependencies you’ll still need to use the lib option.
Users of previous versions may notice that the commands have changed. While this appears to be the case it’s not
actually (mostly). All the same old commands are available, so if you got comfortable with
rake ray:extension:install name=mailer and don’t want to switch to rake ray:i name=mailer
you can keep right on using the long versions. You can get a reminder of the shortcuts with the
rake ray:help:shortcuts command.
Copyright © 2008, 2009 john muhl
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.