Skip to content

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

Update the docs and add section about sound notifications. updates #62

parent 8061171b
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 279 additions and 340 deletions
docs/html/_sources/index.txt
View file @ 83c68696
...@@ -17,16 +17,16 @@ Quickstart (to get a demo up and running) ...@@ -17,16 +17,16 @@ Quickstart (to get a demo up and running)
When you download a specific release of *Converse.js* there will be two minified files inside the zip file. When you download a specific release of *Converse.js* there will be two minified files inside the zip file.
* converse.min.js * builds/converse.min.js
* converse.min.css * css/converse.min.css
You can include these two files inside the *<head>* element of your website via the *script* and *link* You can include these two files inside the *<head>* element of your website via the *script* and *link*
tags: tags:
:: ::
<link rel="stylesheet" type="text/css" media="screen" href="converse.min.css"> <link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
<script src="converse.min.js"></script> <script src="builds/converse.min.js"></script>
You need to initialize Converse.js with configuration settings particular to You need to initialize Converse.js with configuration settings particular to
your requirements. your requirements.
...@@ -34,7 +34,7 @@ your requirements. ...@@ -34,7 +34,7 @@ your requirements.
Please refer to the `Configuration variables`_ section further below for info on Please refer to the `Configuration variables`_ section further below for info on
all the available configuration settings. all the available configuration settings.
To do this, put the following inline Javascript code at the To configure Converse.js, put the following inline Javascript code at the
bottom of your page (after the closing *</body>* element). bottom of your page (after the closing *</body>* element).
:: ::
...@@ -48,12 +48,12 @@ bottom of your page (after the closing *</body>* element). ...@@ -48,12 +48,12 @@ bottom of your page (after the closing *</body>* element).
i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
prebind: false, prebind: false,
show_controlbox_by_default: true, show_controlbox_by_default: true,
xhr_user_search: false roster_groups: true
}); });
}); });
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
Converse.js repository serves as a nice usable example of this. Converse.js repository may serve as a nice usable example.
These minified files provide the same demo-like functionality as is available These minified files provide the same demo-like functionality as is available
on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing, but not very on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing, but not very
...@@ -79,7 +79,7 @@ website, *Converse.js* is not really meant to be a "Software-as-a-service" (SaaS ...@@ -79,7 +79,7 @@ website, *Converse.js* is not really meant to be a "Software-as-a-service" (SaaS
webchat. webchat.
Instead, its goal is to provide the means for website owners to add a tightly Instead, its goal is to provide the means for website owners to add a tightly
integrated instant messaging service to their own sites. integrated instant messaging service to their own websites.
As a website owner, you are expected to host *Converse.js* yourself, and to do some legwork to As a website owner, you are expected to host *Converse.js* yourself, and to do some legwork to
properly configure and integrate it into your site. properly configure and integrate it into your site.
...@@ -114,8 +114,8 @@ You can find a list of public XMPP servers/providers on `xmpp.net`_ and a list o ...@@ -114,8 +114,8 @@ You can find a list of public XMPP servers/providers on `xmpp.net`_ and a list o
servers that you can set up yourself on `xmpp.org`_. servers that you can set up yourself on `xmpp.org`_.
Connection Manager A BOSH Connection Manager
================== =========================
Your website and *Converse.js* use `HTTP`_ as protocol to communicate with Your website and *Converse.js* use `HTTP`_ as protocol to communicate with
the webserver. HTTP connections are stateless and usually shortlived. the webserver. HTTP connections are stateless and usually shortlived.
...@@ -127,18 +127,25 @@ To enable a web application like *Converse.js* to communicate with an XMPP ...@@ -127,18 +127,25 @@ To enable a web application like *Converse.js* to communicate with an XMPP
server, we need a proxy in the middle that can act as a bridge between the two server, we need a proxy in the middle that can act as a bridge between the two
protocols. protocols.
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
This is the job of a connection manager. A connection manager can be either a This is the job of a connection manager. A connection manager can be either a
standalone application or part of an XMPP server. `ejabberd`_ for example, standalone application or part of an XMPP server. Popular XMPP servers such as
includes a connection manager (but you have to enable it). `ejabberd <http://www.ejabberd.im>`_, `prosody <http://prosody.im/doc/setting_up_bosh>`_ and
`openfire <http://www.igniterealtime.org/projects/openfire/>`_ all include their own connection managers
(but you usually have to enable them in the configuration).
Standalone connection managers also exist, see for example `Punjab <https://github.com/twonds/punjab>`_.
The demo on the `Converse.js homepage`_ uses a a connection manager located at https://bind.conversejs.org. The demo on the `Converse.js homepage`_ uses a connection manager located at https://bind.conversejs.org.
This connection manager is for testing purposes only, please don't use it in This connection manager is available for testing purposes only, please don't use it in production.
production.
Overcoming cross-domain request restrictions Overcoming cross-domain request restrictions
-------------------------------------------- --------------------------------------------
The domain of the *Converse.js* demo is *conversejs.org*, but the domain of the connection manager is *opkode.im*. Lets say your domain is *example.org*, but the domain of your connection
manager is *example.com*.
HTTP requests are made by *Converse.js* to the connection manager via XmlHttpRequests (XHR). HTTP requests are made by *Converse.js* to the connection manager via XmlHttpRequests (XHR).
Until recently, it was not possible to make such requests to a different domain Until recently, it was not possible to make such requests to a different domain
than the one currently being served (to prevent XSS attacks). than the one currently being served (to prevent XSS attacks).
...@@ -281,67 +288,6 @@ Example code for server-side prebinding ...@@ -281,67 +288,6 @@ Example code for server-side prebinding
See this `example Django application`_ by Jack Moffitt. See this `example Django application`_ by Jack Moffitt.
Setting up a BOSH server
------------------------
The `Movim <http://movim.eu/>`_ project wiki has a very thorough page on setting up a BOSH server for
a wide variety of standalone or XMPP servers.
http://wiki.movim.eu/manual:bosh_servers
Facebook integration
====================
.. Note ::
It should be possible to integrate Converse.js with Facebook chat, and
below I'll provide some tips and documentation on how to achieve this. That
said, I don't have a Facebook account and therefore haven't tried to do
this myself. Feedback and patches from people who have succesfully done this
will be appreciated.
Converse.js uses `Strophe.js <http://strophe.im/strophejs>`_ to connect and
communicate with the XMPP server. One nice thing about Strophe.js is that it
can be extended via `plugins <http://github.com/strophe/strophejs-plugins>`_.
Here is a `plugin for authenticating with facebook
<https://github.com/kissrobber/turedsocial/blob/master/strophe-plugins/src/facebook.js>`_.
You will need your own BOSH connection manager to act as a proxy between
Converse.js/Strophe.js and Facebook's XMPP server. That is because Facebook's
XMPP server doesn't support BOSH natively.
The BOSH connection manager that I make available for
testing purposes (at https://bind.conversejs.org) uses `Punjab <https://github.com/twonds/punjab>`_,
although there are quite a few other options available as well.
When you configure Converse.js, via its ``initialize`` method, you must specify the
`bosh_service_url`_ value, which is to be your BOSH connection manager.
Please note, to enable Facebook integration, you'll have to
get your hands dirty and modify Converse.js's code, so that it calls the
``facebookConnect`` method of the plugin above.
The plugin above gives the following code example for you to meditate upon:
::
connection = new Strophe.Connection("http://localhost:5280/bosh");
connection.facebookConnect(
"12345@chat.facebook.com",
onConnectFacebook,
300,
1,
'5e64a30272af065bd72258c565a03f2f',
'8147a27e4a7f9b55ffc85c2683f9529a',
FB.getSession().session_key
);
The connection is already created inside Converse.js, so the
``facebookConnect`` method needs to also be called from there.
If someone submits a sane patch that does the above, I'll be happy to merge it.
Until then, people will have to do this themselves.
======== ========
Features Features
======== ========
...@@ -375,6 +321,25 @@ For now, suffice to say that although its useful to have OTR support in ...@@ -375,6 +321,25 @@ For now, suffice to say that although its useful to have OTR support in
Converse.js in order to avoid most eavesdroppers, if you need serious Converse.js in order to avoid most eavesdroppers, if you need serious
communications privacy, then you're much better off using native software. communications privacy, then you're much better off using native software.
Sound Notifications
===================
From version 0.8.1 Converse.js can play a sound notification when you receive a
message.
For more info, please see the `play_sounds`_ configuration setting.
Multilingual Support
====================
Converse.js is translated into multiple languages. The default build,
``converse.min.js``, includes all languages.
Languages increase the size of the Converse.js significantly.
If you only need one, or a subset of the available languages, it's better to
make a custom build which includes only those languages that you need.
=========== ===========
Development Development
=========== ===========
...@@ -982,6 +947,21 @@ i18n ...@@ -982,6 +947,21 @@ i18n
Specify the locale/language. The language must be in the ``locales`` object. Refer to Specify the locale/language. The language must be in the ``locales`` object. Refer to
``./locale/locales.js`` to see which locales are supported. ``./locale/locales.js`` to see which locales are supported.
play_sounds
-----------
Default: ``false``
Inside the ``./sounds`` directory of the Converse.js repo, you'll see MP3 and Ogg
formatted sound files. We need both, because neither format is supported by all browsers.
For now, sound files are looked up by convention, not configuration. So to have
a sound play when a message is received, make sure that your webserver serves
it in both formats as ``http://yoursite.com/sounds/msg_received.mp3`` and
``http://yoursite.com/sounds/msg_received.ogg``.
``http://yoursite.com`` should of course be your site's URL.
prebind prebind
-------- --------
......
docs/html/index.html
View file @ 83c68696
This diff is collapsed.
docs/html/searchindex.js
View file @ 83c68696
This diff is collapsed.
docs/source/index.rst
View file @ 83c68696
...@@ -17,16 +17,16 @@ Quickstart (to get a demo up and running) ...@@ -17,16 +17,16 @@ Quickstart (to get a demo up and running)
When you download a specific release of *Converse.js* there will be two minified files inside the zip file. When you download a specific release of *Converse.js* there will be two minified files inside the zip file.
* converse.min.js * builds/converse.min.js
* converse.min.css * css/converse.min.css
You can include these two files inside the *<head>* element of your website via the *script* and *link* You can include these two files inside the *<head>* element of your website via the *script* and *link*
tags: tags:
:: ::
<link rel="stylesheet" type="text/css" media="screen" href="converse.min.css"> <link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
<script src="converse.min.js"></script> <script src="builds/converse.min.js"></script>
You need to initialize Converse.js with configuration settings particular to You need to initialize Converse.js with configuration settings particular to
your requirements. your requirements.
...@@ -34,7 +34,7 @@ your requirements. ...@@ -34,7 +34,7 @@ your requirements.
Please refer to the `Configuration variables`_ section further below for info on Please refer to the `Configuration variables`_ section further below for info on
all the available configuration settings. all the available configuration settings.
To do this, put the following inline Javascript code at the To configure Converse.js, put the following inline Javascript code at the
bottom of your page (after the closing *</body>* element). bottom of your page (after the closing *</body>* element).
:: ::
...@@ -48,12 +48,12 @@ bottom of your page (after the closing *</body>* element). ...@@ -48,12 +48,12 @@ bottom of your page (after the closing *</body>* element).
i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
prebind: false, prebind: false,
show_controlbox_by_default: true, show_controlbox_by_default: true,
xhr_user_search: false roster_groups: true
}); });
}); });
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
Converse.js repository serves as a nice usable example of this. Converse.js repository may serve as a nice usable example.
These minified files provide the same demo-like functionality as is available These minified files provide the same demo-like functionality as is available
on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing, but not very on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing, but not very
...@@ -79,7 +79,7 @@ website, *Converse.js* is not really meant to be a "Software-as-a-service" (SaaS ...@@ -79,7 +79,7 @@ website, *Converse.js* is not really meant to be a "Software-as-a-service" (SaaS
webchat. webchat.
Instead, its goal is to provide the means for website owners to add a tightly Instead, its goal is to provide the means for website owners to add a tightly
integrated instant messaging service to their own sites. integrated instant messaging service to their own websites.
As a website owner, you are expected to host *Converse.js* yourself, and to do some legwork to As a website owner, you are expected to host *Converse.js* yourself, and to do some legwork to
properly configure and integrate it into your site. properly configure and integrate it into your site.
...@@ -114,8 +114,8 @@ You can find a list of public XMPP servers/providers on `xmpp.net`_ and a list o ...@@ -114,8 +114,8 @@ You can find a list of public XMPP servers/providers on `xmpp.net`_ and a list o
servers that you can set up yourself on `xmpp.org`_. servers that you can set up yourself on `xmpp.org`_.
Connection Manager A BOSH Connection Manager
================== =========================
Your website and *Converse.js* use `HTTP`_ as protocol to communicate with Your website and *Converse.js* use `HTTP`_ as protocol to communicate with
the webserver. HTTP connections are stateless and usually shortlived. the webserver. HTTP connections are stateless and usually shortlived.
...@@ -127,18 +127,25 @@ To enable a web application like *Converse.js* to communicate with an XMPP ...@@ -127,18 +127,25 @@ To enable a web application like *Converse.js* to communicate with an XMPP
server, we need a proxy in the middle that can act as a bridge between the two server, we need a proxy in the middle that can act as a bridge between the two
protocols. protocols.
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
This is the job of a connection manager. A connection manager can be either a This is the job of a connection manager. A connection manager can be either a
standalone application or part of an XMPP server. `ejabberd`_ for example, standalone application or part of an XMPP server. Popular XMPP servers such as
includes a connection manager (but you have to enable it). `ejabberd <http://www.ejabberd.im>`_, `prosody <http://prosody.im/doc/setting_up_bosh>`_ and
`openfire <http://www.igniterealtime.org/projects/openfire/>`_ all include their own connection managers
(but you usually have to enable them in the configuration).
Standalone connection managers also exist, see for example `Punjab <https://github.com/twonds/punjab>`_.
The demo on the `Converse.js homepage`_ uses a a connection manager located at https://bind.conversejs.org. The demo on the `Converse.js homepage`_ uses a connection manager located at https://bind.conversejs.org.
This connection manager is for testing purposes only, please don't use it in This connection manager is available for testing purposes only, please don't use it in production.
production.
Overcoming cross-domain request restrictions Overcoming cross-domain request restrictions
-------------------------------------------- --------------------------------------------
The domain of the *Converse.js* demo is *conversejs.org*, but the domain of the connection manager is *opkode.im*. Lets say your domain is *example.org*, but the domain of your connection
manager is *example.com*.
HTTP requests are made by *Converse.js* to the connection manager via XmlHttpRequests (XHR). HTTP requests are made by *Converse.js* to the connection manager via XmlHttpRequests (XHR).
Until recently, it was not possible to make such requests to a different domain Until recently, it was not possible to make such requests to a different domain
than the one currently being served (to prevent XSS attacks). than the one currently being served (to prevent XSS attacks).
...@@ -281,67 +288,6 @@ Example code for server-side prebinding ...@@ -281,67 +288,6 @@ Example code for server-side prebinding
See this `example Django application`_ by Jack Moffitt. See this `example Django application`_ by Jack Moffitt.
Setting up a BOSH server
------------------------
The `Movim <http://movim.eu/>`_ project wiki has a very thorough page on setting up a BOSH server for
a wide variety of standalone or XMPP servers.
http://wiki.movim.eu/manual:bosh_servers
Facebook integration
====================
.. Note ::
It should be possible to integrate Converse.js with Facebook chat, and
below I'll provide some tips and documentation on how to achieve this. That
said, I don't have a Facebook account and therefore haven't tried to do
this myself. Feedback and patches from people who have succesfully done this
will be appreciated.
Converse.js uses `Strophe.js <http://strophe.im/strophejs>`_ to connect and
communicate with the XMPP server. One nice thing about Strophe.js is that it
can be extended via `plugins <http://github.com/strophe/strophejs-plugins>`_.
Here is a `plugin for authenticating with facebook
<https://github.com/kissrobber/turedsocial/blob/master/strophe-plugins/src/facebook.js>`_.
You will need your own BOSH connection manager to act as a proxy between
Converse.js/Strophe.js and Facebook's XMPP server. That is because Facebook's
XMPP server doesn't support BOSH natively.
The BOSH connection manager that I make available for
testing purposes (at https://bind.conversejs.org) uses `Punjab <https://github.com/twonds/punjab>`_,
although there are quite a few other options available as well.
When you configure Converse.js, via its ``initialize`` method, you must specify the
`bosh_service_url`_ value, which is to be your BOSH connection manager.
Please note, to enable Facebook integration, you'll have to
get your hands dirty and modify Converse.js's code, so that it calls the
``facebookConnect`` method of the plugin above.
The plugin above gives the following code example for you to meditate upon:
::
connection = new Strophe.Connection("http://localhost:5280/bosh");
connection.facebookConnect(
"12345@chat.facebook.com",
onConnectFacebook,
300,
1,
'5e64a30272af065bd72258c565a03f2f',
'8147a27e4a7f9b55ffc85c2683f9529a',
FB.getSession().session_key
);
The connection is already created inside Converse.js, so the
``facebookConnect`` method needs to also be called from there.
If someone submits a sane patch that does the above, I'll be happy to merge it.
Until then, people will have to do this themselves.
======== ========
Features Features
======== ========
...@@ -375,6 +321,25 @@ For now, suffice to say that although its useful to have OTR support in ...@@ -375,6 +321,25 @@ For now, suffice to say that although its useful to have OTR support in
Converse.js in order to avoid most eavesdroppers, if you need serious Converse.js in order to avoid most eavesdroppers, if you need serious
communications privacy, then you're much better off using native software. communications privacy, then you're much better off using native software.
Sound Notifications
===================
From version 0.8.1 Converse.js can play a sound notification when you receive a
message.
For more info, please see the `play_sounds`_ configuration setting.
Multilingual Support
====================
Converse.js is translated into multiple languages. The default build,
``converse.min.js``, includes all languages.
Languages increase the size of the Converse.js significantly.
If you only need one, or a subset of the available languages, it's better to
make a custom build which includes only those languages that you need.
=========== ===========
Development Development
=========== ===========
...@@ -982,6 +947,21 @@ i18n ...@@ -982,6 +947,21 @@ i18n
Specify the locale/language. The language must be in the ``locales`` object. Refer to Specify the locale/language. The language must be in the ``locales`` object. Refer to
``./locale/locales.js`` to see which locales are supported. ``./locale/locales.js`` to see which locales are supported.
play_sounds
-----------
Default: ``false``
Inside the ``./sounds`` directory of the Converse.js repo, you'll see MP3 and Ogg
formatted sound files. We need both, because neither format is supported by all browsers.
For now, sound files are looked up by convention, not configuration. So to have
a sound play when a message is received, make sure that your webserver serves
it in both formats as ``http://yoursite.com/sounds/msg_received.mp3`` and
``http://yoursite.com/sounds/msg_received.ogg``.
``http://yoursite.com`` should of course be your site's URL.
prebind prebind
-------- --------
......
index.html
View file @ 83c68696
...@@ -230,18 +230,16 @@ ...@@ -230,18 +230,16 @@
<script> <script>
require(['converse'], function (converse) { require(['converse'], function (converse) {
converse.initialize({ converse.initialize({
auto_reconnect: false, // Still buggy
allow_otr: true, allow_otr: true,
auto_list_rooms: false, auto_list_rooms: false,
auto_subscribe: false, auto_subscribe: false,
bosh_service_url: 'https://bind.conversejs.org', // Please use this connection manager only for testing purposes bosh_service_url: 'https://bind.conversejs.org', // Please use this connection manager only for testing purposes
debug: true , debug: true,
hide_muc_server: false, hide_muc_server: false,
i18n: locales['en'], // Refer to ./locale/locales.js to see which locales are supported i18n: locales['en'], // Refer to ./locale/locales.js to see which locales are supported
play_sounds: true, play_sounds: true,
prebind: false, prebind: false,
show_controlbox_by_default: true, show_controlbox_by_default: true,
xhr_user_search: false,
roster_groups: true roster_groups: true
}); });
}); });
......
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