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 @@
<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
to link to the JSDoc output.
......
docs/source/builds.rst
View file @ cb8b5a70
......@@ -5,9 +5,9 @@
.. _builds:
===============
Creating builds
===============
=================
Generating builds
=================
.. contents:: Table of Contents
:depth: 3
......@@ -15,72 +15,65 @@ Creating builds
.. 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``)
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>`_
to define modules and their dependencies.
Converse uses `webpack <https://webpack.js.org/>`_ to create single build files containing the core code and
all of the 3rd party dependencies.
Dependencies can then be loaded on-the-fly with `require.js <http://requirejs.org>`_.
This is very useful during development, but when it comes to
deployement you'll usually want to create a single, minified distribution build.
These files are in the `dist <https://github.com/conversejs/converse.js/tree/master/dist>`_ directory.
For this, the `r.js optimizer <http://requirejs.org/docs/optimization.html>`_
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.
Before you start changing the core code, you can run ``make watchjs`` in your terminal.
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
This command does the following:
The CSS files are also generated, from the scss files in the
`sass <https://github.com/conversejs/converse.js/tree/master/sass>`_ directory.
* 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``.
This file can then be included via the ``<script>`` tag. See for example the ``non_amd.html`` example page.
The Converse repository does not include the minified files in the ``dist`` or
``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/
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
make dist
.. _`minification`:
Creating custom builds
----------------------
Creating custom bundles
=======================
One reason you might want to create your own builds, is because you want to
remove some of the core plugins of converse.js, or perhaps you want to include
One reason you might want to create your own bundles, is because you want to
remove some of the core plugins of Converse, or perhaps you want to include
your own.
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
``/* END: Removable components */``.
In this section is listed all the converse.js plugins that will make up a
build.
In this section is listed the Converse plugins that will make up a bundle.
You could for example decide to disable the ControlBox altogether by removing
the ``converse-controlbox`` plugin.
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
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
``define`` call, near the top of the file. This list specifies the dependencies
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 @@
<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
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.
Installing the 3rd party dependencies
=====================================
.. note::
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
please read `this post <http://librelist.com/browser//conversejs/2014/11/5/openfire-converse-and-visual-studio-questions/#b28387e7f8f126693b11598a8acbe810>`_
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).
If you don't have Node.js installed, you can download and install the latest
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::
Windows users should use Chocolatey as recommended above.
.. note::
Debian & Ubuntu users : apt-get install git npm nodejs-legacy
Also make sure you have ``Git`` installed. `See here <http://git-scm.com/book/en/Getting-Started-Installing-Git>`_.
Once you have *Node.js* and *git* installed, run the following command inside the Converse.js
directory:
Now use ``git`` to check out the Converse repository:
::
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
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
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
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
Converse.js directly depends and which will be loaded in the browser.
This will install the Node.js development tools and Converse's dependencies.
To see the dependencies, take a look at whats under the *devDependencies* key in
`package.json <https://github.com/jcbrand/converse.js/blob/master/package.json>`_.
The front-end dependencies are those JavaScript files on which
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::
After running ```make dev```, you should now have a new *node_modules* directory
which contains all the external dependencies of Converse.js.
If these directory does NOT exist, something must have gone wrong.
which contains all the external dependencies of Converse.
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
listed. For support, you can write to the mailing list: conversejs@librelist.com
Loading converse.js and its dependencies
----------------------------------------
listed. For support, you can ask in our chatroom: `dicuss@conference.conversejs.org <xmpp:discuss@conference.conversejs.org>`_.
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
non-minified javascript files.
Brief description of Converse's dependencies
===============================================
Add the following two lines to the *<head>* section of your webpage:
.. 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:
Converse relies on the following dependencies:
* `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
......@@ -108,35 +89,30 @@ Converse.js relies on the following dependencies:
* `Backbone <http://backbonejs.org/>`_ is used to model the data as Models and
Collections and to create Views that render the UI.
* `backbone.overview <http://github.com/jcbrand/backbone.overview>`_ provides
Overviews, which are to Views as Backbone Collections are to Models.
* `pluggable.js <https://github.com/jcbrand/pluggable.js>`_ is the plugin
architecture for Converse.js. It registers and initializes plugins and
allows existing attributes, functions and objects on converse.js to be
``Backbone.Overview``, which is to Views as Backbone Collection is to Models.
It also provides the ``Backbone.OrderedListView`` which is used to show
alphabetically sorted lists, such as your contacts roster.
* `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.
When submitting a pull request
------------------------------
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.
Libsignal
---------
Add tests for your bugfix or feature
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Add a test for any bug fixed or feature added. We use Jasmine
for testing.
Optionally, if you want OMEMO encryption, you need to load `libsignal
<https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in
your page.
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.
For example::
Check that the tests pass
~~~~~~~~~~~~~~~~~~~~~~~~~
Check that all tests complete sucessfully.
<script src="3rdparty/libsignal-protocol-javascript/dist/libsignal-protocol.js"></script>
Run ``make check`` in your terminal or open `tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
in your browser.
The reason libsignal needs to be loaded separately is because it's released
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 @@
Development
===========
Welcome to the developer documentation of Converse. Read the documentation
linked to below, if you want to add new features or create your own customized
version of Converse.
Welcome to the developer documentation 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::
:maxdepth: 2
developer_guidelines
dependencies
style_guide
plugin_development
api/index
testing
events
other_frameworks
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
handlers.
roomsAutoJoined
---------------
~~~~~~~~~~~~~~~
Emitted once any rooms that have been configured to be automatically joined,
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.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
......@@ -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>
=========================
Converse.js Documentation
=========================
======================
Converse Documentation
======================
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.
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
============
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.
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
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.
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/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/css/converse.min.css
......@@ -34,15 +37,15 @@ via the *script* and *link* tags:
<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
latest one), to avoid breakage when new backwards-incompatible versions are
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.
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)::
</script>
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.
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.
Converse repository may serve as a nice usable example.
Fullscreen version
------------------
Converse.js also comes in a fullscreen version.
A hosted version is available online at `inverse.chat <https://inverse.chat>`_.
Converse also comes in a fullscreen version.
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
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
:ref:`view_mode`.
To generate the headless build, run ``make dist/converse-headless.js`` and/or
``make dist/converse-headless.min.js``.
For example::
<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?
======================
......@@ -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
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`
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.
docs/source/security.rst
View file @ cb8b5a70
......@@ -7,12 +7,12 @@ Security considerations
=======================
.. 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.
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
access to user data and/or the API.
......@@ -22,18 +22,18 @@ The threat model
The following threat model is considered:
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.
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
------------------------------------------------
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.
Restrict access to private code/data
......@@ -46,7 +46,7 @@ Restrict access to private code/data
(otherwise the whitelist could be circumvented).
.. 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
the omitted plugins should also be removed from the whitelist, otherwise
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
all.
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
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
on websites that host untrusted 3rd party code. The most common examples of such
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
connection manager.
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.
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.
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
automatically reconnect whenever the connection drops, by simply calling that
URL again to fetch new tokens.
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.
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
your authentication backend, since you could then configure your XMPP server to
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`)
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
converse.js can then attach to.
Converse can then attach to.
.. note::
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.
The best way to achieve this is to simply increment the RID with each page
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.
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
format.
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 @@
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
`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?
---------------
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?
-------------------------
......
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
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
webserver will be useful.
......@@ -28,7 +28,7 @@ serve the files for you, simply run::
Windows you can use `Chocolatey <https://chocolatey.org/>`_.
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
unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html
......@@ -37,7 +37,7 @@ instead.
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.
The ``./mockup/index.html`` file contains the most comprehensive mockup, while
......@@ -46,13 +46,13 @@ the other files focus on particular UI aspects.
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.
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
=================
......@@ -66,7 +66,7 @@ To generate the CSS you can run::
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.
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 @@
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.
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.
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``
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
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
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
manually in a checkout of the converse.js source repository.
manually in a checkout of the Converse source repository.
These tasks are documented below.
......@@ -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
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
function like so:
......@@ -64,7 +64,7 @@ After adding the string, you'll need to regenerate the POT file:
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
.. 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
-----------------------------------------------
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
for the specific language.
......
docs/source/troubleshooting.rst
View file @ cb8b5a70
......@@ -6,16 +6,16 @@
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.
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.
`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
non-critical errors occur.
......@@ -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
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.
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
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
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
**are** logged, then there might be a bug or misconfiguration in Converse.js.
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).
**are** logged, then there might be a bug or misconfiguration in Converse.
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.
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
bottlenecks in the code.
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``.
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