NameDateSize

..16-Mar-201612 KiB

.gitignore29-Dec-2012989

bin/18-May-20134 KiB

contrib/29-Dec-20124 KiB

CONTRIBUTORS29-Dec-20121.5 KiB

COPYING29-Dec-201211.1 KiB

debian/29-Dec-20124 KiB

etherpad/29-Dec-20124 KiB

infrastructure/29-Dec-20124 KiB

INSTALL29-Dec-20122.8 KiB

LICENSE29-Dec-201212.1 KiB

README.md29-Dec-2012385

README.plugins29-Dec-20123.7 KiB

README.themes29-Dec-20124.2 KiB

redhat/29-Dec-20124 KiB

README.md

1# About Etherpad
2# Etherpad (this version) has been superseded by Etherpad Lite #
3Etherpad Lite is a simplier, faster, lighter solution for collaborative editing.  Please use that and develop on that as it is the active project.
4<https://github.com/ether/etherpad-lite>
5
6EtherPad is a web-based realtime collaborative document editor.
7
8EtherPad currently lives at <http://etherpad.org>

README.plugins

1Plugins are hooks
2------------------
3
4The plugin infrastructure is really a hook infrastructure. It provides
5a way for code anywhere in EtherPad (including in other plugins) to
6create a hook call, and for plugins to register for such hooks to have
7their code run when the hook call is done.
8
9All the power of plugins comes from the hooks available to them.
10
11For details on how the plugin API works, please see the comments in
12the "test" plugin (etherpad/src/plugins/test).
13
14
15On the calling side
16--------------------
17
18To create a hook call, call plugins.callHook(hookName, args) where
19hookName is any descriptive string that can be used as a JavaScript
20function name, and args is a dictionary/object. This function will
21call any hooks registered with hookName with one parameter, args, and
22concatenate their result lists (each must return a list, see below).
23Note: if no plugins are registered for this hook, this function
24returns the empty list.
25
26There is also a helper function, callHookSt that returns a string,
27constructed by concatenating all strings in the returned lists. This
28is mainly usefull from within templates.
29
30
31On the plugin side
32-------------------
33
34Each plugin must contain a main.js module with an object constructor
35function named as the plugin but with "Init" appended. The returned
36object describes the plugin and declares hook registrations.
37
38Each hook function must take one parameter, an dictionary/object, and
39return a list of values. The properties available on the parameter
40object is dependent on the hook the function is registered for.
41
42
43Client side hooks
44------------------
45
46Etherpad runs a sizeable chunk of JavaScript code on the client side,
47that is, in the users' browsers. Because of this there is a need to be
48able to extend that code with plugins the same way that code on the
49server is extended.
50
51The hook system is replicated on the client side - there is a
52plugins.callHook() and plugins can register client side functions to
53be called when that hook is called for.
54
55This registration is done from a client side java script file called
56static/js/main.js. There is one major catch with this file: It runs
57both on the server and client! Beware!
58
59static/js/main.js is modelled after the main main.js, and imported by
60that one on the server. The descriptor object created by
61pluginNameInit() in static/js/main.js is also included as a property
62on the main plugin descriptor object described above,
63
64
65Hooks that plugins can provide
66-------------------------------
67
68All hooks must return either undefined/null or a list of return
69values. This list might contain any number of values, including none
70at all or just one.
71
72aceAttribsToClasses
73  Type: client, server
74adminMenu
75collectContentPost
76  Type: client, server
77collectContentPre 
78  Type: client, server
79docBarDropdownsAll
80docBarDropdownsPad
81docbarItemsAdmin
82docbarItemsAll
83docbarItemsPad
84docbarItemsPluginManager
85docbarItemsTagBrowser
86docbarItemsTagBrowserPad
87editBarDropdownsAll
88editBarDropdownsPad
89editBarItemsLeftAll
90editBarItemsLeftPad
91editBarItemsRightAll
92editBarItemsRightPad
93handleAdminPath
94handlePath
95  Registers new urls to serve
96  Type: server
97  Parameters: None
98  Returns: Parameter suitable for Dispatcher
99padModelWriteToDB
100renderNavigation
101renderPageBodyPre [DEPRECATED]
102  Adds extra html before the body of a page
103  Type: server
104  Parameters: bodyFileName, data, plugin
105  Returns: String(s) of html
106renderPageBodyPost [DEPRECATED]
107  Adds extra html after the body of a page
108  Type: server
109  Parameters: bodyFileName, data, plugin
110  Returns: String(s) of html
111serverShutdown
112  Run before server shutdown
113  Type: server
114  Parameters: None
115  Returns: None
116serverStartup
117  Run right after server startup
118  Type: server
119  Parameters: None
120  Returns: None
121

README.themes

1Themes are templates
2---------------------
3
4The theme infrastructure is really a templating library. It consists
5of an extended version of EJS (like ERB but for JavaScript).
6
7Many templating libraries (Smarty, Django templates) adds a special
8template script language that provides things like inheritance and
9blocks, but also general programming constructs like loops and
10conditionals.
11
12The EJS templating language uses JavaScript as templating scripting
13language, giving you the full power JavaScript in your templates. In
14addition, it provides a standard library for interacting with the
15template content.
16
17EJS tags
18---------
19
20An EJS template consist of verbatim HTML (or other text) and
21server-side JavaScripts mixed in one file. There are three syntaxes
22available to mix in JavaScript in the verbatim HTML:
23
24  <h1>some HTML</h1>
25  <% myVar = someJavaScript(); xyzzy = goesHere(); %>
26  <p>some more HTML</p>
27  <% if (myVar != '') { %>
28    myVar is not empty
29  <% } %>
30
31This will execute the javascript statements beteen <% and %>, but
32throw away any result values. To insert a value in the generated HTML,
33you use the <%= syntax:
34
35  <p>Result from previous code plus 47: <%= xyzzy + 47 %></p>
36
37This will convert the value in the expression to string and then
38include it. If the value already is a string, you can gain a little
39more expressive freedom by using the <%: syntax instead:
40
41  <p>Result from previous code: <%: myVar %></p>
42
43The advantage of the latter one is that it does not require the code
44between <%: and %> to be a full JavaScript expression, but can be a
45fragment of one. To understand how this is usefull, we have to examine
46another property of EJS: What happens to verbatim HTML.
47
48
49Verbatim text in EJS and the evaluation model
50----------------------------------------------
51
52During evaluation of an EJS template, verbatim HTML is appended to a
53variable called ejs_data, one part at a time. Consider the following code:
54
55  Some text
56  <% temp = ejs_data; ejs_data = ''; %>
57  some text to be encoded
58  <% data = base64encode(ejs_data); ejs_data = temp; %>
59  Base64 dump: <%= data %>
60
61This will encode the string "some text to be encoded" with the
62base64encode function and insert the result at the end of the output.
63The original, unencoded string is not inserted in the output.
64
65Since ejs_data is just a normal variable that can be hidden by a local
66variable in a function, this allows for creating functions that
67returns mostly text using the normal EJS templating syntax:
68
69  <% function header(n) { var ejs_data = ''; %>
70    Hello world <%= n %> times!
71  <% return ejs_data; } %>
72
73This is equivalent to
74
75  <%
76    function (n) {
77      return "Hello world " + n + " times!";
78    }
79  %>
80
81Of course this only starts to be usefull when the function should
82return a larger body of verbatim text.
83
84So, back to the usefullness of the <%: syntax:
85
86  Base64 dump:
87  <%: base64encode(function () { var ejs_data = ''; %>
88    some text to be encoded
89  <% return ejs_data; }); %>
90
91Here, the base64encode function call only ends inside the last <% %>
92block. This type of expression is extensively used for the template
93inheritance and block functions.
94
95Standard functions
96-------------------
97
98In addition to the ability to mix verbatim text and code, templates
99needs some additional functionality not found in a scripting language,
100or at least not in the same form. This include textual inheritance and
101blocks.
102
103In EJS this is provided by a standrad function library.
104
105template.inherit('page.ejs');
106  Declares that the template inherits from another template, page.ejs.
107  This should only be called once in a template, and at the top.
108
109<%: template.use('blockName'); %>
110<%: template.use('blockName', function() { var ejs_data=''; %>Default content<% return ejs_data; }); %>
111  Declares a block that can be overridden by an inheriting template.
112  If the first form of the call is used the block is empty unless
113  overridden.
114
115<% template.define('blockName', function() { var ejs_data=''; %>New block content<% return ejs_data; }); %>
116  Overrides the content of a block of an inherited template.
117
118Note: All templates should define (or inherit from a template that
119defines) a top-level block named "body". The content of this block,
120will be the final output of the template.
121