Etherpad::API - Access Etherpad Lite API easily
use Etherpad::API; my $ec = Etherpad::API->new({ url => "http://pad.example.com", apikey => "teirnausetsraunieti", user => "apiuser", password => "apipassword" }); $ec->create_pad('new_pad_name');
This is a client for the Etherpad Lite HTTP API.
Usage : my $ec = Etherpad::API->new({ url => "http://pad.example.com", apikey => "secretapikey" }); Purpose : Constructor Returns : An Etherpad::API object Argument : An mandatory hash reference, containing at least two keys: url : mandatory, the epl URL (trailing slashes will be removed) apikey : mandatory, the epl API key user : optional, the user for epl authentication password : optional, the passowrd for epl authentication
Usage : $ec->apikey(); Purpose : Get the apikey Returns : The apikey
Usage : $ec->url(); Purpose : Get the epl URL Returns : The epl URL
Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test
Usage : $ec->create_group(); Purpose : Creates a new group Returns : The new group ID
Usage : $ec->create_group_if_not_exists_for('myGroupId'); Purpose : This functions helps you to map your application group ids to epl group ids Returns : The epl group id Argument : Your application group id
Usage : $ec->delete_group('groupId'); Purpose : Deletes a group Returns : 1 if it succeeds Argument : The id of the group you want to delete
Usage : $ec->list_pads('groupId'); Purpose : Returns all pads of this group Returns : An array or an array reference (depending on the context) which contains the pad ids Argument : The id of the group from which you want the pads
Usage : $ec->create_group_pad('groupID', 'padName' [, 'text']) Purpose : Creates a new pad in this group Returns : 1 if it succeeds Argument : The group id, the pad name, optionally takes the pad's initial text
Usage : $ec->list_all_groups() Purpose : Lists all existing groups Returns : An array or an array reference (depending on the context) which contains the groups ids
These authors are bound to the attributes the users choose (color and name).
Usage : $ec->create_author(['name']) Purpose : Creates a new author Returns : The new author ID Argument : Optionally takes a string as argument : the new author's name
Usage : $ec->create_author_if_not_exists_for(authorMapper [, name]) Purpose : This functions helps you to map your application author ids to epl author ids Returns : The epl author ID Argument : Your application author ID (mandatory) and optionally the epl author name
Usage : $ec->list_pads_of_author('authorID') Purpose : Returns an array of all pads this author contributed to Returns : An array or an array reference depending on the context, containing the pads names Argument : An epl author ID
Usage : $ec->get_author_name('authorID') Purpose : Returns the Author Name of the author Returns : The author name Argument : The epl author ID
Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-seperated sessionIDs, allowing a user to edit pads in different groups at the same time. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out.
Usage : $ec->create_session('groupID', 'authorID', 'validUntil') Purpose : Creates a new session. validUntil is an unix timestamp in seconds Returns : The epl session ID Argument : An epl group ID, an epl author ID and an valid unix timestamp (the session validity end date)
Usage : $ec->delete_session('sessionID') Purpose : Deletes a session Returns : 1 if it succeeds Argument : An epl session ID
Usage : $ec->get_session_info('sessionID') Purpose : Returns informations about a session Returns : An hash reference, containing 3 keys : authorID, groupID and validUntil Argument : An epl session ID
Usage : $ec->list_sessions_of_group('groupID') Purpose : Returns all sessions of a group Returns : Returns a hash reference, which keys are sessions ID and values are sessions infos (see get_session_info) Argument : An epl group ID
Usage : $ec->list_sessions_of_author('authorID') Purpose : Returns all sessions of an author Returns : Returns a hash reference, which keys are sessions ID and values are sessions infos (see get_session_info) Argument : An epl group ID
Pad content can be updated and retrieved through the API.
Usage : $ec->get_text('padID', ['rev']) Purpose : Returns the text of a pad Returns : A string, containing the text of the pad Argument : Takes a pad ID (mandatory) and optionally a revision number
Usage : $ec->set_text('padID', 'text') Purpose : Sets the text of a pad Returns : 1 if it succeeds Argument : Takes a pad ID and the text you want to set (both mandatory)
Usage : $ec->get_html('padID', ['rev']) Purpose : Returns the text of a pad formatted as html Returns : A string, containing the text of the pad formatted as html Argument : Takes a pad ID (mandatory) and optionally a revision number
Usage : $ec->get_chat_history('padID' [, start, end]) Purpose : Returns - a part of the chat history, when start and end are given - the whole chat history, when no extra parameters are given Returns : An array or an array reference, depending of the context, containing hash references with 4 keys : - text => text of the message - userId => epl user id - time => unix timestamp of the message - userName => epl user name Argument : Takes a pad ID (mandatory) and optionally the start and the end numbers of the messages you want. The start number can't be higher than or equal to the current chatHead. The first chat message is number 0. If you specify a start but not an end, all messages will be returned.
Usage : $ec->get_chat_head('padID') Purpose : Returns the chatHead (last number of the last chat-message) of the pad Returns : The last chat-message number. -1 if there is no chat message Argument : A pad ID
Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and its forbidden for normal pads to include a $ in the name.
Usage : $ec->create_pad('padID' [, 'text']) Purpose : Creates a new (non-group) pad. Note that if you need to create a group Pad, you should call create_group_pad. Returns : 1 if it succeeds Argument : Takes a pad ID (mandatory) and optionally a text to fill the pad
Usage : $ec->get_revisions_count('padID') Purpose : Returns the number of revisions of this pad Returns : The number of revisions Argument : A pad ID
Usage : $ec->get_users_count('padID') Purpose : Returns the number of user that are currently editing this pad Returns : The number of users Argument : A pad ID
Usage : $ec->pad_users('padID') Purpose : Returns the list of users that are currently editing this pad Returns : An array or an array reference, depending of the context, containing hash references with 3 keys : colorId, name and timestamp Argument : A pad ID
Usage : $ec->delete_pad('padID') Purpose : Deletes a pad Returns : 1 if it succeeds Argument : A pad ID
Usage : $ec->get_read_only_id('padID') Purpose : Returns the read only link of a pad Returns : A string Argument : A pad ID
Usage : $ec->set_public_status('padID', 'publicStatus') Purpose : Sets a boolean for the public status of a pad Returns : 1 if it succeeds Argument : A pad ID and the public status you want to set : 1 or 0
Usage : $ec->get_public_status('padID') Purpose : Return true of false Returns : 1 or 0 Argument : A pad ID
Usage : $ec->set_password('padID', 'password') Purpose : Returns ok or a error message Returns : 1 if it succeeds Argument : A pad ID and a password
Usage : $ec->is_password_protected('padID') Purpose : Returns true or false Returns : 1 or 0 Argument : A pad ID
Usage : $ec->list_authors_of_pad('padID') Purpose : Returns an array of authors who contributed to this pad Returns : An array or an array reference depending on the context, containing the epl authors IDs Argument : A pad ID
Usage : $ec->list_names_authors_of_pad('padID') Returns : Returns an array of the names of the authors who contributed to this pad in list context Returns an array reference in scalar context Argument : The pad name
Usage : $ec->get_last_edited('padID') Purpose : Returns the timestamp of the last revision of the pad Returns : A unix timestamp Argument : A pad ID
Usage : $ec->send_clients_message('padID', 'msg') Purpose : Sends a custom message of type msg to the pad Returns : 1 if it succeeds Argument : A pad ID and the message you want to send
Usage : $ec->check_token() Purpose : Returns ok when the current api token is valid Returns : 1 if the token is valid, 0 otherwise
Usage : $ec->list_all_pads() Purpose : Lists all pads on this epl instance Returns : An array or an array reference depending on the context, containing the pads names
You can find documentation for this module with the perldoc command.
perldoc Etherpad::API
Bugs and feature requests will be tracked at RT:
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Etherpad-API bug-etherpad-api at rt.cpan.org
The latest source code can be browsed and fetched at:
https://github.com/ldidry/etherpad-api git clone git://github.com/ldidry/etherpad-api.git
You can also look for information at:
RT: CPAN's request tracker http://rt.cpan.org/NoAuth/Bugs.html?Dist=Etherpad-API AnnoCPAN: Annotated CPAN documentation http://annocpan.org/dist/Etherpad-API CPAN Ratings http://cpanratings.perl.org/d/Etherpad-API Search CPAN http://search.cpan.org/dist/Etherpad-API
Luc DIDRY CPAN ID: LDIDRY ldidry@cpan.org http://www.fiat-tux.fr/
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
perl(1).
To install Etherpad::API, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Etherpad::API
CPAN shell
perl -MCPAN -e shell install Etherpad::API
For more information on module installation, please visit the detailed CPAN module installation guide.