Confluence4r Rails Plugin

While the original Confluence4r is a nice convenient Ruby wrapper for talking to Confluence via XML-RPC, we at Encore wanted a little more convenience and abstraction. What we've come up with is a Rails plugin that provides a vaguely ActiveRecord-like interface for dealing with Confluence. You can install this as a Rails plugin by going into your Rails application's base directory and typing:

script/plugin install -x http://svn.encorewiki.org/svn/encore-dev/confluence4r/trunk

Once installed, you need to create the file config/confluence.yml in your Rails application, which should look something like this:

development:
  url: http://dev.myserver.net/confluence
  
production:
  url: http://www.myserver.net/confluence
  
test:
  url: http://test.myserver.net/confluence
  username: myusername
  password: mypassword

Authentication is, unfortunately, a bit of a problem. Since we cannot obtain authentication information from Confluence, you will probably have to ask your user to enter their login information again. For an example of how we handle Confluence authentication with Confluence4r, see the Confluence4r Rails Authentication page (hint: we ask the user again for their username and password ) Another alternative is to use a single sign on solution like CAS, although this is considerably more complicated to deploy.

Once you have your confluence.yml file set up and you've dealt with the authentication issues, you should be able to do things like:

page = Confluence::Page.find_by_title("My Page", "My Space")
page.content += "Some added content"
page.title = "My Page With a New Title!"
page.save

user = User.find_by_username("john.smith")
user.fullname = "Foo Bar"
user.save

You can also create a brand new page:

page = Confluence::Page.new
page.space = "Some Space"
page.title = "My New Page"
page.content = "Some content goes here."
page.save

Some other useful functions (most of these take effect immediately, without having to call the save method to commit):

# add user to the confluence-administrators group
user.add_to_group("confluence-administrators")

# find out if user is in group "cheeky-monkies"
user.in_group? "cheeky-monkies"

# get the page-level permissions for page (as a Hash)
page.get_permissions

# get the parent page for this page (returned as a Confluence::Page object)
page.parent

A few advanced functions require that you install the encore-macros plugin, which you can obtain via svn at svn://svn.encorewiki.org/encore-dev/encore-macros/trunk/dist/plugins-encore-macros.jar:

# make page editable only by members of the super-mega-ultra-editors group
page.edit_group = "super-mega-ultra-editors"

# make page viewable only by members of the mere-mortals group
page.view_group = "mere-mortals"

Our site makes heavy use of the Metadata Plugin – in fact I'm not entirely sure that our extended Confluence4r will work without the Metadata Plugin installed. If you have this plugin installed, you can use the Extended Confluence4r to manipulate metadata on your pages. For example, this will insert a tag into the bottom of your page, filling in the appropriate metadata values:

page = Confluence::Page.find_by_title("My Page")
page.metadata["Some Metadata Field"] = "Hello"
page.metadata["Another Metadata Field"] = "World"
page.save

Disclaimer Our Extended Confluence4r library is still under heavy development. Some of it doesn't work very well... some of it is flakey. If you find bugs – or better yet, if you find bugs and correct them – please contact me, Matt Zukowski.