diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..5f081f27e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Developer Guidelines + +Please talk to people on the mailing list before you change this page + +Mailing list: https://groups.google.com/forum/?fromgroups#!forum/etherpad-lite-dev + +IRC channels: [#etherpad](irc://freenode/#etherpad) ([webchat](webchat.freenode.net?channels=etherpad)), [#etherpad-lite-dev](irc://freenode/#etherpad-lite-dev) ([webchat](webchat.freenode.net?channels=etherpad-lite-dev)) + +**Our goal is to iterate in small steps. Release often, release early. Evolution instead of a revolution** + +## General goals of Etherpad Lite +* easy to install for admins +* easy to use for people +* using less resources on server side +* easy to embed for admins +* also runable as etherpad lite only +* keep it maintainable, we don't wanna end ob as the monster Etherpad was +* extensible, as much functionality should be extendable with plugins so changes don't have to be done in core + +## How to code: +* **Please write comments**. I don't mean you have to comment every line and every loop. I just mean, if you do anything thats a bit complex or a bit weird, please leave a comment. It's easy to do that if you do while you're writing the code. Keep in mind that you will probably leave the project at some point and that other people will read your code. Undocumented huge amounts of code are worthless +* Never ever use tabs +* Indentation: JS/CSS: 2 spaces; HTML: 4 spaces +* Don't overengineer. Don't try to solve any possible problem in one step. Try to solve problems as easy as possible and improve the solution over time +* Do generalize sooner or later - if an old solution hacked together according to the above point, poses more problems than it solves today, reengineer it, with the lessons learned taken into account. +* Keep it compatible to API-Clients/older DBs/configurations. Don't make incompatible changes the protocol/database format without good reasons + +## How to work with git +* Make a new branch for every feature you're working on. Don't work in your master branch. This ensures that you can work you can do lot of small pull requests instead of one big one with complete different features +* Don't use the online edit function of github. This only creates ugly and not working commits +* Test before you push. Sounds easy, it isn't +* Try to make clean commits that are easy readable +* Don't check in stuff that gets generated during build or runtime (like jquery, minified files, dbs etc...) +* Make pull requests from your feature branch to our develop branch once your feature is ready +* Make small pull requests that are easy to review but make sure they do add value by themselves / individually + +## Branching model in Etherpad Lite +see git flow http://nvie.com/posts/a-successful-git-branching-model/ + +* master, the stable. This is the branch everyone should use for production stuff +* develop, everything that is READY to go into master at some point in time. This stuff is tested and ready to go out +* release branches, stuff that should go into master very soon, only bugfixes go into these (see http://nvie.com/posts/a-successful-git-branching-model/ for why) +* you can set tags in the master branch, there is no real need for release branches imho +* The latest tag is not what is shown in github by default. Doing a clone of master should give you latest stable, not what is gonna be latest stable in a week, also, we should not be blocking new features to develop, just because we feel that we should be releasing it to master soon. This is the situation that release branches solve/handle. +* hotfix branches, fixes for bugs in master +* feature branches (in your own repos), these are the branches where you develop your features in. If its ready to go out, it will be merged into develop + +Over the time we pull features from feature branches into the develop branch. Every month we pull from develop into master. Bugs in master get fixed in hotfix branches. These branches will get merged into master AND develop. There should never be commits in master that aren't in develop + +## Documentation +The docs are in the `doc/` folder in the git repository, so people can easily find the suitable docs for the current git revision. + +Documentation should be kept up-to-date. This means, whenever you add a new API method, add a new hook or change the database model, pack the relevant changes to the docs in the same pull request. + +You can build the docs e.g. produce html, using `make docs`. At some point in the future we will provide an online documentation. The current documentation in the github wiki should always reflect the state of `master` (!), since there are no docs in master, yet. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..01f30701b --- /dev/null +++ b/Makefile @@ -0,0 +1,13 @@ +doc_dirs = doc $(wildcard doc/*/) +outdoc_dirs = out $(addprefix out/,$(doc_dirs)) +doc_sources = $(wildcard doc/*/*.md) $(wildcard doc/*.md) +outdoc_files = $(addprefix out/,$(doc_sources:.md=.html)) + +docs: $(outdoc_files) + +out/doc/%.html: doc/%.md + mkdir -p $(@D) + node tools/doc/generate.js --format=html --template=doc/template.html $< > $@ + +clean: + rm -rf out/ diff --git a/README.md b/README.md index e3acfc383..deb2ced23 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,13 @@ -# Our goal is to make collaborative editing the standard on the web +# Making collaborative editing the standard on the web # About Etherpad lite is a really-real time collaborative editor spawned from the Hell fire of Etherpad. We're reusing the well tested Etherpad easysync library to make it really realtime. Etherpad Lite is based on node.js ergo is much lighter and more stable than the original Etherpad. Our hope is that this will encourage more users to use and install a realtime collaborative editor. A smaller, manageable and well -documented codebase makes it easier for developers to improve the code and contribute towards the project. +documented codebase makes it easier for developers to improve the code and contribute towards the project. -Etherpad Lite is optimized to be easy embeddable. It provides a [HTTP API](https://github.com/Pita/etherpad-lite/wiki/HTTP-API) -that allows your web application to manage pads, users and groups. -There are several clients in for this API: - -* [PHP](https://github.com/TomNomNom/etherpad-lite-client), thx to [TomNomNom](https://github.com/TomNomNom) -* [.Net](https://github.com/ja-jo/EtherpadLiteDotNet), thx to [ja-jo](https://github.com/ja-jo) -* [Node.js](https://github.com/tomassedovic/etherpad-lite-client-js), thx to [tomassedovic](https://github.com/tomassedovic) -* [Ruby](https://github.com/jhollinger/ruby-etherpad-lite), thx to [jhollinger](https://github.com/jhollinger) -* [Python](https://github.com/devjones/PyEtherpadLite), thx to [devjones](https://github.com/devjones) - -There is also a [jQuery plugin](https://github.com/johnyma22/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website - -**Online demo**
-Visit to test it live - -Here is the **[FAQ](https://github.com/Pita/etherpad-lite/wiki/FAQ)** - -# Etherpad vs Etherpad Lite +**Etherpad vs Etherpad lite** @@ -41,81 +24,93 @@ Here is the **[FAQ](https://github.com/Pita/etherpad-lite/wiki/FAQ)** -
 EtherpadEtherpad Lite
RAM Usage immediately after start257 MB (grows to ~1GB)16 MB (grows to ~30MB)
+ + + +Etherpad Lite is designed to be easily embeddable and provides a [HTTP API](https://github.com/Pita/etherpad-lite/wiki/HTTP-API) +that allows your web application to manage pads, users and groups. It is recommended to use the client implementations available for this API, listed on [this wiki page](https://github.com/Pita/etherpad-lite/wiki/HTTP-API-client-libraries). +There is also a [jQuery plugin](https://github.com/johnyma22/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website + +**Visit [beta.etherpad.org](http://beta.etherpad.org) to test it live** + +Also, check out the **[FAQ](https://github.com/Pita/etherpad-lite/wiki/FAQ)**, really! # Installation ## Windows -1. Download -2. Extract the file -3. Open the extracted folder and double click `start.bat` -4. Open your web browser and browse to . You like it? Look at the 'Next Steps' section below +### Prebuilt windows package +This package works out of the box on any windows machine, but it's not very useful for developing purposes... + +1. Download the windows package +2. Extract the folder + +Now, run `start.bat` and open in your browser. You like it? [Next steps](#next-steps). + +### Fancy install +You'll need [node.js](http://nodejs.org) and (optionally, though recommended) git. + +1. Grab the source, either + - download + - or `git clone https://github.com/Pita/etherpad-lite.git` (for this you need git, obviously) +2. start `bin\installOnWindows.bat` + +Now, run `start.bat` and open in your browser. + +Update to the latest version with `git pull origin`, then run `bin\installOnWindows.bat`, again. + +[Next steps](#next-steps). ## Linux +You'll need gzip, git, curl, libssl develop libraries, python and gcc. +*For Debian/Ubuntu*: `apt-get install gzip git-core curl python libssl-dev pkg-config build-essential` +*For Fedora/CentOS*: `yum install gzip git-core curl python openssl-devel && yum groupinstall "Development Tools"` -**As root:** - -
    -
  1. Install the dependencies. We need gzip, git, curl, libssl develop libraries, python and gcc.
    For Debian/Ubuntu apt-get install gzip git-core curl python libssl-dev pkg-config build-essential
    - For Fedora/CentOS yum install gzip git-core curl python openssl-devel && yum groupinstall "Development Tools" -

    2. -
  2. Install node.js -
      -
    1. Download the latest node.js release (both 0.6 and 0.8 are supported, recommended is stable 0.8.8) from http://nodejs.org
      2. -
    2. Extract it with tar xf node-v0.8.8
      3. -
    3. Move into the node folder cd node-v0.8.8 and build node with ./configure && make && make install
      4. -
    -
    3. -
+Additionally, you'll need [node.js](http://nodejs.org). **As any user (we recommend creating a separate user called etherpad-lite):** -
    -
  1. Move to a folder where you want to install Etherpad Lite. Clone the git repository git clone 'git://github.com/Pita/etherpad-lite.git'
    2. -
  2. Change into the directory containing the Etherpad Lite source code clone with cd etherpad-lite
    3. -
  3. Start it with bin/run.sh
     
    4. -
  4. Open your web browser and visit http://localhost:9001. You like it? Look at the 'Next Steps' section below
    5. -
+1. Move to a folder where you want to install Etherpad Lite. Clone the git repository `git clone git://github.com/Pita/etherpad-lite.git` +2. Change into the new directory containing the cloned source code `cd etherpad-lite` -## Next Steps -You can modify the settings in the file `settings.json` +Now, run `bin\run.sh` and open in your browser. -If you have multiple settings files, you may pass one to `bin/run.sh` using the `-s|--settings` option. This allows you to run multiple Etherpad Lite instances from the same installation. +Update to the latest version with `git pull origin`. The next start with bin/run.sh will update the dependencies. -You should use a dedicated database such as "mysql" if you are planning on using etherpad-lite in a production environment, the "dirty" database driver is only for testing and/or development purposes. +You like it? [Next steps](#next-steps). -You can update to the latest version with `git pull origin`. The next start with bin/run.sh will update the dependencies. You probably need to do a `npm cache clean jshint` before, in case that throws an error message. +# Next Steps +## Tweak the settings +You can modify the settings in `settings.json`. (If you need to handle multiple settings files, you can pass the path to a settings file to `bin/run.sh` using the `-s|--settings` option. This allows you to run multiple Etherpad Lite instances from the same installation.) -Look at this wiki pages: +You should use a dedicated database such as "mysql", if you are planning on using etherpad-lite in a production environment, since the "dirtyDB" database driver is only for testing and/or development purposes. -* [How to deploy Etherpad Lite as a service](https://github.com/Pita/etherpad-lite/wiki/How-to-deploy-Etherpad-Lite-as-a-service) -* [How to put Etherpad Lite behind a reverse Proxy](https://github.com/Pita/etherpad-lite/wiki/How-to-put-Etherpad-Lite-behind-a-reverse-Proxy) -* [How to customize your Etherpad Lite installation](https://github.com/Pita/etherpad-lite/wiki/How-to-customize-your-Etherpad-Lite-installation) -* [How to use Etherpad-Lite with jQuery](https://github.com/Pita/etherpad-lite/wiki/How-to-use-Etherpad-Lite-with-jQuery) -* [How to use Etherpad Lite with MySQL](https://github.com/Pita/etherpad-lite/wiki/How-to-use-Etherpad-Lite-with-MySQL) -* [Sites that run Etherpad Lite](https://github.com/Pita/etherpad-lite/wiki/Sites-that-run-Etherpad-Lite) -* [How to migrate the database from Etherpad to Etherpad Lite](https://github.com/Pita/etherpad-lite/wiki/How-to-migrate-the-database-from-Etherpad-to-Etherpad-Lite) +## Helpful resources +The [wiki](https://github.com/Pita/etherpad-lite/wiki) is your one-stop resource for Tutorials and How-to's, really check it out! Also, feel free to improve these wiki pages. -You can find more information in the [wiki](https://github.com/Pita/etherpad-lite/wiki). Feel free to improve these wiki pages +Documentation can be found in `docs/`. -# Develop -If you're new to git and github, start by watching [this video](http://youtu.be/67-Q26YH97E) then read this [git guide](http://learn.github.com/p/intro.html). +# Development -If you're new to node.js, start with this video . +## Things you should know +Read this [git guide](http://learn.github.com/p/intro.html) and watch this [video on getting started with Etherpad Lite Development](http://youtu.be/67-Q26YH97E). -You can debug with `bin/debugRun.sh` +If you're new to node.js, start with Ryan Dahl's [Introduction to Node.js](http://youtu.be/jo_B4LTHi3I). -If you want to find out how Etherpads Easysync works (the library that makes it really realtime), start with this [PDF](https://github.com/Pita/etherpad-lite/raw/master/doc/easysync/easysync-full-description.pdf) (complex, but worth reading). +You can debug Etherpad lite using `bin/debugRun.sh`. -You know all this and just want to know how you can help? Look at the [TODO list](https://github.com/Pita/etherpad-lite/wiki/TODO). -You can join the [mailinglist](http://groups.google.com/group/etherpad-lite-dev) or go to the freenode irc channel [#etherpad-lite-dev](http://webchat.freenode.net?channels=#etherpad-lite-dev) +If you want to find out how Etherpad's `Easysync` works (the library that makes it really realtime), start with this [PDF](https://github.com/Pita/etherpad-lite/raw/master/doc/easysync/easysync-full-description.pdf) (complex, but worth reading). -You also help the project, if you only host a Etherpad Lite instance and share your experience with us. +## Getting started +You know all this and just want to know how you can help? -Please consider using [jshint](http://www.jshint.com/about/) if you plan to -contribute to Etherpad Lite. +Look at the [TODO list](https://github.com/Pita/etherpad-lite/wiki/TODO) and our [Issue tracker](https://github.com/Pita/etherpad-lite/issues). (Please consider using [jshint](http://www.jshint.com/about/), if you plan to contribute code.) + +Also, and most importantly, read our [**Developer Guidelines**](https://github.com/Pita/etherpad-lite/wiki/Developer-Guidelines), really! + +# Get in touch +Join the [mailinglist](http://groups.google.com/group/etherpad-lite-dev) and make some noise on our freenode irc channel [#etherpad-lite-dev](http://webchat.freenode.net?channels=#etherpad-lite-dev)! # Modules created for this project @@ -123,9 +118,9 @@ contribute to Etherpad Lite. * [channels](https://github.com/Pita/channels) "Event channels in node.js" - ensures that ueberDB operations are atomic and in series for each key * [async-stacktrace](https://github.com/Pita/async-stacktrace) "Improves node.js stacktraces and makes it easier to handle errors" -# Donations -* [Etherpad Foundation Flattr] (http://flattr.com/thing/71378/Etherpad-Foundation) -* [Paypal] (http://etherpad.org) <-- Click the donate button +# Donate! +* [Flattr] (http://flattr.com/thing/71378/Etherpad-Foundation) +* Paypal - Press the donate button on [etherpad.org](http://etherpad.org) # License [Apache License v2](http://www.apache.org/licenses/LICENSE-2.0.html) \ No newline at end of file diff --git a/bin/buildForWindows.sh b/bin/buildForWindows.sh index 99f9bb08a..1d47bff1b 100755 --- a/bin/buildForWindows.sh +++ b/bin/buildForWindows.sh @@ -1,6 +1,6 @@ #!/bin/sh -NODE_VERSION="0.6.5" +NODE_VERSION="0.8.4" #Move to the folder where ep-lite is installed cd `dirname $0` @@ -50,7 +50,7 @@ mv node_modules_resolved node_modules echo "download windows node..." cd bin -wget "http://nodejs.org/dist/v$NODE_VERSION/node.exe" -O node.exe +wget "http://nodejs.org/dist/v$NODE_VERSION/node.exe" -O ../node.exe echo "create the zip..." cd /tmp diff --git a/bin/installOnWindows.bat b/bin/installOnWindows.bat index 159c517f9..b4e4f5400 100644 --- a/bin/installOnWindows.bat +++ b/bin/installOnWindows.bat @@ -1,22 +1,19 @@ @echo off -set NODE_VERSION=0.8.1 -set JQUERY_VERSION=1.7 :: change directory to etherpad-lite root -cd bin -cd .. +cd /D "%~dp0\.." + +:: Is node installed? +cmd /C node -e "" || ( echo "Please install node.js ( http://nodejs.org )" && exit /B 1 ) echo _ -echo Updating node... -curl -lo bin\node.exe http://nodejs.org/dist/v%NODE_VERSION%/node.exe +echo Checking node version... +set check_version="if(['6','8'].indexOf(process.version.split('.')[1].toString()) === -1) { console.log('You are running a wrong version of Node. Etherpad Lite requires v0.6.x or v0.8.x'); process.exit(1) }" +cmd /C node -e %check_version% || exit /B 1 echo _ echo Installing etherpad-lite and dependencies... -cmd /C npm install src/ - -echo _ -echo Updating jquery... -curl -lo "node_modules\ep_etherpad-lite\static\js\jquery.min.js" "http://code.jquery.com/jquery-%JQUERY_VERSION%.min.js" +cmd /C npm install src/ || exit /B 1 echo _ echo Copying custom templates... @@ -27,12 +24,16 @@ FOR %%f IN (index pad timeslider) DO ( ) echo _ -echo Clearing cache. +echo Clearing cache... del /S var\minified* echo _ echo Setting up settings.json... -IF NOT EXIST settings.json copy settings.json.template settings.json +IF NOT EXIST settings.json ( + echo Can't find settings.json. + echo Copying settings.json.template... + cmd /C copy settings.json.template settings.json || exit /B 1 +) echo _ -echo Installed Etherpad-lite! \ No newline at end of file +echo Installed Etherpad-lite! To run Etherpad type start.bat \ No newline at end of file diff --git a/doc/all.md b/doc/all.md new file mode 100644 index 000000000..c0cbf369f --- /dev/null +++ b/doc/all.md @@ -0,0 +1,3 @@ +@include documentation +@include api/api +@include database diff --git a/doc/api/api.md b/doc/api/api.md new file mode 100644 index 000000000..b96fa0c8e --- /dev/null +++ b/doc/api/api.md @@ -0,0 +1,7 @@ +@include embed_parameters +@include http_api +@include hooks +@include hooks_client-side +@include hooks_server-side +@include editorInfo +@include changeset_library \ No newline at end of file diff --git a/doc/api/changeset_library.md b/doc/api/changeset_library.md new file mode 100644 index 000000000..2dce55aa3 --- /dev/null +++ b/doc/api/changeset_library.md @@ -0,0 +1,151 @@ +# Changeset Library + +``` +"Z:z>1|2=m=b*0|1+1$\n" +``` + +This is a Changeset. Its just a string and its very difficult to read in this form. But the Changeset Library gives us some tools to read it. + +A changeset describes the diff between two revisions of the document. The Browser sends changesets to the server and the server sends them to the clients to update them. This Changesets gets also saved into the history of a pad. Which allows us to go back to every revision from the past. + +## Changeset.unpack(changeset) + + * `changeset` {String} + +This functions returns an object representaion of the changeset, similar to this: + +``` +{ oldLen: 35, newLen: 36, ops: '|2=m=b*0|1+1', charBank: '\n' } +``` + + * `oldLen` {Number} the original length of the document. + * `newLen` {Number} the length of the document after the changeset is applied. + * `ops` {String} the actual changes, introduced by this changeset. + * `charBank` {String} All characters that are added by this changeset. + +## Changeset.opIterator(ops) + + * `ops` {String} The operators, returned by `Changeset.unpack()` + +Returns an operator iterator. This iterator allows us to iterate over all operators that are in the changeset. + +You can iterate with an opIterator using its `next()` and `hasNext()` methods. Next returns the `next()` operator object and `hasNext()` indicates, whether there are any operators left. + +## The Operator object +There are 3 types of operators: `+`,`-` and `=`. These operators describe different changes to the document, beginning with the first character of the document. A `=` operator doesn't change the text, but it may add or remove text attributes. A `-` operator removes text. And a `+` Operator adds text and optionally adds some attributes to it. + + * `opcode` {String} the operator type + * `chars` {Number} the length of the text changed by this operator. + * `lines` {Number} the number of lines changed by this operator. + * `attribs` {attribs} attributes set on this text. + +### Example +``` +{ opcode: '+', + chars: 1, + lines: 1, + attribs: '*0' } +``` + +## APool + +``` +> var AttributePoolFactory = require("./utils/AttributePoolFactory"); +> var apool = AttributePoolFactory.createAttributePool(); +> console.log(apool) +{ numToAttrib: {}, + attribToNum: {}, + nextNum: 0, + putAttrib: [Function], + getAttrib: [Function], + getAttribKey: [Function], + getAttribValue: [Function], + eachAttrib: [Function], + toJsonable: [Function], + fromJsonable: [Function] } +``` + +This creates an empty apool. A apool saves which attributes were used during the history of a pad. There is one apool for each pad. It only saves the attributes that were really used, it doesn't save unused attributes. Lets fill this apool with some values + +``` +> apool.fromJsonable({"numToAttrib":{"0":["author","a.kVnWeomPADAT2pn9"],"1":["bold","true"],"2":["italic","true"]},"nextNum":3}); +> console.log(apool) +{ numToAttrib: + { '0': [ 'author', 'a.kVnWeomPADAT2pn9' ], + '1': [ 'bold', 'true' ], + '2': [ 'italic', 'true' ] }, + attribToNum: + { 'author,a.kVnWeomPADAT2pn9': 0, + 'bold,true': 1, + 'italic,true': 2 }, + nextNum: 3, + putAttrib: [Function], + getAttrib: [Function], + getAttribKey: [Function], + getAttribValue: [Function], + eachAttrib: [Function], + toJsonable: [Function], + fromJsonable: [Function] } +``` + +We used the fromJsonable function to fill the empty apool with values. the fromJsonable and toJsonable functions are used to serialize and deserialize an apool. You can see that it stores the relation between numbers and attributes. So for example the attribute 1 is the attribute bold and vise versa. A attribute is always a key value pair. For stuff like bold and italic its just 'italic':'true'. For authors its author:$AUTHORID. So a character can be bold and italic. But it can't belong to multiple authors + +``` +> apool.getAttrib(1) +[ 'bold', 'true' ] +``` + +Simple example of how to get the key value pair for the attribute 1 + +## AText + +``` +> var atext = {"text":"bold text\nitalic text\nnormal text\n\n","attribs":"*0*1+9*0|1+1*0*1*2+b|1+1*0+b|2+2"}; +> console.log(atext) +{ text: 'bold text\nitalic text\nnormal text\n\n', + attribs: '*0*1+9*0|1+1*0*1*2+b|1+1*0+b|2+2' } +``` + +This is an atext. An atext has two parts: text and attribs. The text is just the text of the pad as a string. We will look closer at the attribs at the next steps + +``` +> var opiterator = Changeset.opIterator(atext.attribs) +> console.log(opiterator) +{ next: [Function: next], + hasNext: [Function: hasNext], + lastIndex: [Function: lastIndex] } +> opiterator.next() +{ opcode: '+', + chars: 9, + lines: 0, + attribs: '*0*1' } +> opiterator.next() +{ opcode: '+', + chars: 1, + lines: 1, + attribs: '*0' } +> opiterator.next() +{ opcode: '+', + chars: 11, + lines: 0, + attribs: '*0*1*2' } +> opiterator.next() +{ opcode: '+', + chars: 1, + lines: 1, + attribs: '' } +> opiterator.next() +{ opcode: '+', + chars: 11, + lines: 0, + attribs: '*0' } +> opiterator.next() +{ opcode: '+', + chars: 2, + lines: 2, + attribs: '' } +``` + +The attribs are again a bunch of operators like .ops in the changeset was. But these operators are only + operators. They describe which part of the text has which attributes + +For more information see /doc/easysync/easysync-notes.txt in the source. diff --git a/doc/api/editorInfo.md b/doc/api/editorInfo.md new file mode 100644 index 000000000..e4322e9e1 --- /dev/null +++ b/doc/api/editorInfo.md @@ -0,0 +1,47 @@ +# editorInfo + +## editorInfo.ace_replaceRange(start, end, text) +This function replaces a range (from `start` to `end`) with `text`. + +## editorInfo.ace_getRep() +Returns the `rep` object. + +## editorInfo.ace_getAuthor() +## editorInfo.ace_inCallStack() +## editorInfo.ace_inCallStackIfNecessary(?) +## editorInfo.ace_focus(?) +## editorInfo.ace_importText(?) +## editorInfo.ace_importAText(?) +## editorInfo.ace_exportText(?) +## editorInfo.ace_editorChangedSize(?) +## editorInfo.ace_setOnKeyPress(?) +## editorInfo.ace_setOnKeyDown(?) +## editorInfo.ace_setNotifyDirty(?) +## editorInfo.ace_dispose(?) +## editorInfo.ace_getFormattedCode(?) +## editorInfo.ace_setEditable(bool) +## editorInfo.ace_execCommand(?) +## editorInfo.ace_callWithAce(fn, callStack, normalize) +## editorInfo.ace_setProperty(key, value) +## editorInfo.ace_setBaseText(txt) +## editorInfo.ace_setBaseAttributedText(atxt, apoolJsonObj) +## editorInfo.ace_applyChangesToBase(c, optAuthor, apoolJsonObj) +## editorInfo.ace_prepareUserChangeset() +## editorInfo.ace_applyPreparedChangesetToBase() +## editorInfo.ace_setUserChangeNotificationCallback(f) +## editorInfo.ace_setAuthorInfo(author, info) +## editorInfo.ace_setAuthorSelectionRange(author, start, end) +## editorInfo.ace_getUnhandledErrors() +## editorInfo.ace_getDebugProperty(prop) +## editorInfo.ace_fastIncorp(?) +## editorInfo.ace_isCaret(?) +## editorInfo.ace_getLineAndCharForPoint(?) +## editorInfo.ace_performDocumentApplyAttributesToCharRange(?) +## editorInfo.ace_setAttributeOnSelection(?) +## editorInfo.ace_toggleAttributeOnSelection(?) +## editorInfo.ace_performSelectionChange(?) +## editorInfo.ace_doIndentOutdent(?) +## editorInfo.ace_doUndoRedo(?) +## editorInfo.ace_doInsertUnorderedList(?) +## editorInfo.ace_doInsertOrderedList(?) +## editorInfo.ace_performDocumentApplyAttributesToRange() diff --git a/doc/api/embed_parameters.md b/doc/api/embed_parameters.md new file mode 100644 index 000000000..587305665 --- /dev/null +++ b/doc/api/embed_parameters.md @@ -0,0 +1,47 @@ +# Embed parameters +You can easily embed your etherpad-lite into any webpage by using iframes. You can configure the embedded pad using embed paramters. + +Example: + +Cut and paste the following code into any webpage to embed a pad. The parameters below will hide the chat and the line numbers. + +``` + +``` + +## showLineNumbers + * Boolean + +Default: true + +## showControls + * Boolean + +Default: true + +## showChat + * Boolean + +Default: true + +## useMonospaceFont + * Boolean + +Default: false + +## userName + * String + +Default: "unnamed" + +Example: `userName=Etherpad%20User` + +## noColors + * Boolean + +Default: false + +## alwaysShowChat + * Boolean + +Default: false diff --git a/doc/api/hooks.md b/doc/api/hooks.md new file mode 100644 index 000000000..c252aa840 --- /dev/null +++ b/doc/api/hooks.md @@ -0,0 +1,11 @@ +# Hooks +All hooks are called with two arguments: + +1. name - the name of the hook being called +2. context - an object with some relevant information about the context of the call + +## Return values +A hook should always return a list or undefined. Returning undefined is equivalent to returning an empty list. +All the returned lists are appended to each other, so if the return values where `[1, 2]`, `undefined`, `[3, 4,]`, `undefined` and `[5]`, the value returned by callHook would be `[1, 2, 3, 4, 5]`. + +This is, because it should never matter if you have one plugin or several plugins doing some work - a single plugin should be able to make callHook return the same value a set of plugins are able to return collectively. So, any plugin can return a list of values, of any length, not just one value. \ No newline at end of file diff --git a/doc/api/hooks_client-side.md b/doc/api/hooks_client-side.md new file mode 100644 index 000000000..f706f6a12 --- /dev/null +++ b/doc/api/hooks_client-side.md @@ -0,0 +1,176 @@ +# Client-side hooks +Most of these hooks are called during or in order to set up the formatting process. + +## documentReady +Called from: src/templates/pad.html + +Things in context: + +nothing + +This hook proxies the functionality of jQuery's `$(document).ready` event. + +## aceDomLineProcessLineAttributes +Called from: src/static/js/domline.js + +Things in context: + +1. domline - The current DOM line being processed +2. cls - The class of the current block element (useful for styling) + +This hook is called for elements in the DOM that have the "lineMarkerAttribute" set. You can add elements into this category with the aceRegisterBlockElements hook above. + +The return value of this hook should have the following structure: + +`{ preHtml: String, postHtml: String, processedMarker: Boolean }` + +The preHtml and postHtml values will be added to the HTML display of the element, and if processedMarker is true, the engine won't try to process it any more. + +## aceCreateDomLine +Called from: src/static/js/domline.js + +Things in context: + +1. domline - the current DOM line being processed +2. cls - The class of the current element (useful for styling) + +This hook is called for any line being processed by the formatting engine, unless the aceDomLineProcessLineAttributes hook from above returned true, in which case this hook is skipped. + +The return value of this hook should have the following structure: + +`{ extraOpenTags: String, extraCloseTags: String, cls: String }` + +extraOpenTags and extraCloseTags will be added before and after the element in question, and cls will be the new class of the element going forward. + +## acePostWriteDomLineHTML +Called from: src/static/js/domline.js + +Things in context: + +1. node - the DOM node that just got written to the page + +This hook is for right after a node has been fully formatted and written to the page. + +## aceAttribsToClasses +Called from: src/static/js/linestylefilter.js + +Things in context: + +1. linestylefilter - the JavaScript object that's currently processing the ace attributes +2. key - the current attribute being processed +3. value - the value of the attribute being processed + +This hook is called during the attribute processing procedure, and should be used to translate key, value pairs into valid HTML classes that can be inserted into the DOM. + +The return value for this function should be a list of classes, which will then be parsed into a valid class string. + +## aceGetFilterStack +Called from: src/static/js/linestylefilter.js + +Things in context: + +1. linestylefilter - the JavaScript object that's currently processing the ace attributes +2. browser - an object indicating which browser is accessing the page + +This hook is called to apply custom regular expression filters to a set of styles. The one example available is the ep_linkify plugin, which adds internal links. They use it to find the telltale `[[ ]]` syntax that signifies internal links, and finding that syntax, they add in the internalHref attribute to be later used by the aceCreateDomLine hook (documented above). + +## aceEditorCSS +Called from: src/static/js/ace.js + +Things in context: None + +This hook is provided to allow custom CSS files to be loaded. The return value should be an array of paths relative to the plugins directory. + +## aceInitInnerdocbodyHead +Called from: src/static/js/ace.js + +Things in context: + +1. iframeHTML - the HTML of the editor iframe up to this point, in array format + +This hook is called during the creation of the editor HTML. The array should have lines of HTML added to it, giving the plugin author a chance to add in meta, script, link, and other tags that go into the `` element of the editor HTML document. + +## aceEditEvent +Called from: src/static/js/ace2_inner.js + +Things in context: + +1. callstack - a bunch of information about the current action +2. editorInfo - information about the user who is making the change +3. rep - information about where the change is being made +4. documentAttributeManager - information about attributes in the document (this is a mystery to me) + +This hook is made available to edit the edit events that might occur when changes are made. Currently you can change the editor information, some of the meanings of the edit, and so on. You can also make internal changes (internal to your plugin) that use the information provided by the edit event. + +## aceRegisterBlockElements +Called from: src/static/js/ace2_inner.js + +Things in context: None + +The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements. + +## aceInitialized +Called from: src/static/js/ace2_inner.js + +Things in context: + +1. editorInfo - information about the user who will be making changes through the interface, and a way to insert functions into the main ace object (see ep_headings) +2. rep - information about where the user's cursor is +3. documentAttributeManager - some kind of magic + +This hook is for inserting further information into the ace engine, for later use in formatting hooks. + +## postAceInit +Called from: src/static/js/pad.js + +Things in context: + +1. ace - the ace object that is applied to this editor. + +There doesn't appear to be any example available of this particular hook being used, but it gets fired after the editor is all set up. + +## userJoinOrUpdate +Called from: src/static/js/pad_userlist.js + +Things in context: + +1. info - the user information + +This hook is called on the client side whenever a user joins or changes. This can be used to create notifications or an alternate user list. + +## collectContentPre +Called from: src/static/js/contentcollector.js + +Things in context: + +1. cc - the contentcollector object +2. state - the current state of the change being made +3. tname - the tag name of this node currently being processed +4. style - the style applied to the node (probably CSS) +5. cls - the HTML class string of the node + +This hook is called before the content of a node is collected by the usual methods. The cc object can be used to do a bunch of things that modify the content of the pad. See, for example, the heading1 plugin for etherpad original. + +## collectContentPost +Called from: src/static/js/contentcollector.js + +Things in context: + +1. cc - the contentcollector object +2. state - the current state of the change being made +3. tname - the tag name of this node currently being processed +4. style - the style applied to the node (probably CSS) +5. cls - the HTML class string of the node + +This hook is called after the content of a node is collected by the usual methods. The cc object can be used to do a bunch of things that modify the content of the pad. See, for example, the heading1 plugin for etherpad original. + +## handleClientMessage_`name` +Called from: `src/static/js/collab_client.js` + +Things in context: + +1. payload - the data that got sent with the message (use it for custom message content) + +This hook gets called every time the client receives a message of type `name`. This can most notably be used with the new HTTP API call, "sendClientsMessage", which sends a custom message type to all clients connected to a pad. You can also use this to handle existing types. + +`collab_client.js` has a pretty extensive list of message types, if you want to take a look. diff --git a/doc/api/hooks_server-side.md b/doc/api/hooks_server-side.md new file mode 100644 index 000000000..06ec7374b --- /dev/null +++ b/doc/api/hooks_server-side.md @@ -0,0 +1,138 @@ +# Server-side hooks +These hooks are called on server-side. + +## loadSettings +Called from: src/node/server.js + +Things in context: + +1. settings - the settings object + +Use this hook to receive the global settings in your plugin. + +## pluginUninstall +Called from: src/static/js/pluginfw/installer.js + +Things in context: + +1. plugin_name - self-explanatory + +If this hook returns an error, the callback to the uninstall function gets an error as well. This mostly seems useful for handling additional features added in based on the installation of other plugins, which is pretty cool! + +## pluginInstall +Called from: src/static/js/pluginfw/installer.js + +Things in context: + +1. plugin_name - self-explanatory + +If this hook returns an error, the callback to the install function gets an error, too. This seems useful for adding in features when a particular plugin is installed. + +## init_`` +Called from: src/static/js/pluginfw/plugins.js + +Things in context: None + +This function is called after a specific plugin is initialized. This would probably be more useful than the previous two functions if you only wanted to add in features to one specific plugin. + +## expressConfigure +Called from: src/node/server.js + +Things in context: + +1. app - the main application object + +This is a helpful hook for changing the behavior and configuration of the application. It's called right after the application gets configured. + +## expressCreateServer +Called from: src/node/server.js + +Things in context: + +1. app - the main application object (helpful for adding new paths and such) + +This hook gets called after the application object has been created, but before it starts listening. This is similar to the expressConfigure hook, but it's not guaranteed that the application object will have all relevant configuration variables. + +## eejsBlock_`` +Called from: src/node/eejs/index.js + +Things in context: + +1. content - the content of the block + +This hook gets called upon the rendering of an ejs template block. For any specific kind of block, you can change how that block gets rendered by modifying the content object passed in. + +Have a look at `src/templates/pad.html` and `src/templates/timeslider.html` to see which blocks are available. + +## socketio +Called from: src/node/hooks/express/socketio.js + +Things in context: + +1. app - the application object +2. io - the socketio object + +I have no idea what this is useful for, someone else will have to add this description. + +## authorize +Called from: src/node/hooks/express/webaccess.js + +Things in context: + +1. req - the request object +2. res - the response object +3. next - ? +4. resource - the path being accessed + +This is useful for modifying the way authentication is done, especially for specific paths. + +## authenticate +Called from: src/node/hooks/express/webaccess.js + +Things in context: + +1. req - the request object +2. res - the response object +3. next - ? +4. username - the username used (optional) +5. password - the password used (optional) + +This is useful for modifying the way authentication is done. + +## authFailure +Called from: src/node/hooks/express/webaccess.js + +Things in context: + +1. req - the request object +2. res - the response object +3. next - ? + +This is useful for modifying the way authentication is done. + +## handleMessage +Called from: src/node/handler/PadMessageHandler.js + +Things in context: + +1. message - the message being handled +2. client - the client object from socket.io + +This hook will be called once a message arrive. If a plugin calls `callback(null)` the message will be dropped. However it is not possible to modify the message. + +Plugins may also decide to implement custom behavior once a message arrives. + +**WARNING**: handleMessage will be called, even if the client is not authorized to send this message. It's up to the plugin to check permissions. + +Example: + +``` +function handleMessage ( hook, context, callback ) { + if ( context.message.type == 'USERINFO_UPDATE' ) { + // If the message type is USERINFO_UPDATE, drop the message + callback(null); + }else{ + callback(); + } +}; +``` diff --git a/doc/api/http_api.md b/doc/api/http_api.md new file mode 100644 index 000000000..3afab498f --- /dev/null +++ b/doc/api/http_api.md @@ -0,0 +1,254 @@ +# HTTP API + +## What can I do with this API? +The API gives another web application control of the pads. The basic functions are + +* create/delete pads +* grant/forbid access to pads +* get/set pad content + +The API is designed in a way, so you can reuse your existing user system with their permissions, and map it to etherpad lite. Means: Your web application still has to do authentication, but you can tell etherpad lite via the api, which visitors should get which permissions. This allows etherpad lite to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website. + +Take a look at [HTTP API client libraries](https://github.com/Pita/etherpad-lite/wiki/HTTP-API-client-libraries) to see if a library in your favorite language. + +## Examples + +### Example 1 + +A portal (such as WordPress) wants to give a user access to a new pad. Let's assume the user have the internal id 7 and his name is michael. + +Portal maps the internal userid to an etherpad author. + +> Request: `http://pad.domain/api/1/createAuthorIfNotExistsFor?apikey=secret&name=Michael&authorMapper=7` +> +> Response: `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}` + +Portal maps the internal userid to an etherpad group: + +> Request: `http://pad.domain/api/1/createGroupIfNotExistsFor?apikey=secret&groupMapper=7` +> +> Response: `{code: 0, message:"ok", data: {groupID: "g.s8oes9dhwrvt0zif"}}` + +Portal creates a pad in the userGroup + +> Request: `http://pad.domain/api/1/createGroupPad?apikey=secret&groupID=g.s8oes9dhwrvt0zif&padName=samplePad&text=This is the first sentence in the pad` +> +> Response: `{code: 0, message:"ok", data: null}` + +Portal starts the session for the user on the group: + +> Request: `http://pad.domain/api/1/createSession?apikey=secret&groupID=g.s8oes9dhwrvt0zif&authorID=a.s8oes9dhwrvt0zif&validUntil=1312201246` +> +> Response: `{"data":{"sessionID": "s.s8oes9dhwrvt0zif"}}` + +Portal places the cookie "sessionID" with the given value on the client and creates an iframe including the pad. + +### Example 2 + +A portal (such as WordPress) wants to transform the contents of a pad that multiple admins edited into a blog post. + +Portal retrieves the contents of the pad for entry into the db as a blog post: + +> Request: `http://pad.domain/api/1/getText?apikey=secret&padID=g.s8oes9dhwrvt0zif$123` +> +> Response: `{code: 0, message:"ok", data: {text:"Welcome Text"}}` + +Portal submits content into new blog post + +> Portal.AddNewBlog(content) +> + +## Usage + +### Request Format + +The API is accessible via HTTP. HTTP Requests are in the format /api/$APIVERSION/$FUNCTIONNAME. Parameters are transmitted via HTTP GET. $APIVERSION is 1 + +### Response Format +Responses are valid JSON in the following format: + +```js +{ + "code": number, + "message": string, + "data": obj +} +``` + +* **code** a return code + * **0** everything ok + * **1** wrong parameters + * **2** internal error + * **3** no such function + * **4** no or wrong API Key +* **message** a status message. Its ok if everything is fine, else it contains an error message +* **data** the payload + +### Overview + +![API Overview](http://i.imgur.com/d0nWp.png) + +## Data Types + +* **groupID** a string, the unique id of a group. Format is g.16RANDOMCHARS, for example g.s8oes9dhwrvt0zif +* **sessionID** a string, the unique id of a session. Format is s.16RANDOMCHARS, for example s.s8oes9dhwrvt0zif +* **authorID** a string, the unique id of an author. Format is a.16RANDOMCHARS, for example a.s8oes9dhwrvt0zif +* **readOnlyID** a string, the unique id of an readonly relation to a pad. Format is r.16RANDOMCHARS, for example r.s8oes9dhwrvt0zif +* **padID** a string, format is GROUPID$PADNAME, for example the pad test of group g.s8oes9dhwrvt0zif has padID g.s8oes9dhwrvt0zif$test + +### Authentication + +Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad-Lite deployment. This token will be random string, generated by Etherpad-Lite at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad Lite. Only Etherpad Lite and the requesting application knows this key. Token management will not be exposed through this API. + +### Node Interoperability + +All functions will also be available through a node module accessable from other node.js applications. + +### JSONP + +The API provides _JSONP_ support to allow requests from a server in a different domain. +Simply add `&jsonp=?` to the API call. + +Example usage: http://api.jquery.com/jQuery.getJSON/ + +## API Methods + +### Groups +Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test + +* **createGroup()** creates a new group

*Example returns:* + * `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}` + +* **createGroupIfNotExistsFor(groupMapper)** this functions helps you to map your application group ids to etherpad lite group ids

*Example returns:* + * `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}` + +* **deleteGroup(groupID)** deletes a group

*Example returns:* + * `{code: 0, message:"ok", data: null}` + * `{code: 1, message:"groupID does not exist", data: null}` + +* **listPads(groupID)** returns all pads of this group

*Example returns:* + * `{code: 0, message:"ok", data: {padIDs : ["g.s8oes9dhwrvt0zif$test", "g.s8oes9dhwrvt0zif$test2"]}` + * `{code: 1, message:"groupID does not exist", data: null}` + +* **createGroupPad(groupID, padName [, text])** creates a new pad in this group

*Example returns:* + * `{code: 0, message:"ok", data: null}` + * `{code: 1, message:"pad does already exist", data: null}` + * `{code: 1, message:"groupID does not exist", data: null}` + +* **listAllGroups()** lists all existing groups

*Example returns:* + * `{code: 0, message:"ok", data: {groupIDs: ["g.mKjkmnAbSMtCt8eL", "g.3ADWx6sbGuAiUmCy"]}}` + * `{code: 0, message:"ok", data: {groupIDs: []}}` + +### Author +These authors are bound to the attributes the users choose (color and name). + +* **createAuthor([name])** creates a new author

*Example returns:* + * `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}` + +* **createAuthorIfNotExistsFor(authorMapper [, name])** this functions helps you to map your application author ids to etherpad lite author ids

*Example returns:* + * `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}` + +* **listPadsOfAuthor(authorID)** returns an array of all pads this author contributed to

*Example returns:* + * `{code: 0, message:"ok", data: {padIDs: ["g.s8oes9dhwrvt0zif$test", "g.s8oejklhwrvt0zif$foo"]}}` + * `{code: 1, message:"authorID does not exist", data: null}` + +* **getAuthorName(authorID)** Returns the Author Name of the author

*Example returns:* + * `{code: 0, message:"ok", data: {authorName: "John McLear"}}` + +-> can't be deleted cause this would involve scanning all the pads where this author was + +### 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. + +* **createSession(groupID, authorID, validUntil)** creates a new session. validUntil is an unix timestamp in seconds

*Example returns:* + * `{code: 0, message:"ok", data: {sessionID: "s.s8oes9dhwrvt0zif"}}` + * `{code: 1, message:"groupID doesn't exist", data: null}` + * `{code: 1, message:"authorID doesn't exist", data: null}` + * `{code: 1, message:"validUntil is in the past", data: null}` + +* **deleteSession(sessionID)** deletes a session

*Example returns:* + * `{code: 1, message:"ok", data: null}` + * `{code: 1, message:"sessionID does not exist", data: null}` + +* **getSessionInfo(sessionID)** returns informations about a session

*Example returns:* + * `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif", groupID: g.s8oes9dhwrvt0zif, validUntil: 1312201246}}` + * `{code: 1, message:"sessionID does not exist", data: null}` + +* **listSessionsOfGroup(groupID)** returns all sessions of a group

*Example returns:* + * `{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}` + * `{code: 1, message:"groupID does not exist", data: null}` + +* **listSessionsOfAuthor(authorID)** returns all sessions of an author

*Example returns:* + * `{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}` + * `{code: 1, message:"authorID does not exist", data: null}` + +### Pad Content + +Pad content can be updated and retrieved through the API + +* **getText(padID, [rev])** returns the text of a pad

*Example returns:* + * `{code: 0, message:"ok", data: {text:"Welcome Text"}}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **setText(padID, text)** sets the text of a pad

*Example returns:* + * `{code: 0, message:"ok", data: null}` + * `{code: 1, message:"padID does not exist", data: null}` + * `{code: 1, message:"text too long", data: null}` + +* **getHTML(padID, [rev])** returns the text of a pad formatted as HTML

*Example returns:* + * `{code: 0, message:"ok", data: {html:"Welcome Text
More Text"}}` + * `{code: 1, message:"padID does not exist", data: null}` + +### 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. + +* **createPad(padID [, text])** creates a new (non-group) pad. Note that if you need to create a group Pad, you should call **createGroupPad**.

*Example returns:* + * `{code: 0, message:"ok", data: null}` + * `{code: 1, message:"pad does already exist", data: null}` + +* **getRevisionsCount(padID)** returns the number of revisions of this pad

*Example returns:* + * `{code: 0, message:"ok", data: {revisions: 56}}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **padUsersCount(padID)** returns the number of user that are currently editing this pad

*Example returns:* + * `{code: 0, message:"ok", data: {padUsersCount: 5}}` + +* **padUsers(padID)** returns the list of users that are currently editing this pad

*Example returns:* + * `{code: 0, message:"ok", data: {padUsers: [{colorId:"#c1a9d9","name":"username1","timestamp":1345228793126},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042}]}}` + * `{code: 0, message:"ok", data: {padUsers: []}}` + +* **deletePad(padID)** deletes a pad

*Example returns:* + * `{code: 0, message:"ok", data: null}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **getReadOnlyID(padID)** returns the read only link of a pad

*Example returns:* + * `{code: 0, message:"ok", data: {readOnlyID: "r.s8oes9dhwrvt0zif"}}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **setPublicStatus(padID, publicStatus)** sets a boolean for the public status of a pad

*Example returns:* + * `{code: 0, message:"ok", data: null}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **getPublicStatus(padID)** return true of false

*Example returns:* + * `{code: 0, message:"ok", data: {publicStatus: true}}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **setPassword(padID, password)** returns ok or a error message

*Example returns:* + * `{code: 0, message:"ok", data: null}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **isPasswordProtected(padID)** returns true or false

*Example returns:* + * `{code: 0, message:"ok", data: {passwordProtection: true}}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **listAuthorsOfPad(padID)** returns an array of authors who contributed to this pad

*Example returns:* + * `{code: 0, message:"ok", data: {authorIDs : ["a.s8oes9dhwrvt0zif", "a.akf8finncvomlqva"]}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **getLastEdited(padID)** returns the timestamp of the last revision of the pad

*Example returns:* + * `{code: 0, message:"ok", data: {lastEdited: 1340815946602}}` + * `{code: 1, message:"padID does not exist", data: null}` + +* **sendClientsMessage(padID, msg)** sends a custom message of type `msg` to the pad

*Example returns:* + * `{code: 0, message:"ok", data: {}}` + * `{code: 1, message:"padID does not exist", data: null}` diff --git a/doc/database.md b/doc/database.md index 372691747..de3e9f547 100644 --- a/doc/database.md +++ b/doc/database.md @@ -1,5 +1,10 @@ # Database structure +## Keys and their values + +### groups +A list of all existing groups (a JSON object with groupIDs as keys and `1` as values). + ### pad:$PADID Saves all informations about pads diff --git a/doc/documentation.md b/doc/documentation.md new file mode 100644 index 000000000..0542c4360 --- /dev/null +++ b/doc/documentation.md @@ -0,0 +1,15 @@ +# About this Documentation + + + +The goal of this documentation is to comprehensively explain Etherpad-Lite, +both from a reference as well as a conceptual point of view. + +Where appropriate, property types, method arguments, and the arguments +provided to event handlers are detailed in a list underneath the topic +heading. + +Every `.html` file is generated based on the corresponding +`.markdown` file in the `doc/api/` folder in the source tree. The +documentation is generated using the `tools/doc/generate.js` program. +The HTML template is located at `doc/template.html`. \ No newline at end of file diff --git a/doc/template.html b/doc/template.html new file mode 100644 index 000000000..2eb939872 --- /dev/null +++ b/doc/template.html @@ -0,0 +1,23 @@ + + + + + __SECTION__ Etherpad-Lite Manual & Documentation + + + + + +
+

Table of Contents

+ __TOC__ +
+ +
+ __CONTENT__ +
+ + + diff --git a/src/node/db/API.js b/src/node/db/API.js index 4a1371ba5..4979e8c65 100644 --- a/src/node/db/API.js +++ b/src/node/db/API.js @@ -35,6 +35,7 @@ var cleanText = require("./Pad").cleanText; /**GROUP FUNCTIONS*****/ /**********************/ +exports.listAllGroups = groupManager.listAllGroups; exports.createGroup = groupManager.createGroup; exports.createGroupIfNotExistsFor = groupManager.createGroupIfNotExistsFor; exports.deleteGroup = groupManager.deleteGroup; @@ -47,7 +48,9 @@ exports.createGroupPad = groupManager.createGroupPad; exports.createAuthor = authorManager.createAuthor; exports.createAuthorIfNotExistsFor = authorManager.createAuthorIfNotExistsFor; +exports.getAuthorName = authorManager.getAuthorName; exports.listPadsOfAuthor = authorManager.listPadsOfAuthor; +exports.padUsers = padMessageHandler.padUsers; exports.padUsersCount = padMessageHandler.padUsersCount; /**********************/ @@ -512,6 +515,39 @@ exports.listAuthorsOfPad = function(padID, callback) }); } +/** +sendClientsMessage(padID, msg) sends a message to all clients connected to the +pad, possibly for the purpose of signalling a plugin. + +Note, this will only accept strings from the HTTP API, so sending bogus changes +or chat messages will probably not be possible. + +The resulting message will be structured like so: + +{ + type: 'COLLABROOM', + data: { + type: , + time: