From cb8b5a703939644048f9da5dd72d9287eb498846 Mon Sep 17 00:00:00 2001 From: JC Brand Date: Tue, 18 Sep 2018 10:53:43 +0200 Subject: [PATCH] Update the developer documentation --- docs/source/api/index.rst | 6 +- docs/source/builds.rst | 116 ++++++++++++---------- docs/source/dependencies.rst | 118 ++++++++++++++++++++++ docs/source/developer_guidelines.rst | 142 --------------------------- docs/source/development.rst | 32 ++++-- docs/source/events.rst | 2 +- docs/source/index.rst | 12 +-- docs/source/quickstart.rst | 82 ++++------------ docs/source/security.rst | 18 ++-- docs/source/setup.rst | 14 +-- docs/source/style_guide.rst | 11 +-- docs/source/testing.rst | 24 +++++ docs/source/theming.rst | 16 +-- docs/source/translations.rst | 16 +-- docs/source/troubleshooting.rst | 87 ++-------------- 15 files changed, 307 insertions(+), 389 deletions(-) create mode 100644 docs/source/dependencies.rst delete mode 100644 docs/source/developer_guidelines.rst create mode 100644 docs/source/testing.rst diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index 33b065c8a..f3acd1102 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -2,9 +2,9 @@ -===================== -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. diff --git a/docs/source/builds.rst b/docs/source/builds.rst index 30c5b3054..7dbb489ec 100644 --- a/docs/source/builds.rst +++ b/docs/source/builds.rst @@ -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) `_ -to define modules and their dependencies. +Converse uses `webpack `_ 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 `_. -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 `_ directory. -For this, the `r.js optimizer `_ -is used together with `almond.js `_, 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 `_ 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 `` + +The reason libsignal needs to be loaded separately is because it's released +under the `GPLv3 `_ +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. diff --git a/docs/source/developer_guidelines.rst b/docs/source/developer_guidelines.rst deleted file mode 100644 index 9be897523..000000000 --- a/docs/source/developer_guidelines.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. raw:: html - - - -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 `_ - 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 `_ - 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 `_. - -Also make sure you have ``Git`` installed. `Details `_. - -.. 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 `_. - -.. 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 `_ 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 ** section of your webpage: - -.. code-block:: html - - - - -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 `_ -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 `_ provides a better API for handling dates and times. -* `Strophe.js `_ maintains the XMPP session, is used to - build XMPP stanzas, to send them, and to register handlers for received stanzas. -* `lodash `_ provides very useful utility functions. -* `Backbone `_ is used to model the data as Models and - Collections and to create Views that render the UI. -* `backbone.overview `_ provides - Overviews, which are to Views as Backbone Collections are to Models. -* `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 `_ 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 `_ -and the `spec files `_ -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 `_ -in your browser. diff --git a/docs/source/development.rst b/docs/source/development.rst index 2b6fe4a5e..d0b9e109d 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -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 `_) +which lets you add new features or modify existing functionality without having to touch +the core files (in the `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 `_ +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 `_ +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 diff --git a/docs/source/events.rst b/docs/source/events.rst index 102dc3183..9f80886e6 100644 --- a/docs/source/events.rst +++ b/docs/source/events.rst @@ -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. diff --git a/docs/source/index.rst b/docs/source/index.rst index ad9edbc21..01723fc25 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 @@ -========================= -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 `_. @@ -22,7 +22,7 @@ You might instead be looking for the `User Manual `_. Introduction ============ -Converse.js is a free and open-source `XMPP `_ +Converse is a free and open-source `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 diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index cb7997ea1..611f9b01e 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -12,7 +12,7 @@ Getting a demo up and running Use the content delivery network -------------------------------- -Converse.js has a `CDN `_, provided by `KeyCDN `_, +Converse has a `CDN `_, provided by `KeyCDN `_, 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: -.. 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 ** element):: The `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 `_ 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 `_ 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 `_ -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 `_. +Converse also comes in a fullscreen version. +A hosted version is available online at `conversejs.org/fullscreen `_. 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:: + 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. diff --git a/docs/source/security.rst b/docs/source/security.rst index 807725948..89b1afd4d 100644 --- a/docs/source/security.rst +++ b/docs/source/security.rst @@ -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. diff --git a/docs/source/setup.rst b/docs/source/setup.rst index cd52bdc62..00f150332 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -241,20 +241,20 @@ authenticated BOSH session with the XMPP server or a standalone `BOSH `_ 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 `_ -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? ------------------------- diff --git a/docs/source/testing.rst b/docs/source/testing.rst new file mode 100644 index 000000000..917e84356 --- /dev/null +++ b/docs/source/testing.rst @@ -0,0 +1,24 @@ +Automated tests +=============== + +Converse uses the `Jasmine `_ 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 `_ +and the `spec files `_ +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 `_ in your browser. diff --git a/docs/source/theming.rst b/docs/source/theming.rst index db9e24e2d..ddab51532 100644 --- a/docs/source/theming.rst +++ b/docs/source/theming.rst @@ -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 `_. 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. diff --git a/docs/source/translations.rst b/docs/source/translations.rst index 6a2680d63..32fe87567 100644 --- a/docs/source/translations.rst +++ b/docs/source/translations.rst @@ -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 `_ 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 `_. -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 `_. 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 `_, 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. diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 18c310d10..7c8d2fa95 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -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 `_ the underlying XMPP library which Converse.js +`Strope.js `_ 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