Etherpad Lite Ruby Client

The etherpad-lite Ruby Gem is a Ruby client for Etherpad Lite's HTTP JSON API. Etherpad Lite is a collaborative editor provided by the Etherpad Foundation.

See github.com/ether/etherpad-lite for information on how to install and configure your own Etherpad Lite instance, and read etherpad.org/doc/v1.2.0/#index_http_api for an in-depth description of Etherpad Lite's HTTP API.

Installation

gem install etherpad-lite

NOTE Nobody likes you, Ruby 1.8. Now go away.

Basic usage

require 'etherpad-lite'

# Connect to your Etherpad Lite instance
ether = EtherpadLite.connect('http://etherpad-lite.example.com', 'the api key', '1.2.1')

# Get a Pad (or create one if it doesn't exist)
pad = ether.pad('my first etherpad lite pad')

puts pad.text
=> "Welcome to Etherpad Lite!\n\nThis pad text is synchronized as you type, so that everyone viewing..."

# Write your the changes to the Pad
pad.text = "What hath God wrought?"

# There are now 2 revisions!
puts pad.revision_numbers
=> [0, 1]

# Iterate through each revision
pad.revisions.each do |pad_rev|
  puts "Revision #{pad_rev.rev}:"
  puts pad_rev.text
end

Advanced usage

The above example deals with public pads, accessible to anyone through the Web UI. There is another class of pads - group pads - which deal with groups, authors and sessions. Examples are documented in EtherpadLite::Group, EtherpadLite::Author, and EtherpadLite::Session.

Example use in Rails

For your view, I recommend the jQuery plugin at github.com/ether/etherpad-lite-jquery-plugin. Also, I recommend reading the docs for EtherpadLite::Group first.

Add the following to your Gemfile gem 'etherpad-lite'

On login, create a Hash in your session to store EtherpadLite API sessions:

session[:ep_sessions] = {}

Some example controller actions:

class EtherpadController < ApplicationController
# /etherpad
def index
  # Your users are probably members of some kind of groups.
  # These groups can be mapped to EtherpadLite Groups. List all the user's groups.
  @app_groups = current_user.groups
end

# /etherpad/groups/:id
def group
  ether = EtherpadLite.connect(9001, File.new('/srv/www/etherpad-lite/APIKEY.txt'))
  @app_group = YourAppGroup.find(params[:id])
  # Map your app's group to an EtherpadLite Group, and list all its pads
  group = ether.group("my_app_group_#{@app_group.id}")
  @pads = group.pads
end

# /etherpad/pads/:ep_group_id/:ep_pad_name
def pad
  ether = EtherpadLite.connect(9001, File.new('/srv/www/etherpad-lite/APIKEY.txt'))
  # Get the EtherpadLite Group and Pad by id
  @group = ether.get_group(params[:ep_group_id])
  @pad = @group.pad(params[:ep_pad_name])
  # Map the user to an EtherpadLite Author
  author = ether.author("my_app_user_#{current_user.id}", name: current_user.name)
  # Get or create an hour-long session for this Author in this Group
  sess = session[:ep_sessions][@group.id] ? ether.get_session(session[:ep_sessions][@group.id]) : @group.create_session(author, 60)
  if sess.expired?
    sess.delete
    sess = @group.create_session(author, 60)
  end
  session[:ep_sessions][@group.id] = sess.id
  # Set the EtherpadLite session cookie. This will automatically be picked up by the jQuery plugin's iframe.
  cookies[:sessionID] = {value: sess.id, domain: ".yourdomain.com"}
end
end

Low-level client

There is an optional low-level client, which is a paper-thin wrapper around Etherpad Lite's HTTP JSON API. In the examples above, the low-level client is accessible from the high-level interface: client = ether.client client.getText(padID: 'my first etherpad lite pad') => => "What hath God wrought?"

or you can explicitly load just the low-level client: require 'etherpad-lite/client' client = EtherpadLite.client('http://beta.etherpad.org/api', 'api key', 1.1) client.setText(padID: 'my first etherpad lite pad', text: "lots of new text and stuff")

The methods and parameters exactly match the HTTP API. For a full list of them, see etherpad.org/doc/v1.2.0/#index_http_api.

Testing

Testing this library is fairly simple. It requires:

A recent version of Rspec
A running copy of Etherpad Lite with a fresh db for each run of the tests (configure connection in spec/config.yml)

Bring up Etherpad Lite with:

rm var/dirty.db && bin/run.sh

Run the tests with

rspec spec

License

Licensed under the Apache License

Credit

This Ruby client was inspired by TomNomNom's PHP client and devjones's Python client.