Update the developer documentation
This commit is contained in:
JC Brand
parent
c37a1dcbb2
commit
cb8b5a7039
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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``.
|
||||
|
||||
The CSS files are also generated, from the scss files in the
|
||||
`sass <https://github.com/conversejs/converse.js/tree/master/sass>`_ directory.
|
||||
|
||||
Similarly to ``make watchjs``, you can run ``make watch`` to automatically
|
||||
generate the css files in the ``./css/`` directory.
|
||||
|
||||
The Converse repository does not include the minified files in the ``dist`` or
|
||||
``css`` directories. Before deployment, you'll want to generate them yourself.
|
||||
|
||||
To do so, run the following:
|
||||
|
||||
::
|
||||
make dist/converse.min.js
|
||||
make css/converse.min.css
|
||||
|
||||
Alternatively, if you want to generate ALL the bundles files (minified and
|
||||
unminified), then you can also run::
|
||||
|
||||
make dist
|
||||
|
||||
This command does the following:
|
||||
|
||||
* It creates different builds of Converse.js in the ``./dist/`` directory.
|
||||
Creating custom bundles
|
||||
=======================
|
||||
|
||||
* 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.
|
||||
|
||||
* Also, the CSS files in the ``./css`` directory will be minified.
|
||||
|
||||
The JavaScript build files are contained in the ``./dist`` directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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
|
||||
|
||||
.. _`minification`:
|
||||
|
||||
Creating custom builds
|
||||
----------------------
|
||||
|
||||
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.
|
||||
|
||||
To only minify the CSS files, nothing else, run the following command::
|
||||
Excluding all 3rd party dependencies
|
||||
------------------------------------
|
||||
|
||||
make cssmin
|
||||
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.
|
||||
|
||||
The CSS files are minified via `cssmin <https://github.com/gruntjs/grunt-contrib-cssmin>`_.
|
||||
To generate this bundle, you can run:
|
||||
|
||||
::
|
||||
|
||||
make dist/converse-no-dependencies.js
|
||||
make dist/converse-no-dependencies.min.js
|
||||
|
||||
Headless build
|
||||
--------------
|
||||
|
||||
There is also the option of making a headless build of Converse.
|
||||
|
||||
This is a build without any UI code but still containing the core functionality of
|
||||
maintaining a roster, chats 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.
|
||||
|
||||
.. 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.
|
||||
|
|
|
|||
118
docs/source/dependencies.rst
Normal file
118
docs/source/dependencies.rst
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
.. raw:: html
|
||||
|
||||
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
|
||||
|
||||
============
|
||||
Dependencies
|
||||
============
|
||||
|
||||
Installing the 3rd party dependencies
|
||||
=====================================
|
||||
|
||||
.. note::
|
||||
Windows environment: We recommend installing the required tools using `Chocolatey <https://chocolatey.org/>`_
|
||||
You will need Node.js (nodejs.install), Git (git.install) and optionally to build using Makefile, GNU Make (make)
|
||||
If you have trouble setting up a development environment on Windows,
|
||||
please read `this post <http://librelist.com/browser//conversejs/2014/11/5/openfire-converse-and-visual-studio-questions/#b28387e7f8f126693b11598a8acbe810>`_
|
||||
in the mailing list.:
|
||||
|
||||
|
||||
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>`_.
|
||||
|
||||
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>`_.
|
||||
|
||||
Also make sure you have ``Git`` installed. `See here <http://git-scm.com/book/en/Getting-Started-Installing-Git>`_.
|
||||
|
||||
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:
|
||||
|
||||
::
|
||||
|
||||
make -f Makefile.win dev
|
||||
|
||||
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's dependencies.
|
||||
|
||||
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.
|
||||
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 ask in our chatroom: `dicuss@conference.conversejs.org <xmpp:discuss@conference.conversejs.org>`_.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Brief description of Converse's 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
|
||||
build XMPP stanzas, to send them, and to register handlers for received stanzas.
|
||||
* `lodash <https://lodash.com/>`_ provides very useful utility functions.
|
||||
* `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
|
||||
``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.
|
||||
|
||||
Libsignal
|
||||
---------
|
||||
|
||||
Optionally, if you want OMEMO encryption, you need to load `libsignal
|
||||
<https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in
|
||||
your page.
|
||||
|
||||
For example::
|
||||
|
||||
<script src="3rdparty/libsignal-protocol-javascript/dist/libsignal-protocol.js"></script>
|
||||
|
||||
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.
|
||||
|
|
@ -1,142 +0,0 @@
|
|||
.. raw:: html
|
||||
|
||||
<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
|
||||
====================
|
||||
|
||||
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.
|
||||
|
||||
.. note::
|
||||
Windows environment: We recommend installing the required tools using `Chocolatey <https://chocolatey.org/>`_
|
||||
You will need Node.js (nodejs.install), Git (git.install) and optionally to build using Makefile, GNU Make (make)
|
||||
If you have trouble setting up a development environment on Windows,
|
||||
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>`_.
|
||||
|
||||
.. note::
|
||||
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
|
||||
directory:
|
||||
|
||||
::
|
||||
|
||||
make dev
|
||||
|
||||
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:
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
||||
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>`_.
|
||||
|
||||
.. 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.
|
||||
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
|
||||
----------------------------------------
|
||||
|
||||
With AMD and require.js (recommended)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
* `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
|
||||
build XMPP stanzas, to send them, and to register handlers for received stanzas.
|
||||
* `lodash <https://lodash.com/>`_ provides very useful utility functions.
|
||||
* `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
|
||||
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.
|
||||
|
||||
Add tests for your bugfix or feature
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Add a test for any bug fixed or feature added. We use Jasmine
|
||||
for testing.
|
||||
|
||||
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.
|
||||
|
||||
Check that the tests pass
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
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>`_
|
||||
in your browser.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.. 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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?
|
||||
-------------------------
|
||||
|
|
|
|||
24
docs/source/testing.rst
Normal file
24
docs/source/testing.rst
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user