mirror of
https://github.com/ether/etherpad-lite.git
synced 2025-01-19 14:13:34 +01:00
Restructure headings.
This commit is contained in:
Marcel Klehr
parent
5fac05a395
commit
70fb765118
9 changed files with 97 additions and 69 deletions
3
doc/all.md
Normal file
3
doc/all.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
@include documentation.md
|
||||
@include api/api.md
|
||||
@include database.md
|
||||
7
doc/api/api.md
Normal file
7
doc/api/api.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# API
|
||||
@include embed_parameters.md
|
||||
@include http_api.md
|
||||
@include hooks_client-side.md
|
||||
@include hooks_server-side.md
|
||||
@include editorInfo.md
|
||||
@include changeset_library.md
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Changeset Library
|
||||
## Changeset Library
|
||||
|
||||
```
|
||||
"Z:z>1|2=m=b*0|1+1$\n"
|
||||
|
|
@ -8,7 +8,7 @@ This is a Changeset. Its just a string and its very difficult to read in this fo
|
|||
|
||||
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.unpack(changeset)
|
||||
|
||||
* `changeset` {String}
|
||||
|
||||
|
|
@ -23,7 +23,7 @@ This functions returns an object representaion of the changeset, similar to this
|
|||
* `ops` {String} the actual changes, introduced by this changeset.
|
||||
* `charBank` {String} All characters that are added by this changeset.
|
||||
|
||||
## Changeset.opIterator(ops)
|
||||
### Changeset.opIterator(ops)
|
||||
|
||||
* `ops` {String} The operators, returned by `Changeset.unpack()`
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ Returns an operator iterator. This iterator allows us to iterate over all operat
|
|||
|
||||
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
|
||||
### 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
|
||||
|
|
@ -39,7 +39,7 @@ There are 3 types of operators: `+`,`-` and `=`. These operators describe differ
|
|||
* `lines` {Number} the number of lines changed by this operator.
|
||||
* `attribs` {attribs} attributes set on this text.
|
||||
|
||||
### Example
|
||||
#### Example
|
||||
```
|
||||
{ opcode: '+',
|
||||
chars: 1,
|
||||
|
|
@ -47,7 +47,7 @@ There are 3 types of operators: `+`,`-` and `=`. These operators describe differ
|
|||
attribs: '*0' }
|
||||
```
|
||||
|
||||
## APool
|
||||
### APool
|
||||
<pre>
|
||||
> var AttributePoolFactory = require("./utils/AttributePoolFactory");
|
||||
> var apool = AttributePoolFactory.createAttributePool();
|
||||
|
|
@ -91,7 +91,7 @@ We used the fromJsonable function to fill the empty apool with values. the fromJ
|
|||
</pre>
|
||||
Simple example of how to get the key value pair for the attribute 1
|
||||
|
||||
## AText
|
||||
### AText
|
||||
<pre>
|
||||
> 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)
|
||||
|
|
|
|||
|
|
@ -1,7 +1,13 @@
|
|||
# Embed parameters
|
||||
## Embed parameters
|
||||
You can easily embed your etherpad-lite into any webpage by using iframes. You can configure the embedded pad using embed paramters.
|
||||
|
||||
## Parameters
|
||||
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.
|
||||
|
||||
```
|
||||
<iframe src='http://pad.test.de/p/PAD_NAME?showChat=false&showLineNumbers=false' width=600 height=400></iframe>
|
||||
```
|
||||
|
||||
### showLineNumbers
|
||||
* Boolean
|
||||
|
|
@ -39,11 +45,3 @@ Default: false
|
|||
* Boolean
|
||||
|
||||
Default: false
|
||||
|
||||
|
||||
## Example
|
||||
```
|
||||
<iframe src='http://pad.test.de/p/PAD_NAME?showChat=false&showLineNumbers=false' width=600 height=400></iframe>
|
||||
```
|
||||
|
||||
Cut and paste this into any webpage (between the body tags) to embed a pad. The above parameters will hide the chat and the line numbers.
|
||||
|
|
@ -1,7 +1,12 @@
|
|||
# Client-side hooks
|
||||
## Client-side hooks
|
||||
Most of these hooks are called during or in order to set up the formatting process.
|
||||
|
||||
## aceDomLineProcessLineAttributes
|
||||
All hooks registered to these events 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
|
||||
|
||||
### aceDomLineProcessLineAttributes
|
||||
Called from: src/static/js/domline.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -17,7 +22,7 @@ The return value of this hook should have the following structure:
|
|||
|
||||
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
|
||||
### aceCreateDomLine
|
||||
Called from: src/static/js/domline.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -33,7 +38,7 @@ The return value of this hook should have the following structure:
|
|||
|
||||
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
|
||||
### acePostWriteDomLineHTML
|
||||
Called from: src/static/js/domline.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -42,7 +47,7 @@ Things in context:
|
|||
|
||||
This hook is for right after a node has been fully formatted and written to the page.
|
||||
|
||||
## aceAttribsToClasses
|
||||
### aceAttribsToClasses
|
||||
Called from: src/static/js/linestylefilter.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -55,7 +60,7 @@ This hook is called during the attribute processing procedure, and should be use
|
|||
|
||||
The return value for this function should be a list of classes, which will then be parsed into a valid class string.
|
||||
|
||||
## aceGetFilterStack
|
||||
### aceGetFilterStack
|
||||
Called from: src/static/js/linestylefilter.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -65,14 +70,14 @@ Things in context:
|
|||
|
||||
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
|
||||
### 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
|
||||
### aceInitInnerdocbodyHead
|
||||
Called from: src/static/js/ace.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -81,7 +86,7 @@ Things in context:
|
|||
|
||||
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 `<head>` element of the editor HTML document.
|
||||
|
||||
## aceEditEvent
|
||||
### aceEditEvent
|
||||
Called from: src/static/js/ace2_inner.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -93,14 +98,14 @@ Things in context:
|
|||
|
||||
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
|
||||
### 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
|
||||
### aceInitialized
|
||||
Called from: src/static/js/ace2_inner.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -111,7 +116,7 @@ Things in context:
|
|||
|
||||
This hook is for inserting further information into the ace engine, for later use in formatting hooks.
|
||||
|
||||
## postAceInit
|
||||
### postAceInit
|
||||
Called from: src/static/js/pad.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -120,11 +125,7 @@ Things in context:
|
|||
|
||||
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.
|
||||
|
||||
# Other client hooks
|
||||
|
||||
These hooks are for other parts of the software on the client side, that is, when the editor is being used.
|
||||
|
||||
## userJoinOrUpdate
|
||||
### userJoinOrUpdate
|
||||
Called from: src/static/js/pad_userlist.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -133,7 +134,7 @@ Things in context:
|
|||
|
||||
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
|
||||
### collectContentPre
|
||||
Called from: src/static/js/contentcollector.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -146,7 +147,7 @@ Things in context:
|
|||
|
||||
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
|
||||
### collectContentPost
|
||||
Called from: src/static/js/contentcollector.js
|
||||
|
||||
Things in context:
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
## Server-side hooks
|
||||
These hooks are called on server-side.
|
||||
|
||||
All hooks registered to these events 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
|
||||
|
||||
# Server-side hooks
|
||||
These hooks are called on server-side.
|
||||
|
||||
## pluginUninstall
|
||||
### pluginUninstall
|
||||
Called from: src/static/js/pluginfw/installer.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -15,7 +15,7 @@ Things in context:
|
|||
|
||||
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
|
||||
### pluginInstall
|
||||
Called from: src/static/js/pluginfw/installer.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -24,14 +24,14 @@ Things in context:
|
|||
|
||||
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_`<plugin name>`
|
||||
### init_`<plugin name>`
|
||||
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
|
||||
### expressConfigure
|
||||
Called from: src/node/server.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -40,7 +40,7 @@ Things in context:
|
|||
|
||||
This is a helpful hook for changing the behavior and configuration of the application. It's called right after the application gets configured.
|
||||
|
||||
## expressCreateServer
|
||||
### expressCreateServer
|
||||
Called from: src/node/server.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -49,7 +49,7 @@ Things in context:
|
|||
|
||||
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_`<name>`
|
||||
### eejsBlock_`<name>`
|
||||
Called from: src/node/eejs/index.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -60,7 +60,7 @@ This hook gets called upon the rendering of an ejs template block. For any speci
|
|||
|
||||
Have a look at `src/templates/pad.html` and `src/templates/timeslider.html` to see which blocks are available.
|
||||
|
||||
## socketio
|
||||
### socketio
|
||||
Called from: src/node/hooks/express/socketio.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -70,7 +70,7 @@ Things in context:
|
|||
|
||||
I have no idea what this is useful for, someone else will have to add this description.
|
||||
|
||||
## authorize
|
||||
### authorize
|
||||
Called from: src/node/hooks/express/webaccess.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -82,7 +82,7 @@ Things in context:
|
|||
|
||||
This is useful for modifying the way authentication is done, especially for specific paths.
|
||||
|
||||
## authenticate
|
||||
### authenticate
|
||||
Called from: src/node/hooks/express/webaccess.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -95,7 +95,7 @@ Things in context:
|
|||
|
||||
This is useful for modifying the way authentication is done.
|
||||
|
||||
## authFailure
|
||||
### authFailure
|
||||
Called from: src/node/hooks/express/webaccess.js
|
||||
|
||||
Things in context:
|
||||
|
|
@ -106,7 +106,7 @@ Things in context:
|
|||
|
||||
This is useful for modifying the way authentication is done.
|
||||
|
||||
## handleMessage
|
||||
### handleMessage
|
||||
Called from: src/node/handler/PadMessageHandler.js
|
||||
|
||||
Things in context:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# HTTP API
|
||||
## HTTP API
|
||||
|
||||
## What can I do with this 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
|
||||
|
|
@ -11,9 +11,9 @@ The API is designed in a way, so you can reuse your existing user system with th
|
|||
|
||||
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
|
||||
### Examples
|
||||
|
||||
### Example 1
|
||||
#### 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.
|
||||
|
||||
|
|
@ -43,7 +43,7 @@ Portal starts the session for the user on the group:
|
|||
|
||||
Portal places the cookie "sessionID" with the given value on the client and creates an iframe including the pad.
|
||||
|
||||
### Example 2
|
||||
#### Example 2
|
||||
|
||||
A portal (such as WordPress) wants to transform the contents of a pad that multiple admins edited into a blog post.
|
||||
|
||||
|
|
@ -58,11 +58,13 @@ Portal submits content into new blog post
|
|||
> Portal.AddNewBlog(content)
|
||||
>
|
||||
|
||||
## Request Format
|
||||
### 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
|
||||
#### Response Format
|
||||
Responses are valid JSON in the following format:
|
||||
|
||||
```js
|
||||
|
|
@ -82,11 +84,11 @@ Responses are valid JSON in the following format:
|
|||
* **message** a status message. Its ok if everything is fine, else it contains an error message
|
||||
* **data** the payload
|
||||
|
||||
## Overview
|
||||
#### Overview
|
||||
|
||||
|
||||
|
||||
## Data Types
|
||||
#### 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
|
||||
|
|
@ -94,24 +96,24 @@ Responses are valid JSON in the following format:
|
|||
* **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
|
||||
|
||||
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
|
||||
#### Node Interoperability
|
||||
|
||||
All functions will also be available through a node module accessable from other node.js applications.
|
||||
|
||||
## JSONP
|
||||
#### 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 Functions
|
||||
### API Methods
|
||||
|
||||
## Groups
|
||||
#### 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 <br><br>*Example returns:*
|
||||
|
|
@ -133,7 +135,7 @@ Pads can belong to a group. The padID of grouppads is starting with a groupID li
|
|||
* `{code: 1, message:"pad does already exist", data: null}`
|
||||
* `{code: 1, message:"groupID does not exist", data: null}`
|
||||
|
||||
## Author
|
||||
#### Author
|
||||
Theses authors are bind to the attributes the users choose (color and name).
|
||||
|
||||
* **createAuthor([name])** creates a new author <br><br>*Example returns:*
|
||||
|
|
@ -148,7 +150,7 @@ Theses authors are bind to the attributes the users choose (color and name).
|
|||
|
||||
-> can't be deleted cause this would involve scanning all the pads where this author was
|
||||
|
||||
## Session
|
||||
#### 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. 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 <br><br>*Example returns:*
|
||||
|
|
@ -173,7 +175,7 @@ Sessions can be created between a group and an author. This allows an author to
|
|||
* `{"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
|
||||
|
||||
Pad content can be updated and retrieved through the API
|
||||
|
||||
|
|
@ -190,7 +192,7 @@ Pad content can be updated and retrieved through the API
|
|||
* `{code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}}`
|
||||
* `{code: 1, message:"padID does not exist", data: null}`
|
||||
|
||||
## Pad
|
||||
#### 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**.<br><br>*Example returns:*
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Database structure
|
||||
|
||||
## Keys and their values
|
||||
|
||||
### pad:$PADID
|
||||
Saves all informations about pads
|
||||
|
||||
|
|
|
|||
15
doc/documentation.md
Normal file
15
doc/documentation.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
# About this Documentation
|
||||
|
||||
<!-- type=misc -->
|
||||
|
||||
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`.
|
||||
Loading…
Reference in a new issue