mirrors/etherpad-lite
1
0
Fork 0
mirror of https://github.com/ether/etherpad-lite.git synced 2025-04-24 17:36:14 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 33

resolve merge conflict

Browse source
This commit is contained in:
John McLear 2013-12-09 21:55:04 +00:00
commit 58bbfd8a65
210 changed files with 12113 additions and 7505 deletions
Download patch file Download diff file Expand all files Collapse all files

7
doc/api/editorInfo.md
View file

@ -39,6 +39,13 @@ Returns the `rep` object.
## editorInfo.ace_performDocumentApplyAttributesToCharRange(?)
## editorInfo.ace_setAttributeOnSelection(?)
## editorInfo.ace_toggleAttributeOnSelection(?)
## editorInfo.ace_getAttributeOnSelection(attribute)
Returns a boolean if an attribute exists on a selected range.
The attribute should be the string name of the attribute applied to the selection IE subscript
Example usage: Apply the activeButton Class to a button if an attribute is on a highlighted/selected caret position or range.
Example: `call.editorInfo.ace_getAttributeOnSelection("subscript");` // call here is the callstack from aceEditEvent.
See the ep_subscript plugin for an example of this function in action.
Notes: Does not work on first or last character of a line. Suffers from a race condition if called with aceEditEvent.
## editorInfo.ace_performSelectionChange(?)
## editorInfo.ace_doIndentOutdent(?)
## editorInfo.ace_doUndoRedo(?)

6
doc/api/embed_parameters.md
View file

@ -60,3 +60,9 @@ Default: en
Example: `lang=ar` (translates the interface into Arabic)
## rtl
* Boolean
Default: true
Displays pad text from right to left.

35
doc/api/hooks_client-side.md
View file

@ -126,9 +126,15 @@ Called from: src/static/js/pad.js
Things in context:
1. ace - the ace object that is applied to this editor.
2. pad - the pad object of the current pad.
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.
## postTimesliderInit
Called from: src/static/js/timeslider.js
There doesn't appear to be any example available of this particular hook being used, but it gets fired after the timeslider is all set up.
## userJoinOrUpdate
Called from: src/static/js/pad_userlist.js
@ -138,6 +144,20 @@ 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.
## chatNewMessage
Called from: src/static/js/chat.js
Things in context:
1. authorName - The user that wrote this message
2. author - The authorID of the user that wrote the message
2. text - the message text
3. sticky (boolean) - if you want the gritter notification bubble to fade out on its own or just sit there
3. timestamp - the timestamp of the chat message
4. timeStr - the timestamp as a formatted string
This hook is called on the client side whenever a chat message is received from the server. It can be used to create different notifications for chat messages.
## collectContentPre
Called from: src/static/js/contentcollector.js
@ -242,3 +262,18 @@ This hook is provided to allow whether a given line should be deliniated with mu
Multiple authors in one line cause the creation of magic span lines. This might not suit you and
now you can disable it and handle your own deliniation.
The return value should be either true(disable) or false.
## aceSetAuthorStyle
Called from: src/static/js/ace2_inner.js
Things in context:
1. dynamicCSS - css manger for inner ace
2. outerDynamicCSS - css manager for outer ace
3. parentDynamicCSS - css manager for parent document
4. info - author style info
5. author - author info
6. authorSelector - css selector for author span in inner ace
This hook is provided to allow author highlight style to be modified.
Registered hooks should return 1 if the plugin handles highlighting. If no plugin returns 1, the core will use the default background-based highlighting.

92
doc/api/http_api.md
View file

@ -7,7 +7,7 @@ The API gives another web application control of the pads. The basic functions a
* 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.
The API is designed in a way, so you can reuse your existing user system with their permissions, and map it to Etherpad. Means: Your web application still has to do authentication, but you can tell Etherpad via the api, which visitors should get which permissions. This allows Etherpad 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/ether/etherpad-lite/wiki/HTTP-API-client-libraries) to see if a library in your favorite language.
@ -61,7 +61,9 @@ Portal submits content into new blog post
## Usage
### API version
The latest version is `1.2`
The latest version is `1.2.8`
The current version can be queried via /api.
### Request Format
@ -101,7 +103,7 @@ Responses are valid JSON in the following format:
### 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.
Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad deployment. This token will be random string, generated by Etherpad at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad. Only Etherpad and the requesting application knows this key. Token management will not be exposed through this API.
### Node Interoperability
@ -130,7 +132,7 @@ creates a new group
#### createGroupIfNotExistsFor(groupMapper)
* API >= 1
this functions helps you to map your application group ids to etherpad lite group ids
this functions helps you to map your application group ids to Etherpad group ids
*Example returns:*
* `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}`
@ -186,7 +188,7 @@ creates a new author
#### createAuthorIfNotExistsFor(authorMapper [, name])
* API >= 1
this functions helps you to map your application author ids to etherpad lite author ids
this functions helps you to map your application author ids to Etherpad author ids
*Example returns:*
* `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}`
@ -302,6 +304,66 @@ returns the text of a pad formatted as HTML
* `{code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### setHTML(padID, text)
* API >= 1
sets the html 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}`
#### getAttributePool(padID)
* API >= 1.2.8
returns the attribute pool of a pad
*Example returns:*
* `{ "code":0,
"message":"ok",
"data": {
"pool":{
"numToAttrib":{
"0":["author","a.X4m8bBWJBZJnWGSh"],
"1":["author","a.TotfBPzov54ihMdH"],
"2":["author","a.StiblqrzgeNTbK05"],
"3":["bold","true"]
},
"attribToNum":{
"author,a.X4m8bBWJBZJnWGSh":0,
"author,a.TotfBPzov54ihMdH":1,
"author,a.StiblqrzgeNTbK05":2,
"bold,true":3
},
"nextNum":4
}
}
}`
* `{"code":1,"message":"padID does not exist","data":null}`
#### getRevisionChangeset(padID, [rev])
* API >= 1.2.8
get the changeset at a given revision, or last revision if 'rev' is not defined.
*Example returns:*
* `{ "code" : 0,
"message" : "ok",
"data" : "Z:1>6b|5+6b$Welcome to Etherpad!\n\nThis pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!\n\nGet involved with Etherpad at http://etherpad.org\n"
}`
* `{"code":1,"message":"padID does not exist","data":null}`
* `{"code":1,"message":"rev is higher than the head revision of the pad","data":null}`
#### createDiffHTML(padID, startRev, endRev)
* API >= 1.2.7
returns an object of diffs from 2 points in a pad
*Example returns:*
* `{"code":0,"message":"ok","data":{"html":"<style>\n.authora_HKIv23mEbachFYfH {background-color: #a979d9}\n.authora_n4gEeMLsv1GivNeh {background-color: #a9b5d9}\n.removed {text-decoration: line-through; -ms-filter:'progid:DXImageTransform.Microsoft.Alpha(Opacity=80)'; filter: alpha(opacity=80); opacity: 0.8; }\n</style>Welcome to Etherpad!<br><br>This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!<br><br>Get involved with Etherpad at <a href=\"http&#x3a;&#x2F;&#x2F;etherpad&#x2e;org\">http:&#x2F;&#x2F;etherpad.org</a><br><span class=\"authora_HKIv23mEbachFYfH\">aw</span><br><br>","authors":["a.HKIv23mEbachFYfH",""]}}`
* `{"code":4,"message":"no or wrong API Key","data":null}`
### Chat
#### getChatHistory(padID, [start, end])
* API >= 1.2.7
@ -373,6 +435,24 @@ returns the list of users that are currently editing this pad
deletes a pad
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### copyPad(sourceID, destinationID[, force=false])
* API >= 1.2.8
copies a pad with full history and chat. If force is true and the destination pad exists, it will be overwritten.
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### movePad(sourceID, destinationID[, force=false])
* API >= 1.2.8
moves a pad. If force is true and the destination pad exists, it will be overwritten.
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
@ -466,4 +546,4 @@ returns ok when the current api token is valid
lists all pads on this epl instance
*Example returns:*
* `{code: 0, message:"ok", data: ["testPad", "thePadsOfTheOthers"]}`
* `{code: 0, message:"ok", data: {padIDs: ["testPad", "thePadsOfTheOthers"]}}`

2
doc/custom_static.md
View file

@ -1,5 +1,5 @@
# Custom static files
Etherpad Lite allows you to include your own static files in the browser, by modifying the files in `static/custom`.
Etherpad allows you to include your own static files in the browser, by modifying the files in `static/custom`.
* `index.js` Javascript that'll be run in `/`
* `index.css` Stylesheet affecting `/`

2
doc/documentation.md
View file

@ -2,7 +2,7 @@
<!-- type=misc -->
The goal of this documentation is to comprehensively explain Etherpad-Lite,
The goal of this documentation is to comprehensively explain Etherpad,
both from a reference as well as a conceptual point of view.
Where appropriate, property types, method arguments, and the arguments

2
doc/easysync/README.md
View file

@ -1,2 +1,2 @@
# About this folder
We put all documentations we found about the old Etherpad together in this folder. Most of this is still valid for Etherpad Lite
We put all documentations we found about the original Etherpad together in this folder. Most of this is still valid for the current (node.js based) Etherpad.

14
doc/easysync/easysync-notes.txt
View file

@ -79,14 +79,14 @@ Here are descriptions of the operations, where capital letters are variables:
kept MUST be a newline, and the final newline of the document is allowed.
"*I" : Apply attribute I from the pool to the following +, =, |+, or |= command.
In other words, any number of * ops can come before a +, =, or | but not
between a | and the corresponding + or =.
between a | and the corresponding + or =.
If +, text is inserted having this attribute. If =, text is kept but with
the attribute applied as an attribute addition or removal.
Consecutive attributes must be sorted lexically by (key,value) with key
and value taken as strings. It's illegal to have duplicate keys
for (key,value) pairs that apply to the same text. It's illegal to
have an empty value for a key in the case of an insertion (+), the
pair should just be omitted.
the attribute applied as an attribute addition or removal.
Consecutive attributes must be sorted lexically by (key,value) with key
and value taken as strings. It's illegal to have duplicate keys
for (key,value) pairs that apply to the same text. It's illegal to
have an empty value for a key in the case of an insertion (+), the
pair should just be omitted.
Characters from the source text that aren't accounted for are assumed to be kept
with the same attributes.

1
doc/index.md
View file

@ -1,4 +1,5 @@
@include documentation
@include stats
@include localization
@include custom_static
@include api/api

16
doc/localization.md
View file

@ -1,5 +1,5 @@
# Localization
Etherpad lite provides a multi-language user interface, that's apart from your users' content, so users from different countries can collaborate on a single document, while still having the user interface displayed in their mother tongue.
Etherpad provides a multi-language user interface, that's apart from your users' content, so users from different countries can collaborate on a single document, while still having the user interface displayed in their mother tongue.
## Translating
@ -19,9 +19,9 @@ Translations will be send back to us regularly and will eventually appear in the
`/src/locales` contains files for all supported languages which contain the translated strings. Translation files are simple `*.json` files and look like this:
```json
{ "pad.modals.connected": "Connecté."
, "pad.modals.uderdup": "Ouvrir dans une nouvelle fenêtre."
, "pad.toolbar.unindent.title": "Désindenter"
{ "pad.modals.connected": "Connecté."
, "pad.modals.uderdup": "Ouvrir dans une nouvelle fenêtre."
, "pad.toolbar.unindent.title": "Dèsindenter"
, "pad.toolbar.undo.title": "Annuler (Ctrl-Z)"
, "timeslider.pageTitle": "{{appTitle}} Curseur temporel"
, ...
@ -50,7 +50,7 @@ to:
<option data-l10n-id="ep_heading.h1" value="0"></option>
```
In the javascript files of your plugin, chaneg all hardcoded messages/strings...
In the javascript files of your plugin, change all hardcoded messages/strings...
from:
```js
@ -75,7 +75,7 @@ alert(window._('pad.chat'));
*ep_your-plugin/locales/es.json*
```
{ "ep_your-plugin.h1": "Título 1"
{ "ep_your-plugin.h1": "Título 1"
}
```
@ -83,7 +83,7 @@ Everytime the http server is started, it will auto-detect your messages and merg
### Overwrite core messages
You can overwrite Etherpad Lite's core messages in your plugin's locale files.
You can overwrite Etherpad's core messages in your plugin's locale files.
For example, if you want to replace `Chat` with `Notes`, simply add...
*ep_your-plugin/locales/en.json*
@ -91,4 +91,4 @@ For example, if you want to replace `Chat` with `Notes`, simply add...
{ "ep_your-plugin.h1": "Heading 1"
, "pad.chat": "Notes"
}
```
```

4
doc/plugins.md
View file

@ -1,5 +1,5 @@
# Plugins
Etherpad-Lite allows you to extend its functionality with plugins. A plugin registers hooks (functions) for certain events (thus certain features) in Etherpad-lite to execute its own functionality based on these events.
Etherpad allows you to extend its functionality with plugins. A plugin registers hooks (functions) for certain events (thus certain features) in Etherpad-lite to execute its own functionality based on these events.
Publicly available plugins can be found in the npm registry (see <http://npmjs.org>). Etherpad-lite's naming convention for plugins is to prefix your plugins with `ep_`. So, e.g. it's `ep_flubberworms`. Thus you can install plugins from npm, using `npm install ep_flubberworm` in etherpad-lite's root directory.
@ -104,7 +104,7 @@ Your plugin must also contain a [package definition file](http://npmjs.org/doc/j
```
## Templates
If your plugin adds or modifies the front end HTML (e.g. adding buttons or changing their functions), you should put the necessary HTML code for such operations in `templates/`, in files of type ".ejs", since Etherpad-Lite uses EJS for HTML templating. See the following link for more information about EJS: <https://github.com/visionmedia/ejs>.
If your plugin adds or modifies the front end HTML (e.g. adding buttons or changing their functions), you should put the necessary HTML code for such operations in `templates/`, in files of type ".ejs", since Etherpad uses EJS for HTML templating. See the following link for more information about EJS: <https://github.com/visionmedia/ejs>.
## Writing and running front-end tests for your plugin

18
doc/stats.md Normal file
View file

@ -0,0 +1,18 @@
# Statistics
Etherpad keeps track of the goings-on inside the edit machinery. If you'd like to have a look at this, just point your browser to `/stats`.
We currently measure:
- totalUsers (counter)
- connects (meter)
- disconnects (meter)
- pendingEdits (counter)
- edits (timer)
- failedChangesets (meter)
- httpRequests (timer)
- http500 (meter)
- memoryUsage (gauge)
Under the hood, we are happy to rely on [measured](https://github.com/felixge/node-measured) for all our metrics needs.
To modify or simply access our stats in your plugin, simply `require('ep_etherpad-lite/stats')` which is a `measured.Collection`.

4
doc/template.html
View file

@ -2,12 +2,12 @@
<html lang="en">
<head>
<meta charset="utf-8">
<title>__SECTION__ - Etherpad Lite v__VERSION__ Manual &amp; Documentation</title>
<title>__SECTION__ - Etherpad v__VERSION__ Manual &amp; Documentation</title>
<link rel="stylesheet" href="assets/style.css">
</head>
<body class="apidoc" id="api-section-__FILENAME__">
<header id="header">
<h1>Etherpad-Lite v__VERSION__ Manual &amp; Documentation</h1>
<h1>Etherpad v__VERSION__ Manual &amp; Documentation</h1>
</header>
<div id="toc">