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.

README.rdoc