NAME Etherpad - interact with Etherpad API VERSION version 1.2.14.0 SYNOPSIS use Etherpad; my $ec = Etherpad->new( url => 'http://pad.example.org', apikey => 'secret_etherpad_API_key', user => 'http_user', password => 'http_password', proxy => { http => 'http://proxy.example.org', https => 'http://proxy.example.org' } ); $ec->create_pad('new_pad_name'); DESCRIPTION Client module for the Etherpad HTTP API. The Etherpad API currently supported is the 1.2.13 (Etherpad version: 1.6.0) This module aims to replace Etherpad::API ATTRIBUTES Etherpad implements the following attributes. url my $url = $ec->url; $ec = $ec->url('http://pad.example.org'); MANDATORY. The Etherpad URL, no default. apikey my $apikey = $ec->apikey; $ec = $ec->apikey('secret_etherpad_API_key'); MANDATORY. Secret API key, located in the APIKEY.txt file of your Etherpad installation directory, no default. ua my $ua = $ec->ua; $ec = $ec->ua(Mojo::UserAgent->new); OPTIONAL. User agent, default to a Mojo::UserAgent. Please, don't use anything other than a Mojo::Useragent. user my $user = $ec->user; $ec = $ec->user('bender'); OPTIONAL. HTTP user, use it if your Etherpad is protected by a HTTP authentication, no default. password my $password = $ec->password; $ec = $ec->password('beer'); OPTIONAL. HTTP password, use it if your Etherpad is protected by a HTTP authentication, no default. proxy my $proxy = $ec->proxy; $ec = $ec->proxy({ http => 'http://proxy.example.org', https => 'http://proxy.example.org' }); OPTIONAL. Proxy settings. If set to { detect => 1 }, Etherpad will check environment variables HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, NO_PROXY and no_proxy for proxy information. No default. METHODS Etherpad inherits all methods from Mojo::Base and implements the following new ones. Groups Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test See https://etherpad.org/doc/v1.6.0/#index_groups create_group Usage : $ec->create_group(); Purpose : Creates a new group Returns : The new group ID Argument : None See : https://etherpad.org/doc/v1.6.0/#index_creategroup create_group_if_not_exists_for Usage : $ec->create_group_if_not_exists_for('groupMapper'); 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 See : https://etherpad.org/doc/v1.6.0/#index_creategroupifnotexistsfor_groupmapper delete_group Usage : $ec->delete_group('groupId'); Purpose : Deletes a group Returns : 1 if it succeeds Argument : The id of the group you want to delete See : https://etherpad.org/doc/v1.6.0/#index_deletegroup_groupid list_pads 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 See : https://etherpad.org/doc/v1.6.0/#index_listpads_groupid create_group_pad 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 See : https://etherpad.org/doc/v1.6.0/#index_creategrouppad_groupid_padname_text list_all_groups 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 Argument : None See : https://etherpad.org/doc/v1.6.0/#index_listallgroups Author These authors are bound to the attributes the users choose (color and name). See https://etherpad.org/doc/v1.6.0/#index_author create_author 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 See : https://etherpad.org/doc/v1.6.0/#index_createauthor_name create_author_if_not_exists_for 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 See : https://etherpad.org/doc/v1.6.0/#index_createauthorifnotexistsfor_authormapper_name list_pads_of_author 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 See : https://etherpad.org/doc/v1.6.0/#index_listpadsofauthor_authorid get_author_name Usage : $ec->get_author_name('authorID') Purpose : Returns the Author Name of the author Returns : The author name Argument : The epl author ID See : https://etherpad.org/doc/v1.6.0/#index_getauthorname_authorid Session 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. See https://etherpad.org/doc/v1.6.0/#index_session create_session 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) See : https://etherpad.org/doc/v1.6.0/#index_createsession_groupid_authorid_validuntil delete_session Usage : $ec->delete_session('sessionID') Purpose : Deletes a session Returns : 1 if it succeeds Argument : An epl session ID See : https://etherpad.org/doc/v1.6.0/#index_deletesession_sessionid get_session_info Usage : $ec->get_session_info('sessionID') Purpose : Returns informations about a session Returns : A hash reference, containing 3 keys : authorID, groupID and validUntil Argument : An epl session ID See : https://etherpad.org/doc/v1.6.0/#index_getsessioninfo_sessionid list_sessions_of_group 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 See : https://etherpad.org/doc/v1.6.0/#index_listsessionsofgroup_groupid list_sessions_of_author 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 See : https://etherpad.org/doc/v1.6.0/#index_listsessionsofauthor_authorid Pad Content Pad content can be updated and retrieved through the API. See https://etherpad.org/doc/v1.6.0/#index_pad_content get_text 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 See : https://etherpad.org/doc/v1.6.0/#index_gettext_padid_rev set_text 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) See : https://etherpad.org/doc/v1.6.0/#index_settext_padid_text append_text Usage : $ec->append_text('padID', 'text') Purpose : Appends text to a pad Returns : 1 if it succeeds Argument : Takes a pad ID and the text you want to append (both mandatory) See : https://etherpad.org/doc/v1.6.0/#index_appendtext_padid_text get_html 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 See : https://etherpad.org/doc/v1.6.0/#index_gethtml_padid_rev set_html Usage : $ec->set_html('padID', 'html') Purpose : Sets the text of a pad based on HTML, HTML must be well formed. Returns : 1 if it succeeds Argument : Takes a pad ID and the HTML code you want to set (both mandatory) See : https://etherpad.org/doc/v1.6.0/#index_sethtml_padid_html get_attribute_pool Usage : $ec->get_attribute_pool('padID') Purpose : Returns the attribute pool of a pad Returns : A hash reference, containing 3 keys * numToAttrib, containing a hash reference, which keys are integers and contents are array references * attribToNum, containing a hash reference, which keys are string and contents are integers * nextNum, which content is an integer Argument : Takes a pad ID (mandatory) See : https://etherpad.org/doc/v1.6.0/#index_getattributepool_padid get_revision_changeset Usage : $ec->get_revision_changeset('padID' [, rev]) Purpose : Get the changeset at a given revision, or last revision if 'rev' is not defined Returns : A string, representing an etherpad changeset Argument : Takes a pad ID (mandatory) and optionally a revision number See : https://etherpad.org/doc/v1.6.0/#index_getrevisionchangeset_padid_rev create_diff_html Usage : $ec->create_diff_html('padId', rev1, rev2) Purpose : Returns an object of diffs from 2 points in a pad Returns : A hash reference which keys are * html, which content is a string representing the diff between the two revisions * authors, which content is an array reference of authors Argument : Takes a pad ID, a revision number to start and a revision number to end. All arguments are mandatory See : https://etherpad.org/doc/v1.6.0/#index_creatediffhtml_padid_startrev_endrev restore_revision Usage : $ec->restore_revision('padId', rev) Purpose : Restores revision from past as new changeset Returns : 1 if it succeeds Argument : Takes a pad ID, a revision number to restore. All arguments are mandatory See : https://etherpad.org/doc/v1.7.0/#index_restorerevision_padid_rev Chat See https://etherpad.org/doc/v1.6.0/#index_chat get_chat_history 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. See : https://etherpad.org/doc/v1.6.0/#index_getchathistory_padid_start_end get_chat_head 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 See : https://etherpad.org/doc/v1.6.0/#index_getchathead_padid append_chat_message Usage : $ec->append_chat_message('padID', 'text', 'authorID', 'timestamp') Purpose : Add a message to chat Returns : 1 if it succeeds Argument : Takes a pad ID (mandatory), a text (mandatory), an author ID (mandatory) and a timestamp (mantdatory) See : Undocumented yet Pad 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. See https://etherpad.org/doc/v1.6.0/#index_pad create_pad 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 See : https://etherpad.org/doc/v1.6.0/#index_createpad_padid_text get_revisions_count Usage : $ec->get_revisions_count('padID') Purpose : Returns the number of revisions of this pad Returns : The number of revisions Argument : A pad ID See : https://etherpad.org/doc/v1.6.0/#index_getrevisionscount_padid get_saved_revisions_count Usage : $ec->get_saved_revisions_count('padID') Purpose : Returns the number of saved revisions of this pad Returns : The number of saved revisions Argument : A pad ID See : https://etherpad.org/doc/v1.6.0/#index_getsavedrevisionscount_padid list_saved_revisions Usage : $ec->list_saved_revisions('padID') Purpose : Returns the list of saved revisions of this pad Returns : An array or an array reference, depending of the context, containing the saved revisions numbers Argument : A pad ID See : https://etherpad.org/doc/v1.6.0/#index_listsavedrevisions_padid save_revision Usage : $ec->save_revision('padID', ['rev']) Purpose : Saves a revision Returns : 1 if it succeeds Argument : Takes a pad ID (mandatory) and optionally a revision number See : https://etherpad.org/doc/v1.6.0/#index_saverevision_padid_rev get_users_count Alias for pad_users_count (see below) pad_users_count Usage : $ec->pad_users_count('padID') Purpose : Returns the number of user that are currently editing this pad Returns : The number of users Argument : A pad ID See : https://etherpad.org/doc/v1.6.0/#index_paduserscount_padid pad_users 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 See : https://etherpad.org/doc/v1.6.0/#index_padusers_padid delete_pad Usage : $ec->delete_pad('padID') Purpose : Deletes a pad Returns : 1 if it succeeds Argument : A pad ID See : https://etherpad.org/doc/v1.6.0/#index_deletepad_padid copy_pad Usage : $ec->copy_pad('sourceID', 'destinationID' [, 1]) Purpose : Copies a pad with full history and chat. If force is true and the destination pad exists, it will be overwritten Returns : 1 if it succeeds Argument : A source pad ID A destination pad ID A force flag : a value which is true or false, in perl interpretation (for example; 0 and '' are false, 1, 2 and 'foo' are true) See : https://etherpad.org/doc/v1.6.0/#index_copypad_sourceid_destinationid_force_false move_pad Usage : $ec->move_pad('sourceID', 'destinationID' [, 1]) Purpose : Moves a pad. If force is true and the destination pad exists, it will be overwritten Returns : 1 if it succeeds Argument : A source pad ID A destination pad ID A force flag : a value which is true or false, in perl interpretation (for example; 0 and '' are false, 1, 2 and 'foo' are true) See : https://etherpad.org/doc/v1.6.0/#index_movepad_sourceid_destinationid_force_false get_read_only_id Usage : $ec->get_read_only_id('padID') Purpose : Returns the read only link of a pad Returns : A string Argument : A pad ID See : https://etherpad.org/doc/v1.6.0/#index_getreadonlyid_padid get_pad_id Usage : $ec->get_pad_id('readOnlyID') Purpose : Returns the id of a pad which is assigned to the readOnlyID Returns : A string Argument : A read only ID See : https://etherpad.org/doc/v1.6.0/#index_getpadid_readonlyid set_public_status 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 See : https://etherpad.org/doc/v1.6.0/#index_setpublicstatus_padid_publicstatus get_public_status Usage : $ec->get_public_status('padID') Purpose : Return true of false Returns : 1 or 0 Argument : A pad ID See : https://etherpad.org/doc/v1.6.0/#index_getpublicstatus_padid set_password 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 See : https://etherpad.org/doc/v1.6.0/#index_setpassword_padid_password is_password_protected Usage : $ec->is_password_protected('padID') Purpose : Returns true or false Returns : 1 or 0 Argument : A pad ID See : https://etherpad.org/doc/v1.6.0/#index_ispasswordprotected_padid list_authors_of_pad 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 See : https://etherpad.org/doc/v1.6.0/#index_listauthorsofpad_padid list_names_of_authors_of_pad 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 ID See : This is not part of the Etherpad API but a facility offered by this module get_last_edited 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 See : https://etherpad.org/doc/v1.6.0/#index_getlastedited_padid send_clients_message 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 See : https://etherpad.org/doc/v1.6.0/#index_sendclientsmessage_padid_msg check_token Usage : $ec->check_token() Purpose : Returns ok when the current api token is valid Returns : 1 if the token is valid, 0 otherwise Argument : None See : https://etherpad.org/doc/v1.6.0/#index_checktoken Pads See https://etherpad.org/doc/v1.6.0/#index_pads list_all_pads 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 See : https://etherpad.org/doc/v1.6.0/#index_listallpads Global See https://etherpad.org/doc/v1.8.3/#global (URL not usable yet) get_stats Usage : $ec->get_stats() Purpose : Get stats of the etherpad instance Returns : A hash reference, containing 3 keys : totalPads, totalSessions and totalActivePads See : https://etherpad.org/doc/v1.8.3/#getstats (URL not usable yet) INSTALL After getting the tarball on https://metacpan.org/release/Etherpad, untar it, go to the directory and: perl Makefile.PL make make test make install If you are on a windows box you should use 'nmake' rather than 'make'. BUGS and SUPPORT You can find documentation for this module with the perldoc command. perldoc Etherpad Bugs and feature requests will be tracked on: https://framagit.org/fiat-tux/etherpad/issues The latest source code can be browsed and fetched at: https://framagit.org/fiat-tux/etherpad git clone https://framagit.org/fiat-tux/etherpad.git Source code mirror: https://github.com/ldidry/etherpad You can also look for information at: AnnoCPAN: Annotated CPAN documentation http://annocpan.org/dist/Etherpad CPAN Ratings http://cpanratings.perl.org/d/Etherpad Search CPAN http://search.cpan.org/dist/Etherpad AUTHOR Luc DIDRY CPAN ID: LDIDRY ldidry@cpan.org https://fiat-tux.fr/ COPYRIGHT 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. SEE ALSO perl(1), Mojolicious AUTHOR Luc Didry COPYRIGHT AND LICENSE This software is copyright (c) 2015 by Luc Didry. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.