Skip to content

C
converse.js
Commit cb8b5a70 authored by JC Brand's avatar JC Brand
Browse files
Options

Update the developer documentation

parent c37a1dcb
Hide whitespace changes
Inline Side-by-side
Showing with 302 additions and 242 deletions
docs/source/api/index.rst
View file @ cb8b5a70
...@@ -2,9 +2,9 @@ ...@@ -2,9 +2,9 @@
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div> <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
===================== ============================================
The API documentation The API documentation (generated with JSDoc)
===================== ============================================
This document is a stub. It shouldn't show at all, instead it's a hack in order This document is a stub. It shouldn't show at all, instead it's a hack in order
to link to the JSDoc output. to link to the JSDoc output.
......
docs/source/builds.rst
View file @ cb8b5a70
...@@ -5,9 +5,9 @@ ...@@ -5,9 +5,9 @@
.. _builds: .. _builds:
=============== =================
Creating builds Generating builds
=============== =================
.. contents:: Table of Contents .. contents:: Table of Contents
:depth: 3 :depth: 3
...@@ -15,72 +15,65 @@ Creating builds ...@@ -15,72 +15,65 @@ Creating builds
.. warning:: There current documentation in this section does not adequately .. warning:: There current documentation in this section does not adequately
explain how to create custom builds. explain how to create custom bundles.
.. note:: Please make sure to read the section :doc:`development` and that you have installed .. Note:: Please make sure to read the section :doc:`development` and that you have installed
all development dependencies (long story short, you should be able to just run ``make dev``) all development dependencies (long story short, you should be able to just run ``make dev``)
Creating builds and distribution files Creating JavaScript and CSS bundles and distribution files
====================================== ==========================================================
Converse.js uses `AMD (Asynchronous Modules Definition) <http://requirejs.org/docs/whyamd.html#amd>`_ Converse uses `webpack <https://webpack.js.org/>`_ to create single build files containing the core code and
to define modules and their dependencies. all of the 3rd party dependencies.
Dependencies can then be loaded on-the-fly with `require.js <http://requirejs.org>`_. These files are in the `dist <https://github.com/conversejs/converse.js/tree/master/dist>`_ directory.
This is very useful during development, but when it comes to
deployement you'll usually want to create a single, minified distribution build.
For this, the `r.js optimizer <http://requirejs.org/docs/optimization.html>`_ Before you start changing the core code, you can run ``make watchjs`` in your terminal.
is used together with `almond.js <https://github.com/requirejs/almond>`_, which
is a smaller and minimal AMD API implementation that replaces require.js in builds.
To create the distribution builds, simply run:: This command will listen for any changed files and then automatically create a
new build of ``dist/converse.js``.
make dist The CSS files are also generated, from the scss files in the
`sass <https://github.com/conversejs/converse.js/tree/master/sass>`_ directory.
This command does the following:
* It creates different builds of Converse.js in the ``./dist/`` directory. Similarly to ``make watchjs``, you can run ``make watch`` to automatically
generate the css files in the ``./css/`` directory.
* It bundles all the translation files in ``./locale/`` into a single file ``locales.js``. The Converse repository does not include the minified files in the ``dist`` or
This file can then be included via the ``<script>`` tag. See for example the ``non_amd.html`` example page. ``css`` directories. Before deployment, you'll want to generate them yourself.
* Also, the CSS files in the ``./css`` directory will be minified. To do so, run the following:
The JavaScript build files are contained in the ``./dist`` directory: ::
make dist/converse.min.js
make css/converse.min.css
.. code-block:: bash Alternatively, if you want to generate ALL the bundles files (minified and
unminified), then you can also run::
jc@conversejs:~/converse.js (master)$ ls dist/ make dist
converse-mobile.js converse.min.js
converse-mobile.min.js converse.nojquery.js
converse-no-dependencies.js converse.nojquery.min.js
converse-no-dependencies.min.js locales.js
converse.js
.. _`minification`:
Creating custom builds Creating custom bundles
---------------------- =======================
One reason you might want to create your own builds, is because you want to One reason you might want to create your own bundles, is because you want to
remove some of the core plugins of converse.js, or perhaps you want to include remove some of the core plugins of Converse, or perhaps you want to include
your own. your own.
To add or remove plugins from the build, you need to modify the To add or remove plugins from the build, you need to modify the
``src/converse.js`` file. `src/converse.js <https://github.com/conversejs/converse.js/blob/master/src/converse.js>`_ file.
You'll find a section marked ``/* START: Removable components`` and You'll find a section marked ``/* START: Removable components`` and
``/* END: Removable components */``. ``/* END: Removable components */``.
In this section is listed all the converse.js plugins that will make up a In this section is listed the Converse plugins that will make up a bundle.
build.
You could for example decide to disable the ControlBox altogether by removing You could for example decide to disable the ControlBox altogether by removing
the ``converse-controlbox`` plugin. the ``converse-controlbox`` plugin.
After doing so, you need to run ``make dist`` again in the root or your After doing so, you need to run ``make dist`` again in the root or your
converse.js repository, in order to generate the new build. Converse repository, in order to generate the new build.
Be aware that some plugins might have dependencies on other plugins, so if you Be aware that some plugins might have dependencies on other plugins, so if you
remove a certain plugin but other included plugins still depend on it, then it remove a certain plugin but other included plugins still depend on it, then it
...@@ -91,12 +84,35 @@ text editor and look at the list specified as the second parameter to the ...@@ -91,12 +84,35 @@ text editor and look at the list specified as the second parameter to the
``define`` call, near the top of the file. This list specifies the dependencies ``define`` call, near the top of the file. This list specifies the dependencies
of that plugin. of that plugin.
Minifying the CSS Besides the standard build, the Converse repository includes configuration
----------------- for certain other non-standard builds, which we'll now mention below.
Excluding all 3rd party dependencies
------------------------------------
The ``dist/converse-no-dependencies.js`` bundle contains only the core Converse
code and none of the 3rd party dependencies. This might be useful if you need
to load the dependencies separately.
To generate this bundle, you can run:
::
make dist/converse-no-dependencies.js
make dist/converse-no-dependencies.min.js
Headless build
--------------
To only minify the CSS files, nothing else, run the following command:: There is also the option of making a headless build of Converse.
make cssmin This is a build without any UI code but still containing the core functionality of
maintaining a roster, chats and messages.
The CSS files are minified via `cssmin <https://github.com/gruntjs/grunt-contrib-cssmin>`_. The file `src/headless.js <https://github.com/jcbrand/converse.js/blob/master/src/headless.js>`_
is used to determine which plugins are included in the build.
.. Note:: Unfortunately it's currently not yet possible to include Multi-user chat (MUC)
functionality in the headless build. This is because both the UI and core
functionality is still contained in one plugin and would first need to be
split up into two parts, with the UI part dropped for this build.
docs/source/developer_guidelines.rst → docs/source/dependencies.rst
View file @ cb8b5a70
...@@ -2,13 +2,12 @@ ...@@ -2,13 +2,12 @@
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div> <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
Developer guidelines ============
==================== Dependencies
============
If you want to work with the non-minified JavaScript and CSS files you'll soon Installing the 3rd party dependencies
notice that there are references to a missing *node_modules* directory. =====================================
Please follow the instructions below to create these directories and fetch Converse's
3rd-party dependencies.
.. note:: .. note::
Windows environment: We recommend installing the required tools using `Chocolatey <https://chocolatey.org/>`_ Windows environment: We recommend installing the required tools using `Chocolatey <https://chocolatey.org/>`_
...@@ -17,89 +16,71 @@ Please follow the instructions below to create these directories and fetch Conve ...@@ -17,89 +16,71 @@ Please follow the instructions below to create these directories and fetch Conve
please read `this post <http://librelist.com/browser//conversejs/2014/11/5/openfire-converse-and-visual-studio-questions/#b28387e7f8f126693b11598a8acbe810>`_ please read `this post <http://librelist.com/browser//conversejs/2014/11/5/openfire-converse-and-visual-studio-questions/#b28387e7f8f126693b11598a8acbe810>`_
in the mailing list.: in the mailing list.:
Installing the development and front-end dependencies
-----------------------------------------------------
We use development tools which depend on Node.js and npm (the Node package manager). We use development tools which depend on Node.js and npm (the Node package manager).
If you don't have Node.js installed, you can download and install the latest If you don't have Node.js installed, you can download and install the latest
version `here <https://nodejs.org/download>`_. version `here <https://nodejs.org/download>`_.
Also make sure you have ``Git`` installed. `Details <http://git-scm.com/book/en/Getting-Started-Installing-Git>`_. Alternatively you can `use your operating system's package manager to install
Node.js <https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions>`_.
.. note:: Also make sure you have ``Git`` installed. `See here <http://git-scm.com/book/en/Getting-Started-Installing-Git>`_.
Windows users should use Chocolatey as recommended above.
.. note::
Debian & Ubuntu users : apt-get install git npm nodejs-legacy
Once you have *Node.js* and *git* installed, run the following command inside the Converse.js Now use ``git`` to check out the Converse repository:
directory:
:: ::
git clone git@github.com:conversejs/converse.js.git
Now go into the repository checkout and run ``make dev`` in order to set up the
development environment.
::
cd converse.js
make dev make dev
On Windows you need to specify Makefile.win to be used by running: :: On Windows you need to specify Makefile.win to be used by running:
::
make -f Makefile.win dev make -f Makefile.win dev
Or alternatively, if you don't have GNU Make: Alternatively, if you don't have GNU Make (necessary for the ``make`` command),
you can use NPM directly:
:: ::
npm install npm install
This will install the Node.js development tools and Converse.js's front-end dependencies.
The front-end dependencies are those javascript files on which This will install the Node.js development tools and Converse's dependencies.
Converse.js directly depends and which will be loaded in the browser.
To see the dependencies, take a look at whats under the *devDependencies* key in The front-end dependencies are those JavaScript files on which
`package.json <https://github.com/jcbrand/converse.js/blob/master/package.json>`_. Converse directly depends and which will be loaded in the browser as part of
the bundle in ``dist/converse.js`` (or ``dist/converse.min.js``).
To see the 3rd party dependencies (not just the front-end dependencies, but
also ones necessary for development tasks like making builds), take a look at
the list under the ``devDependencies`` in `package.json <https://github.com/jcbrand/converse.js/blob/master/package.json>`_.
.. note:: .. note::
After running ```make dev```, you should now have a new *node_modules* directory After running ```make dev```, you should now have a new *node_modules* directory
which contains all the external dependencies of Converse.js. which contains all the external dependencies of Converse.
If these directory does NOT exist, something must have gone wrong. If this directory does NOT exist, something must have gone wrong.
Double-check the output of ```make dev``` to see if there are any errors Double-check the output of ```make dev``` to see if there are any errors
listed. For support, you can write to the mailing list: conversejs@librelist.com listed. For support, you can ask in our chatroom: `dicuss@conference.conversejs.org <xmpp:discuss@conference.conversejs.org>`_.
Loading converse.js and its dependencies
----------------------------------------
With AMD and require.js (recommended) If you don't have an XMPP client installed, follow this link to
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `conversejs.org <https://conversejs.org/fullscreen#converse/room?jid=discuss@conference.conversejs.org>`_
where you can log in and be taken directly to the chatroom.
Converse.js uses `require.js <http://requirejs.org>`_ to asynchronously load dependencies.
If you want to develop or customize converse.js, you'll want to load the Brief description of Converse's dependencies
non-minified javascript files. ===============================================
Add the following two lines to the *<head>* section of your webpage: Converse relies on the following dependencies:
.. code-block:: html
<link rel="stylesheet" type="text/css" media="screen" href="converse.css">
<script data-main="main" src="node_modules/requirejs/require.js"></script>
require.js will then let the main.js file be parsed (because of the *data-main*
attribute on the *script* tag), which will in turn cause converse.js to be
parsed.
Without AMD and require.js
~~~~~~~~~~~~~~~~~~~~~~~~~~
Converse.js can also be used without require.js. If you for some reason prefer
to use it this way, please refer to
`non_amd.html <https://github.com/jcbrand/converse.js/blob/master/non_amd.html>`_
for an example of how and in what order all the JavaScript files that converse.js
depends on need to be loaded.
Brief description of converse.js's dependencies
-----------------------------------------------
Converse.js relies on the following dependencies:
* `moment.js <http://momentjs.com/>`_ provides a better API for handling dates and times. * `moment.js <http://momentjs.com/>`_ provides a better API for handling dates and times.
* `Strophe.js <http://strophe.im/>`_ maintains the XMPP session, is used to * `Strophe.js <http://strophe.im/>`_ maintains the XMPP session, is used to
...@@ -108,35 +89,30 @@ Converse.js relies on the following dependencies: ...@@ -108,35 +89,30 @@ Converse.js relies on the following dependencies:
* `Backbone <http://backbonejs.org/>`_ is used to model the data as Models and * `Backbone <http://backbonejs.org/>`_ is used to model the data as Models and
Collections and to create Views that render the UI. Collections and to create Views that render the UI.
* `backbone.overview <http://github.com/jcbrand/backbone.overview>`_ provides * `backbone.overview <http://github.com/jcbrand/backbone.overview>`_ provides
Overviews, which are to Views as Backbone Collections are to Models. ``Backbone.Overview``, which is to Views as Backbone Collection is to Models.
* `pluggable.js <https://github.com/jcbrand/pluggable.js>`_ is the plugin It also provides the ``Backbone.OrderedListView`` which is used to show
architecture for Converse.js. It registers and initializes plugins and alphabetically sorted lists, such as your contacts roster.
allows existing attributes, functions and objects on converse.js to be * `backbone.vdomview <http://github.com/jcbrand/backbone.vdomview>`_ provides
``Backbone.VDOMView`` that uses the `Snabbdom <https://github.com/snabbdom/snabbdom>`_
virtual DOM for rendering DOM elements.
* `pluggable.js <https://github.com/jcbrand/pluggable.js>`_ provides the plugin
architecture for Converse. It registers and initializes plugins and
allows existing attributes, functions and objects on Converse to be
overridden inside plugins. overridden inside plugins.
When submitting a pull request Libsignal
------------------------------ ---------
Please follow the usual github workflow. Create your own local fork of this repository,
make your changes and then submit a pull request.
Follow the programming style guide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Please read the `style guide </docs/html/style_guide.html>`_ and make sure that your code follows it.
Add tests for your bugfix or feature Optionally, if you want OMEMO encryption, you need to load `libsignal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ <https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in
Add a test for any bug fixed or feature added. We use Jasmine your page.
for testing.
Take a look at `tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_ For example::
and the `spec files <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
to see how tests are implemented.
Check that the tests pass <script src="3rdparty/libsignal-protocol-javascript/dist/libsignal-protocol.js"></script>
~~~~~~~~~~~~~~~~~~~~~~~~~
Check that all tests complete sucessfully.
Run ``make check`` in your terminal or open `tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_ The reason libsignal needs to be loaded separately is because it's released
in your browser. under the `GPLv3 <https://github.com/signalapp/libsignal-protocol-javascript/blob/master/LICENSE>`_
which requires all other dependent JavaScript code to also be open sourced under the same
license. You might not be willing to adhere to those terms, which is why you
need to decide for yourself whether you're going to load libsignal or not.
docs/source/development.rst
View file @ cb8b5a70
...@@ -8,21 +8,39 @@ ...@@ -8,21 +8,39 @@
Development Development
=========== ===========
Welcome to the developer documentation of Converse. Read the documentation Welcome to the developer documentation of Converse.
linked to below, if you want to add new features or create your own customized
version of Converse. 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.
Converse is a community project and largely volunteer driven.
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.
Converse itself composed of plugins, and exposes an API with which you can
create and register your own plugins. This is the recommended way to customize
or add new functionality to Converse.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
developer_guidelines dependencies
style_guide style_guide
plugin_development plugin_development
api/index api/index
testing
events events
other_frameworks other_frameworks
builds builds
docs/source/events.rst
View file @ cb8b5a70
...@@ -340,7 +340,7 @@ Plugins can listen to this event as cue to register their own global event ...@@ -340,7 +340,7 @@ Plugins can listen to this event as cue to register their own global event
handlers. handlers.
roomsAutoJoined roomsAutoJoined
--------------- ~~~~~~~~~~~~~~~
Emitted once any rooms that have been configured to be automatically joined, Emitted once any rooms that have been configured to be automatically joined,
specified via the _`auto_join_rooms` setting, have been entered. specified via the _`auto_join_rooms` setting, have been entered.
......
docs/source/index.rst
View file @ cb8b5a70
.. Converse.js documentation master file, created by .. Converse documentation master file, created by
sphinx-quickstart on Fri Apr 26 20:48:03 2013. sphinx-quickstart on Fri Apr 26 20:48:03 2013.
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. contain the root `toctree` directive.
...@@ -7,14 +7,14 @@ ...@@ -7,14 +7,14 @@
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/index.rst">Edit me on GitHub</a></div> <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/index.rst">Edit me on GitHub</a></div>
========================= ======================
Converse.js Documentation Converse Documentation
========================= ======================
Preface Preface
======= =======
This is the official documentation for Converse.js. If you'd like to This is the official documentation for Converse. If you'd like to
contribute, please read the :doc:`documentation` page. contribute, please read the :doc:`documentation` page.
You might instead be looking for the `User Manual <manual.html>`_. You might instead be looking for the `User Manual <manual.html>`_.
...@@ -22,7 +22,7 @@ You might instead be looking for the `User Manual <manual.html>`_. ...@@ -22,7 +22,7 @@ You might instead be looking for the `User Manual <manual.html>`_.
Introduction Introduction
============ ============
Converse.js is a free and open-source `XMPP <http://xmpp.org/about-xmpp/>`_ Converse is a free and open-source `XMPP <http://xmpp.org/about-xmpp/>`_
chat client written in JavaScript which can be tightly integrated into any website. chat client written in JavaScript which can be tightly integrated into any website.
The benefit of using converse.js as opposed to relying on a SaaS The benefit of using converse.js as opposed to relying on a SaaS
......
docs/source/quickstart.rst
View file @ cb8b5a70
...@@ -12,7 +12,7 @@ Getting a demo up and running ...@@ -12,7 +12,7 @@ Getting a demo up and running
Use the content delivery network Use the content delivery network
-------------------------------- --------------------------------
Converse.js has a `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_, provided by `KeyCDN <http://keycdn.com/>`_, Converse has a `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_, provided by `KeyCDN <http://keycdn.com/>`_,
which hosts its JavaScript and CSS files. which hosts its JavaScript and CSS files.
The latest versions of these files are available at these URLs: The latest versions of these files are available at these URLs:
...@@ -20,7 +20,10 @@ The latest versions of these files are available at these URLs: ...@@ -20,7 +20,10 @@ The latest versions of these files are available at these URLs:
* https://cdn.conversejs.org/dist/converse.min.js * https://cdn.conversejs.org/dist/converse.min.js
* https://cdn.conversejs.org/css/converse.min.css * https://cdn.conversejs.org/css/converse.min.css
To load a specific version of Converse.js you can put the version in the URL, like so: It's however recommended that you load a specific version of Converse, to avoid
breakage when a new version is released and the above URLs load new resources.
To load a specific version of Converse you can put the version in the URL, like so:
* https://cdn.conversejs.org/4.0.0/dist/converse.min.js * https://cdn.conversejs.org/4.0.0/dist/converse.min.js
* https://cdn.conversejs.org/4.0.0/css/converse.min.css * https://cdn.conversejs.org/4.0.0/css/converse.min.css
...@@ -34,15 +37,15 @@ via the *script* and *link* tags: ...@@ -34,15 +37,15 @@ via the *script* and *link* tags:
<script src="https://cdn.conversejs.org/dist/converse.min.js" charset="utf-8"></script> <script src="https://cdn.conversejs.org/dist/converse.min.js" charset="utf-8"></script>
.. note:: Instead of always loading the latest version of Converse.js via the .. note:: Instead of always loading the latest version of Converse via the
CDN, it's generally better to load a specific version (preferably the CDN, it's generally better to load a specific version (preferably the
latest one), to avoid breakage when new backwards-incompatible versions are latest one), to avoid breakage when new backwards-incompatible versions are
released. released.
Initializing Converse.js Initializing Converse
------------------------ ---------------------
You'll then need to initialize Converse.js with configuration settings relevant to your requirements. You'll then need to initialize Converse with configuration settings relevant to your requirements.
Refer to the :ref:`configuration-settings` section for info on all the available configuration settings. Refer to the :ref:`configuration-settings` section for info on all the available configuration settings.
To quickly get started, you can put the following JavaScript code at the To quickly get started, you can put the following JavaScript code at the
...@@ -56,70 +59,27 @@ bottom of your page (after the closing *</body>* element):: ...@@ -56,70 +59,27 @@ bottom of your page (after the closing *</body>* element)::
</script> </script>
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
Converse.js repository may serve as a nice usable example. Converse repository may serve as a nice usable example.
Alternative builds of Converse.js
=================================
The minified ``.js`` and ``.css`` files provide the same functionality as is available
on the `conversejs.org <https://conversejs.org>`_ website. Useful for testing or demoing.
Converse.js is composed out of plugins, and you are able to exclude certain
plugins (and to include your own new plugins) when creating a build. This
enables you to create your own custom builds of Converse.js that differ from
the standard one.
Besides the standard build, the Converse.js repository includes configuration
for certain other non-standard builds, which we'll now mention below.
Mobile version
--------------
Besides the default build mentioned above, there is a build intended for mobile
websites, called ``converse-mobile.min.js``.
Take a look at the ``mobile.html`` file in the Converse.js repository
for an example of this build being used. There's an additional CSS file called
``mobile.min.css`` which should be used with the mobile build.
When you load `conversejs.org <https://conversejs.org>`_ with a mobile device
then the mobile JavaScript build and its CSS will be used.
Excluding all 3rd party dependencies
------------------------------------
Then there is also a build that contains no 3rd party dependencies, called
``converse-no-dependencies.min.js`` and which is used in the ``non_amd.html``
page in the repository.
Headless build
--------------
There is also the option of making a headless build of converse.js.
This means a build without any UI but still containing core functionality of
maintaining a roster, chatboxes and messages.
The file `src/headless.js <https://github.com/jcbrand/converse.js/blob/master/src/headless.js>`_
is used to determine which plugins are included in the build.
Unfortunately it's currently not yet possible to include Multi-user chat (MUC)
functionality in the headless build. This is because both the UI and core
functionality is still contained in one plugin and would first need to be
split up into two parts, with the UI part dropped for this build.
Fullscreen version Fullscreen version
------------------ ------------------
Converse.js also comes in a fullscreen version. Converse also comes in a fullscreen version.
A hosted version is available online at `inverse.chat <https://inverse.chat>`_. A hosted version is available online at `conversejs.org/fullscreen <https://conversejs.org/fullscreen.html>`_.
Originally this version was available as a separate build file, but Originally this version was available as a separate build file, but
as of version 4.0.0 and higher, the difference between the "overlay" and the as of version 4.0.0 and higher, the difference between the "overlay" and the
"fullscreen" versions of converse.js is simply a matter of configuring the "fullscreen" versions of converse.js is simply a matter of configuring the
:ref:`view_mode`. :ref:`view_mode`.
To generate the headless build, run ``make dist/converse-headless.js`` and/or For example::
``make dist/converse-headless.min.js``.
<script>
converse.initialize({
bosh_service_url: 'https://conversejs.org/http-bind/', // Please use this connection manager only for testing purposes
view_mode: 'fullscreen'
});
</script>
Where to go from here? Where to go from here?
====================== ======================
...@@ -129,10 +89,10 @@ your website, where users authenticate once in your website and are then ...@@ -129,10 +89,10 @@ your website, where users authenticate once in your website and are then
automatically logged in to the XMPP server as well. For more info on how this automatically logged in to the XMPP server as well. For more info on how this
can be achieved, read: :ref:`session-support`. can be achieved, read: :ref:`session-support`.
Perhaps you want to create your own custom build of Converse.js? Then head over Perhaps you want to create your own custom build of Converse? Then head over
to the :doc:`builds` section, or more generally the :doc:`development` to the :doc:`builds` section, or more generally the :doc:`development`
documentation. documentation.
Do you want to know how to theme Converse.js? Then read the :doc:`theming` Do you want to know how to theme Converse? Then read the :doc:`theming`
documentation. documentation.
docs/source/security.rst
View file @ cb8b5a70
...@@ -7,12 +7,12 @@ Security considerations ...@@ -7,12 +7,12 @@ Security considerations
======================= =======================
.. note:: .. note::
Converse.js comes with no warranty of any kind and the authors are not liable for any damages. Converse comes with no warranty of any kind and the authors are not liable for any damages.
The data-structures of Converse.js encapsulate sensitive user data such as The data-structures of Converse encapsulate sensitive user data such as
XMPP account details (in case of manual login) and personal conversations. XMPP account details (in case of manual login) and personal conversations.
In an environment where, besides Converse.js, other untrusted 3rd party scripts In an environment where, besides Converse, other untrusted 3rd party scripts
might also be running, it's important to guard against malicious or invasive might also be running, it's important to guard against malicious or invasive
access to user data and/or the API. access to user data and/or the API.
...@@ -22,18 +22,18 @@ The threat model ...@@ -22,18 +22,18 @@ The threat model
The following threat model is considered: The following threat model is considered:
Malicious 3rd party scripts served through compromised side-channels, such as ad-networks, Malicious 3rd party scripts served through compromised side-channels, such as ad-networks,
which attempt to access Converse.js's API and/or data-structures in order to personify users which attempt to access Converse's API and/or data-structures in order to personify users
or to pilfer their data. or to pilfer their data.
Mitigating measures Mitigating measures
=================== ===================
As of version 3.0.0, the following actions were taken to harden Converse.js against attacks: As of version 3.0.0, the following actions were taken to harden Converse against attacks:
Separate code/data into public and private parts Separate code/data into public and private parts
------------------------------------------------ ------------------------------------------------
1. Encapsulate Converse.js's data structures into a private closured object (named ``_converse``). 1. Encapsulate Converse's data structures into a private closured object (named ``_converse``).
2. Split the API into public and private parts. 2. Split the API into public and private parts.
Restrict access to private code/data Restrict access to private code/data
...@@ -46,7 +46,7 @@ Restrict access to private code/data ...@@ -46,7 +46,7 @@ Restrict access to private code/data
(otherwise the whitelist could be circumvented). (otherwise the whitelist could be circumvented).
.. note:: .. note::
Care should be taken when using a custom build of Converse.js where some Care should be taken when using a custom build of Converse where some
of the core plugins contained in the default build are omitted. In this case of the core plugins contained in the default build are omitted. In this case
the omitted plugins should also be removed from the whitelist, otherwise the omitted plugins should also be removed from the whitelist, otherwise
malicious plugins could be registered under their names. malicious plugins could be registered under their names.
...@@ -81,12 +81,12 @@ soon as the last tab or window is closed. User credentials are not cached at ...@@ -81,12 +81,12 @@ soon as the last tab or window is closed. User credentials are not cached at
all. all.
Perhaps the ability to encrypt this cached data could be added in future Perhaps the ability to encrypt this cached data could be added in future
versions of Converse.js, if there is sufficient demand for it. versions of Converse, if there is sufficient demand for it.
However to date no significant mitigation or hardening measures have been taken to However to date no significant mitigation or hardening measures have been taken to
secure this cached data. secure this cached data.
Therefore, the best defence as website host is to avoid serving Converse.js with Therefore, the best defence as website host is to avoid serving Converse with
untrusted 3rd party code, and the best defence as an end-user is to avoid chatting untrusted 3rd party code, and the best defence as an end-user is to avoid chatting
on websites that host untrusted 3rd party code. The most common examples of such on websites that host untrusted 3rd party code. The most common examples of such
being advertising and analytics scripts. being advertising and analytics scripts.
......
docs/source/setup.rst
View file @ cb8b5a70
...@@ -241,20 +241,20 @@ authenticated BOSH session with the XMPP server or a standalone `BOSH <http://xm ...@@ -241,20 +241,20 @@ authenticated BOSH session with the XMPP server or a standalone `BOSH <http://xm
connection manager. connection manager.
Once authenticated, it receives RID and SID tokens which need to be passed Once authenticated, it receives RID and SID tokens which need to be passed
on to converse.js upon pa. Converse will then attach to that same session using on to Converse. Converse will then attach to that same session using
those tokens. those tokens.
It's called "prebind" because you bind to the BOSH session beforehand, and then It's called "prebind" because you bind to the BOSH session beforehand, and then
later in the page you just attach to that session again. later in the page you just attach to that session again.
The RID and SID tokens can be passed in manually when calling The RID and SID tokens can be passed in manually when calling
`converse.initialize`, but a more convenient way is to pass converse.js a :ref:`prebind_url` `converse.initialize`, but a more convenient way is to pass Converse a :ref:`prebind_url`
which it will call when it needs the tokens. This way it will be able to which it will call when it needs the tokens. This way it will be able to
automatically reconnect whenever the connection drops, by simply calling that automatically reconnect whenever the connection drops, by simply calling that
URL again to fetch new tokens. URL again to fetch new tokens.
Prebinding reduces network traffic and also speeds up the startup time for Prebinding reduces network traffic and also speeds up the startup time for
converse.js. Additionally, because prebind works with tokens, it's not necessary Converse. Additionally, because prebind works with tokens, it's not necessary
for the XMPP client to know or store users' passwords. for the XMPP client to know or store users' passwords.
One potential drawback of using prebind is that in order to establish the One potential drawback of using prebind is that in order to establish the
...@@ -266,11 +266,11 @@ This is however not the case if you for example use LDAP or Active Directory as ...@@ -266,11 +266,11 @@ This is however not the case if you for example use LDAP or Active Directory as
your authentication backend, since you could then configure your XMPP server to your authentication backend, since you could then configure your XMPP server to
use that as well. use that as well.
To prebind you will require a BOSH-enabled XMPP server for converse.js to connect to To prebind you will require a BOSH-enabled XMPP server for Converse to connect to
(see the :ref:`bosh-service-url` under :ref:`configuration-settings`) (see the :ref:`bosh-service-url` under :ref:`configuration-settings`)
as well as a BOSH client in your web application (written for example in as well as a BOSH client in your web application (written for example in
Python, Ruby or PHP) that will set up an authenticated BOSH session, which Python, Ruby or PHP) that will set up an authenticated BOSH session, which
converse.js can then attach to. Converse can then attach to.
.. note:: .. note::
A BOSH server acts as a bridge between HTTP, the protocol of the web, and A BOSH server acts as a bridge between HTTP, the protocol of the web, and
...@@ -297,7 +297,7 @@ page load). Each page load is a new request which requires a new unique RID. ...@@ -297,7 +297,7 @@ page load). Each page load is a new request which requires a new unique RID.
The best way to achieve this is to simply increment the RID with each page The best way to achieve this is to simply increment the RID with each page
load. load.
You'll need to configure converse.js with the ``prebind``, :ref:`keepalive` and You'll need to configure Converse with the ``prebind``, :ref:`keepalive` and
:ref:`prebind_url` settings. :ref:`prebind_url` settings.
Please read the documentation on those settings for a fuller picture of what Please read the documentation on those settings for a fuller picture of what
...@@ -360,4 +360,4 @@ signed with the right key and that they conform to some kind of pre-arranged ...@@ -360,4 +360,4 @@ signed with the right key and that they conform to some kind of pre-arranged
format. format.
In this case, you would also use the :ref:`credentials_url` setting, to specify a In this case, you would also use the :ref:`credentials_url` setting, to specify a
URL from which converse.js should fetch the username and token. URL from which Converse should fetch the username and token.
docs/source/style_guide.rst
View file @ cb8b5a70
...@@ -5,22 +5,13 @@ ...@@ -5,22 +5,13 @@
Software Style Guide Software Style Guide
==================== ====================
.. note:: Converse.js doesn't yet use any of the new `ES2015
<https://babeljs.io/docs/learn-es2015/>`_ features, because we don't
rely on a transpiler and still support older browsers.
Most of the style guide recommendations here come from Douglas Crockford's book Most of the style guide recommendations here come from Douglas Crockford's book
`JavaScript, the good parts <http://shop.oreilly.com/product/9780596517748.do>`_ `JavaScript, the good parts <http://shop.oreilly.com/product/9780596517748.do>`_
This style guide is fairly opinionated. Some of these opinions perhaps don't
conform to your expectations on how JavaScript code should look like.
I apologize for that. However, for the sake of sanity, consistency and having
code that is pleasing to the eye, please stick to these guidelines.
Tabs or spaces? Tabs or spaces?
--------------- ---------------
We always indent 4 spaces. Proper indentation is very important for readability. We always indent 4 spaces. Proper indentation is important for readability.
Underscores or camelCase? Underscores or camelCase?
------------------------- -------------------------
......
docs/source/testing.rst 0 → 100644
View file @ cb8b5a70
Automated tests
===============
Converse uses the `Jasmine <https://jasmine.github.io/>`_ testing framework for
writing tests.
Tests are run in a browser, either manually or automatically via Chrome
headless.
Adding tests for your bugfix or feature
----------------------------------------
Take a look at `tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
and the `spec files <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
to see how tests are implemented.
Running tests
-------------
Check that all tests complete sucessfully.
Run ``make check`` in your terminal.
To run the tests manually, run ``make serve`` and then open `http://localhost:8000/tests <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_ in your browser.
docs/source/theming.rst
View file @ cb8b5a70
...@@ -11,7 +11,7 @@ Theming ...@@ -11,7 +11,7 @@ Theming
Setting up your environment Setting up your environment
=========================== ===========================
In order to theme converse.js, you first need to set up a :ref:`development` environment. In order to theme Converse, you first need to set up a :ref:`development` environment.
You'll also want to preview the changes you make in your browser, for which a You'll also want to preview the changes you make in your browser, for which a
webserver will be useful. webserver will be useful.
...@@ -28,7 +28,7 @@ serve the files for you, simply run:: ...@@ -28,7 +28,7 @@ serve the files for you, simply run::
Windows you can use `Chocolatey <https://chocolatey.org/>`_. Windows you can use `Chocolatey <https://chocolatey.org/>`_.
After running ``make serve`` you can open http://localhost:8000 in your webbrowser you'll After running ``make serve`` you can open http://localhost:8000 in your webbrowser you'll
see the converse.js website. see the Converse website.
However, when developing or changing the theme, you'll want to load all the However, when developing or changing the theme, you'll want to load all the
unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html
...@@ -37,7 +37,7 @@ instead. ...@@ -37,7 +37,7 @@ instead.
Mockups Mockups
======= =======
Converse.js contains some mockups in the ``./mockup`` directory against which you Converse contains some mockups in the ``./mockup`` directory against which you
can preview and tweak your changes. can preview and tweak your changes.
The ``./mockup/index.html`` file contains the most comprehensive mockup, while The ``./mockup/index.html`` file contains the most comprehensive mockup, while
...@@ -46,13 +46,13 @@ the other files focus on particular UI aspects. ...@@ -46,13 +46,13 @@ the other files focus on particular UI aspects.
To see it in your browser, simply open: http://localhost:8000/mockup To see it in your browser, simply open: http://localhost:8000/mockup
Modifying the HTML templates of Converse.js Modifying the HTML templates of Converse
=========================================== ========================================
The HTML markup of converse.js is contained in small ``.html`` files in the The HTML markup of Converse is contained in small ``.html`` files in the
``./src/templates`` directory. ``./src/templates`` directory.
You can modify HTML markup that converse.js generates by modifying these files. You can modify HTML markup that Converse generates by modifying these files.
Modifying the CSS Modifying the CSS
================= =================
...@@ -66,7 +66,7 @@ To generate the CSS you can run:: ...@@ -66,7 +66,7 @@ To generate the CSS you can run::
Creating dist files Creating dist files
=================== ===================
Once you've themed converse.js, you'll want to create new minified distribution Once you've themed Converse, you'll want to create new minified distribution
files of all the JavaScript and CSS. files of all the JavaScript and CSS.
Please refer to the :doc:`builds` section for information on how this is done. Please refer to the :doc:`builds` section for information on how this is done.
......
docs/source/translations.rst
View file @ cb8b5a70
...@@ -6,17 +6,17 @@ ...@@ -6,17 +6,17 @@
Translations Translations
============ ============
Converse.js supports localization of its user interface and date formats. As Converse supports localization of its user interface and date formats. As
of writing, 17 languages are supported. of writing, 17 languages are supported.
The translations of converse.js can be found in the `locale The translations of Converse can be found in the `locale
<https://github.com/jcbrand/converse.js/tree/master/locale>`_ directory. <https://github.com/jcbrand/converse.js/tree/master/locale>`_ directory.
Translations of Converse.js are very welcome. You can add translations either Translations of Converse are very welcome. You can add translations either
manually by editing the ``.po`` files in the above-mentioned ``locale`` manually by editing the ``.po`` files in the above-mentioned ``locale``
directory, or through the web at `weblate <https://hosted.weblate.org/projects/conversejs/#languages>`_. directory, or through the web at `weblate <https://hosted.weblate.org/projects/conversejs/#languages>`_.
As of version 3.3.0, converse.js no longer automatically bundles translations As of version 3.3.0, Converse no longer automatically bundles translations
in its source file and instead fetches only the relevant locale for the current in its source file and instead fetches only the relevant locale for the current
session from a URL as specified by the :ref:`locales-url` setting. session from a URL as specified by the :ref:`locales-url` setting.
...@@ -34,7 +34,7 @@ If you simply want to add a few missing translations, then consider doing it ...@@ -34,7 +34,7 @@ If you simply want to add a few missing translations, then consider doing it
through the web at `weblate <https://hosted.weblate.org/projects/conversejs/#languages>`_. through the web at `weblate <https://hosted.weblate.org/projects/conversejs/#languages>`_.
Some things however cannot be done via weblate and instead have to be done Some things however cannot be done via weblate and instead have to be done
manually in a checkout of the converse.js source repository. manually in a checkout of the Converse source repository.
These tasks are documented below. These tasks are documented below.
...@@ -46,7 +46,7 @@ The gettext `.pot` file located in ...@@ -46,7 +46,7 @@ The gettext `.pot` file located in
is the template containing all translations and from which for each language an individual PO is the template containing all translations and from which for each language an individual PO
file is generated. file is generated.
The `.pot` file contains all translateable strings extracted from converse.js. The `.pot` file contains all translateable strings extracted from Converse.
To make a user-facing string translateable, wrap it in the double underscore helper To make a user-facing string translateable, wrap it in the double underscore helper
function like so: function like so:
...@@ -64,7 +64,7 @@ After adding the string, you'll need to regenerate the POT file: ...@@ -64,7 +64,7 @@ After adding the string, you'll need to regenerate the POT file:
Making translations file for a new language Making translations file for a new language
------------------------------------------- -------------------------------------------
To create a new translations file for a language in which converse.js is not yet To create a new translations file for a language in which Converse is not yet
translated into, do the following translated into, do the following
.. note:: In this example we use Polish (pl), you need to substitute 'pl' to your own language's code. .. note:: In this example we use Polish (pl), you need to substitute 'pl' to your own language's code.
...@@ -108,7 +108,7 @@ Generating a JSON file from a translations file ...@@ -108,7 +108,7 @@ Generating a JSON file from a translations file
----------------------------------------------- -----------------------------------------------
Unfortunately `Jed <http://slexaxton.github.io/Jed>`_, which we use for Unfortunately `Jed <http://slexaxton.github.io/Jed>`_, which we use for
translations in converse.js cannot use the `.po` files directly. We have translations in Converse cannot use the `.po` files directly. We have
to generate from it a file in JSON format and then put that in a `.js` file to generate from it a file in JSON format and then put that in a `.js` file
for the specific language. for the specific language.
......
docs/source/troubleshooting.rst
View file @ cb8b5a70
...@@ -6,16 +6,16 @@ ...@@ -6,16 +6,16 @@
Troubleshooting and debugging Troubleshooting and debugging
============================= =============================
General tips on debugging Converse.js General tips on debugging Converse
===================================== ==================================
When debugging converse.js, always make sure that you pass in ``debug: true`` to When debugging Converse, always make sure that you pass in ``debug: true`` to
the ``converse.initialize`` call. the ``converse.initialize`` call.
Converse.js will then log debug information to the browser's developer console. Converse will then log debug information to the browser's developer console.
Open the developer console and study the data that is logged to it. Open the developer console and study the data that is logged to it.
`Strope.js <http://strophe.im/>`_ the underlying XMPP library which Converse.js `Strope.js <http://strophe.im/>`_ the underlying XMPP library which Converse
uses, swallows errors, so that messaging can continue in cases where uses, swallows errors, so that messaging can continue in cases where
non-critical errors occur. non-critical errors occur.
...@@ -26,88 +26,21 @@ That's why checking the debug output in the browser console is so important. If ...@@ -26,88 +26,21 @@ That's why checking the debug output in the browser console is so important. If
something goes wrong somewhere, the error will be logged there and you'll be something goes wrong somewhere, the error will be logged there and you'll be
able to see it. able to see it.
Additionally, Converse.js will in debug mode also log all XMPP stanzas Additionally, Converse will in debug mode also log all XMPP stanzas
(the XML snippets being sent between it and the server) to the console. (the XML snippets being sent between it and the server) to the console.
This is very useful for debugging issues relating to the XMPP protocol. This is very useful for debugging issues relating to the XMPP protocol.
For example, if a message or presence update doesn't appear, one of the first For example, if a message or presence update doesn't appear, one of the first
things you can do is to set ``debug: true`` and then to check in the console things you can do is to set ``debug: true`` and then to check in the console
whether the relevant XMPP stanzas are actually logged (which would mean that whether the relevant XMPP stanzas are actually logged (which would mean that
they were received by Converse.js). If they're not logged, then the problem is they were received by Converse). If they're not logged, then the problem is
more likely on the XMPP server's end (perhaps a misconfiguration?). If they more likely on the XMPP server's end (perhaps a misconfiguration?). If they
**are** logged, then there might be a bug or misconfiguration in Converse.js. **are** logged, then there might be a bug or misconfiguration in Converse.
Conflicts with other JavaScript libraries
=========================================
Problem:
---------
You are using other JavaScript libraries (like JQuery plugins), and
get errors like these in your browser console::
Uncaught TypeError: Object [object Object] has no method 'xxx' from example.js
Solution:
---------
First, find out which object is referred to by ``Object [object Object]``.
It will probably be the jQuery object ``$`` or perhaps the lodash/underscore object ``_``.
For the purpose of demonstration, I'm going to assume its ``$``, but the same
rules apply if its something else.
The bundled and minified default build of converse.js, ``converse.min.js``
includes within it all of converse.js's dependencies, which include for example *jQuery*.
If you are having conflicts where attributes or methods aren't available
on the jQuery object, you are probably loading ``converse.min.js`` (which
includes jQuery) as well as your own jQuery version separately.
What then happens is that there are two ``$`` objects (one from
converse.js and one from the jQuery version you included manually)
and only one of them has been extended to have the methods or attributes you require.
Which jQuery object you get depends on the order in which you load the libraries.
There are multiple ways to solve this issue.
Firstly, make sure whether you really need to include a separate version of
jQuery. Chances are that you don't. If you can remove the separate
version, your problem should be solved, as long as your libraries are loaded in
the right order.
Either case, whether you need to keep two versions or not, the solution depends
on whether you'll use require.js to manage your libraries or whether you'll
load them manually.
With require.js
~~~~~~~~~~~~~~~
Instead of using ``converse.min.js``, manage all the libraries in your project
(i.e. converse.js and its dependencies plus all other libraries you use) as one
require.js project, making sure everything is loaded in the correct order.
Then, before deployment, you make your own custom minified build that bundles everything
you need.
With <script> tags
~~~~~~~~~~~~~~~~~~
Take a look at `non_amd.html <https://github.com/jcbrand/converse.js/blob/master/non_amd.html>`_
in the converse.js repo.
It shows in which order the libraries must be loaded via ``<script>`` tags. Add
your own libraries, making sure that they are loaded in the correct order (e.g.
jQuery plugins must load after jQuery).
Performance issues with large rosters Performance issues with large rosters
===================================== =====================================
Effort has been made to benchmark and optimize converse.js to work with large Effort has been made to benchmark and optimize Converse to work with large
rosters. rosters.
See for example the benchmarking tests in `spec/profiling.js See for example the benchmarking tests in `spec/profiling.js
...@@ -117,7 +50,7 @@ Chrome <https://developer.chrome.com/devtools/docs/cpu-profiling>`_ to find ...@@ -117,7 +50,7 @@ Chrome <https://developer.chrome.com/devtools/docs/cpu-profiling>`_ to find
bottlenecks in the code. bottlenecks in the code.
However, with large rosters (more than 1000 contacts), rendering in However, with large rosters (more than 1000 contacts), rendering in
converse.js slows down a lot and it may become intolerably slow. Converse slows down a lot and it may become intolerably slow.
One simple trick to improve performance is to set ``show_only_online_users: true``. One simple trick to improve performance is to set ``show_only_online_users: true``.
This will (usually) reduce the amount of contacts that get rendered in the This will (usually) reduce the amount of contacts that get rendered in the
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7