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')
=> {:text => "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.