Skip to content
This repository

An Etherpad Lite client library for Ruby

README.rdoc

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

Copyright 2011 Jordan Hollinger

Licensed under the Apache License

Credit

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

Something went wrong with that request. Please try again.