Commit fa2d6cca authored by JC Brand's avatar JC Brand

Update developer documentation and buildout dependencies

parent 2546622d
...@@ -227,10 +227,12 @@ check: eslint dist/converse.js ...@@ -227,10 +227,12 @@ check: eslint dist/converse.js
## Documentation ## Documentation
./bin/activate: ./bin/activate:
virtualenv . python3 -m venv .
.installed.cfg: requirements.txt buildout.cfg .installed.cfg: requirements.txt buildout.cfg
./bin/pip install -r requirements.txt ./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 ./bin/buildout -v
docsdev: ./bin/activate .installed.cfg docsdev: ./bin/activate .installed.cfg
......
...@@ -11,4 +11,5 @@ eggs = ...@@ -11,4 +11,5 @@ eggs =
sphinx-bootstrap-theme sphinx-bootstrap-theme
[versions] [versions]
Sphinx = 1.8.1 Sphinx = 2.1.2
docutils = 0.15.1
...@@ -8,27 +8,14 @@ ...@@ -8,27 +8,14 @@
Development 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 Here you will learn how to add new features and how you can create your own
create your own customized version of Converse. 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.
Converse is a community project and largely volunteer driven. 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/>`_ 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. to fix a bug or to add new functionality.
......
...@@ -10,38 +10,62 @@ Writing a plugin ...@@ -10,38 +10,62 @@ Writing a plugin
Introduction Introduction
------------ ------------
Converse exposes a plugin architecture through which developers can modify Converse.js has a plugin architecture based on `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_
and extend its functionality. and is itself composed out of plugins.
Using plugins is good engineering practice, and using them is the *only* recommended There are only a few files that are included in the default build of Converse
way of changing Converse or adding new features to it. 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). The other non-plugin files all contain utility methods in
From this benefit flows various 2nd degree advantages, such as the ability to `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 make smaller production builds (by excluding unused plugins) and an easier
upgrade path by avoiding touching Converse's internals. 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, 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. 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 Plugins enable developers to extend and override existing objects,
`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,
functions and the `Backbone <http://backbonejs.org/>`_ models and views that make up functions and the `Backbone <http://backbonejs.org/>`_ models and views that make up
Converse. Converse. You can also create new Backbone (or other) models and views.
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>`_.
.. note:: **Trying out a plugin in JSFiddle** .. note:: **Trying out a plugin in JSFiddle**
......
...@@ -20,10 +20,10 @@ We use camelCase for function names and underscores for variables names. ...@@ -20,10 +20,10 @@ We use camelCase for function names and underscores for variables names.
For example: For example:
.. code-block:: javascript .. code-block:: javascript
function thisIsAFunction () { 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 `` ...@@ -34,7 +34,7 @@ In general, spaces are put around operators, such as the equals ``=`` or plus ``
For example: For example:
.. code-block:: javascript .. code-block:: javascript
if (sublocale != locale) { if (sublocale != locale) {
// do something // do something
...@@ -42,7 +42,7 @@ For example: ...@@ -42,7 +42,7 @@ For example:
An exception is when they appear inside for-loop expressions, 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++) { for (i=0; i<msgs_length; i++) {
// do something // do something
...@@ -51,18 +51,23 @@ An exception is when they appear inside for-loop expressions, for example: ...@@ -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 Generally though, rather err on the side of adding spaces, since they make the
code much more readable. 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. all capital letters, with underscores between words.
For example: For example:
.. code-block:: javascript .. code-block:: javascript
const SECONDS_IN_HOUR = 3600;
var SECONDS_IN_HOUR = 3600; function update () {
var seconds_since_message = 0; const timeout = 20;
let seconds_since_message = 0;
// other stuff here
}
Function declaration and invocation Function declaration and invocation
...@@ -71,7 +76,7 @@ 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 When declaring a function, the function name and the brackets after it are separated
with a space. Like so: with a space. Like so:
.. code-block:: javascript .. code-block:: javascript
function update (model) { function update (model) {
model.foo = 'bar'; model.foo = 'bar';
...@@ -80,7 +85,7 @@ with a space. Like so: ...@@ -80,7 +85,7 @@ with a space. Like so:
When calling the same function, the brackets are written without a space in When calling the same function, the brackets are written without a space in
between: between:
.. code-block:: javascript .. code-block:: javascript
update(model); update(model);
...@@ -102,7 +107,7 @@ The closing curly bracket appears on its own line. ...@@ -102,7 +107,7 @@ The closing curly bracket appears on its own line.
For example: For example:
.. code-block:: javascript .. code-block:: javascript
if (locales[locale]) { if (locales[locale]) {
return locales[locale]; return locales[locale];
...@@ -122,7 +127,7 @@ the compiler (for example if its only one line inside the ``if`` statement). ...@@ -122,7 +127,7 @@ the compiler (for example if its only one line inside the ``if`` statement).
For example, like this: For example, like this:
.. code-block:: javascript .. code-block:: javascript
if (condition === true) { if (condition === true) {
this.updateRoomsList(); this.updateRoomsList();
......
...@@ -1831,6 +1831,7 @@ _converse.api = { ...@@ -1831,6 +1831,7 @@ _converse.api = {
* or closured data. To do that, you’ll need to create a plugin, which has * or closured data. To do that, you’ll need to create a plugin, which has
* access to the private API method. * access to the private API method.
* *
* @global
* @namespace converse * @namespace converse
*/ */
const converse = { const converse = {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment