Update developer documentation and buildout dependencies
This commit is contained in:
parent
2546622da3
commit
fa2d6cca10
4
Makefile
4
Makefile
|
@ -227,10 +227,12 @@ check: eslint dist/converse.js
|
|||
## Documentation
|
||||
|
||||
./bin/activate:
|
||||
virtualenv .
|
||||
python3 -m venv .
|
||||
|
||||
.installed.cfg: requirements.txt buildout.cfg
|
||||
./bin/pip install -r requirements.txt
|
||||
./bin/pip install --upgrade pip==19.2.1
|
||||
./bin/pip install --upgrade setuptools==41.0.1
|
||||
./bin/buildout -v
|
||||
|
||||
docsdev: ./bin/activate .installed.cfg
|
||||
|
|
|
@ -11,4 +11,5 @@ eggs =
|
|||
sphinx-bootstrap-theme
|
||||
|
||||
[versions]
|
||||
Sphinx = 1.8.1
|
||||
Sphinx = 2.1.2
|
||||
docutils = 0.15.1
|
||||
|
|
|
@ -8,27 +8,14 @@
|
|||
Development
|
||||
===========
|
||||
|
||||
Welcome to the developer documentation of Converse.
|
||||
Welcome to the developer documentation of Converse.js.
|
||||
|
||||
Read the documentation linked to below, if you want to add new features or
|
||||
create your own customized version of Converse.
|
||||
|
||||
Converse has a plugin architecture (see `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_)
|
||||
which lets you add new features or modify existing functionality without having to touch
|
||||
the core files (in the `src/ <https://github.com/conversejs/converse.js/tree/master/src>`_ directory).
|
||||
This is the recommended way to customize or add new functionality to Converse.
|
||||
|
||||
Plugins are especially useful if you want to add proprietary modifications, since the
|
||||
Mozilla Public License version 2 doesn't require you to open source your
|
||||
plugins. Be aware that this doesn't apply when you intend to use libsignal for
|
||||
OMEMO encryption because libsignal's license is GPLv3.
|
||||
|
||||
Refer to the section on `plugin development <https://conversejs.org/docs/html/plugin_development.html>`_
|
||||
for more info on how to write plugins.
|
||||
Here you will learn how to add new features and how you can create your own
|
||||
customized version of Converse.
|
||||
|
||||
Converse is a community project and largely volunteer driven.
|
||||
|
||||
We're grateful for your contributions, so please don't hesitate to
|
||||
We're grateful for your contributions, so please don't hesitate to
|
||||
make a `Github pull request <https://help.github.com/categories/collaborating-with-issues-and-pull-requests/>`_
|
||||
to fix a bug or to add new functionality.
|
||||
|
||||
|
|
|
@ -10,38 +10,62 @@ Writing a plugin
|
|||
Introduction
|
||||
------------
|
||||
|
||||
Converse exposes a plugin architecture through which developers can modify
|
||||
and extend its functionality.
|
||||
Converse.js has a plugin architecture based on `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_
|
||||
and is itself composed out of plugins.
|
||||
|
||||
Using plugins is good engineering practice, and using them is the *only* recommended
|
||||
way of changing Converse or adding new features to it.
|
||||
There are only a few files that are included in the default build of Converse
|
||||
which aren't plugins.
|
||||
|
||||
In particular, plugins have the following advantages:
|
||||
An important one is `converse-core.js <https://github.com/conversejs/converse.js/blob/master/src/headless/converse-core.js>`_,
|
||||
which is responsible for bootstrapping the plugin architecture,
|
||||
setting up and maintaining the connection to the XMPP
|
||||
server and declaring the public (`window.converse </docs/html/api/converse.html>`_) and protected (`_converse.api </docs/html/api/-_converse.api.html>`_) APIs.
|
||||
|
||||
The main benefit of plugins is their *isolation of concerns* (and features).
|
||||
From this benefit flows various 2nd degree advantages, such as the ability to
|
||||
The other non-plugin files all contain utility methods in
|
||||
`src/utils <https://github.com/conversejs/converse.js/blob/master/src/utils>`_ and
|
||||
`src/headless/utils <https://github.com/conversejs/converse.js/blob/master/src/headless/utils>`_.
|
||||
|
||||
As a general rule, any file in the ``./src`` directory that starts with
|
||||
``converse-`` is a plugin (with the exception of ``converse-core.js``.
|
||||
|
||||
The plugin architecture lets you add new features or modify existing functionality in a
|
||||
modular and self-contained way, without having to change other files.
|
||||
|
||||
This ensures that plugins are fully optional (one of the design goals of
|
||||
Converse) and can be removed from the main build without breaking the app.
|
||||
For example, the ``converse-omemo``,
|
||||
``converse-rosterview``, ``converse-dragresize``, ``converse-minimize``,
|
||||
``converse-muc`` and ``converse-muc-views`` plugins can all be removed from the
|
||||
build without breaking the app.
|
||||
|
||||
To more deeply understand how the plugin architecture works, read the
|
||||
`pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
|
||||
and to understand its inner workings, refer to the `annotated source code
|
||||
<https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
|
||||
|
||||
Advantages of plugins
|
||||
---------------------
|
||||
|
||||
Writing a plugin is the recommended way to customize or add new features to Converse.
|
||||
|
||||
The main benefit of plugins is that they allow for **isolation of concerns** (and features).
|
||||
From this benefit flows various 2nd order advantages, such as the ability to
|
||||
make smaller production builds (by excluding unused plugins) and an easier
|
||||
upgrade path by avoiding touching Converse's internals.
|
||||
|
||||
Plugins are especially useful if you want to add proprietary modifications, since the
|
||||
Mozilla Public License version 2 doesn't require you to open source your
|
||||
plugin files. Be aware that this doesn't apply when you intend to use libsignal for
|
||||
OMEMO encryption because libsignal's license is GPLv3 (and turns the entire app
|
||||
into a GPLv3 app).
|
||||
|
||||
Each plugin comes in its own file, and Converse's plugin architecture,
|
||||
called `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_, provides you
|
||||
`pluggable.js <https://github.com/jcbrand/pluggable.js/>`_, provides you
|
||||
with the ability to "hook in" to the core code and other plugins.
|
||||
|
||||
Converse itself is composed out of plugins and uses pluggable.js. Take a look at the
|
||||
`src <https://github.com/jcbrand/converse.js/tree/master/src>`_ directory. All
|
||||
the files that follow the pattern `converse-*.js` are plugins.
|
||||
|
||||
Plugins (by way of Pluggable.js) enable developers to extend and override existing objects,
|
||||
Plugins enable developers to extend and override existing objects,
|
||||
functions and the `Backbone <http://backbonejs.org/>`_ models and views that make up
|
||||
Converse.
|
||||
|
||||
Besides that, in plugins you can also write new Backbone (or other) models and views,
|
||||
in order to add a new functionality.
|
||||
|
||||
To more deeply understand how this plugin architecture works, please read the
|
||||
`pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
|
||||
and to understand its inner workings, please refer to the `annotated source code
|
||||
<https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
|
||||
Converse. You can also create new Backbone (or other) models and views.
|
||||
|
||||
.. note:: **Trying out a plugin in JSFiddle**
|
||||
|
||||
|
|
|
@ -20,10 +20,10 @@ We use camelCase for function names and underscores for variables names.
|
|||
|
||||
For example:
|
||||
|
||||
.. code-block:: javascript
|
||||
.. code-block:: javascript
|
||||
|
||||
function thisIsAFunction () {
|
||||
var this_is_a_variable;
|
||||
let this_is_a_variable;
|
||||
...
|
||||
}
|
||||
|
||||
|
@ -34,7 +34,7 @@ In general, spaces are put around operators, such as the equals ``=`` or plus ``
|
|||
|
||||
For example:
|
||||
|
||||
.. code-block:: javascript
|
||||
.. code-block:: javascript
|
||||
|
||||
if (sublocale != locale) {
|
||||
// do something
|
||||
|
@ -42,7 +42,7 @@ For example:
|
|||
|
||||
An exception is when they appear inside for-loop expressions, for example:
|
||||
|
||||
.. code-block:: javascript
|
||||
.. code-block:: javascript
|
||||
|
||||
for (i=0; i<msgs_length; i++) {
|
||||
// do something
|
||||
|
@ -51,18 +51,23 @@ An exception is when they appear inside for-loop expressions, for example:
|
|||
Generally though, rather err on the side of adding spaces, since they make the
|
||||
code much more readable.
|
||||
|
||||
Constants are written in ALL_CAPS
|
||||
---------------------------------
|
||||
Global constants are written in ALL_CAPS
|
||||
----------------------------------------
|
||||
|
||||
Identifiers that denote constant values should be written in
|
||||
Global identifiers that denote constant values should be written in
|
||||
all capital letters, with underscores between words.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: javascript
|
||||
.. code-block:: javascript
|
||||
|
||||
var SECONDS_IN_HOUR = 3600;
|
||||
var seconds_since_message = 0;
|
||||
const SECONDS_IN_HOUR = 3600;
|
||||
|
||||
function update () {
|
||||
const timeout = 20;
|
||||
let seconds_since_message = 0;
|
||||
// other stuff here
|
||||
}
|
||||
|
||||
|
||||
Function declaration and invocation
|
||||
|
@ -71,7 +76,7 @@ Function declaration and invocation
|
|||
When declaring a function, the function name and the brackets after it are separated
|
||||
with a space. Like so:
|
||||
|
||||
.. code-block:: javascript
|
||||
.. code-block:: javascript
|
||||
|
||||
function update (model) {
|
||||
model.foo = 'bar';
|
||||
|
@ -80,7 +85,7 @@ with a space. Like so:
|
|||
When calling the same function, the brackets are written without a space in
|
||||
between:
|
||||
|
||||
.. code-block:: javascript
|
||||
.. code-block:: javascript
|
||||
|
||||
update(model);
|
||||
|
||||
|
@ -102,7 +107,7 @@ The closing curly bracket appears on its own line.
|
|||
|
||||
For example:
|
||||
|
||||
.. code-block:: javascript
|
||||
.. code-block:: javascript
|
||||
|
||||
if (locales[locale]) {
|
||||
return locales[locale];
|
||||
|
@ -122,7 +127,7 @@ the compiler (for example if its only one line inside the ``if`` statement).
|
|||
|
||||
For example, like this:
|
||||
|
||||
.. code-block:: javascript
|
||||
.. code-block:: javascript
|
||||
|
||||
if (condition === true) {
|
||||
this.updateRoomsList();
|
||||
|
|
|
@ -1 +1 @@
|
|||
zc.buildout==2.12.1
|
||||
zc.buildout==2.13.2
|
||||
|
|
|
@ -1831,6 +1831,7 @@ _converse.api = {
|
|||
* or closured data. To do that, you’ll need to create a plugin, which has
|
||||
* access to the private API method.
|
||||
*
|
||||
* @global
|
||||
* @namespace converse
|
||||
*/
|
||||
const converse = {
|
||||
|
|
Reference in New Issue