187 lines
6.7 KiB
ReStructuredText
187 lines
6.7 KiB
ReStructuredText
.. raw:: html
|
|
|
|
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/manual.rst">Edit me on GitHub</a></div>
|
|
|
|
===========================
|
|
The Converse.js User Manual
|
|
===========================
|
|
|
|
.. |br| raw:: html
|
|
|
|
<br />
|
|
|
|
.. figure:: images/homepage.jpg
|
|
:align: right
|
|
:alt: The converse.js website
|
|
|
|
The converse.js website
|
|
|
|
**Welcome to the converse.js user manual**. This manual is very much still a work
|
|
in progress and is far from complete. Please bear in mind that it's the work of volunteers.
|
|
|
|
If you have requests or suggestions on how the manual can be improved or
|
|
expanded, then please `contact me <https://opkode.com/contact.html>`_
|
|
or create a new ticket on `Github <https://github.com/jcbrand/converse.js/issues>`_.
|
|
|
|
Although converse.js can be integrated into any website, for this user manual
|
|
we'll refer to the canonical version at https://conversejs.org.
|
|
|
|
This documentation also integrates the converse.js chat client, so you can try
|
|
out some of the steps right on this page! Just click the **Toggle chat** button
|
|
at the bottom right of the page to open the so-called *control box* of the
|
|
converse.js chat client.
|
|
|
|
Registering a new chat account
|
|
==============================
|
|
|
|
.. figure:: images/register-panel.jpg
|
|
:align: left
|
|
:alt: The registration panel of the converse.js control box.
|
|
|
|
The registration panel of converse.js
|
|
|
|
With converse.js you can register a new XMPP account on any publically available XMPP provider.
|
|
To do so, click the **Register** tab on the chat client.
|
|
|
|
You will then see the *registration panel* as shown in the picture below.
|
|
|
|
Choosing your provider
|
|
----------------------
|
|
|
|
Converse.js uses a chat protocol called XMPP (also known as Jabber) which allows "federation".
|
|
This means that it's similar to email, in the sense that people signed in at
|
|
different XMPP chat providers can still chat with one another.
|
|
|
|
For example, if you have a Yahoo! email account, you can send and receive emails from
|
|
a friend with a Google email account. In the same way, if you have a chat
|
|
account from **Conversejs.org**, you can send and receive chat messages with a
|
|
friend who has an account at `Jappix.com <https://jappix.com>`_.
|
|
|
|
There are many free providers online which allow you to register a new account.
|
|
You can see a list of some of them at `xmpp.net <https://xmpp.net/directory.php>`_.
|
|
The `xmpp.net <https://xmpp.net/directory.php>`_ website provides a security grading
|
|
for the XMPP servers of the providers, which is very useful. They are however sometimes
|
|
slow to add new servers to the list.
|
|
A larger list of XMPP providers is also available at `list.jabber.net <https://list.jabber.at/>`_.
|
|
|
|
You can find the domain name for a server under the *Domain* column at
|
|
`xmpp.net <https://xmpp.net/directory.php>`_. or the *Server* column at
|
|
`list.jabber.net <https://list.jabber.at/>`_.
|
|
|
|
Once you know which XMPP provider you'd like to use, you can type its domain
|
|
name and click the **Fetch registration form** button.
|
|
|
|
|br|
|
|
|
|
.. figure:: images/register-form.jpg
|
|
:align: left
|
|
:alt: The registration form for an XMPP account at conversejs.org
|
|
|
|
The registration form
|
|
|
|
|
|
Filling out the registration form
|
|
---------------------------------
|
|
|
|
After you've clicked **Fetch registration form**, the chat client will contact
|
|
the chat provider, ask for its registration form and then present it to you.
|
|
|
|
Different chat providers have different registration forms, but they're all
|
|
relatively similar.
|
|
|
|
Check the security score
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
At the top of the form you'll see a colored bar containing the text **xmpp.net score**.
|
|
This shows the security score for this server as determined by `xmpp.net <https://xmpp.net>`_
|
|
where you can test out a server for yourself. You should generally avoid providers with
|
|
a poor security score (colored in red).
|
|
|
|
Choosing a username
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
As you can see in the registration form, the **username** consists of two
|
|
parts separated with an **@** sign, similar to an email address.
|
|
|
|
The first part is your unique *handle* which you need to choose. The second part
|
|
is the domain name of the chat provider, the one which you chose in the previous step
|
|
when you fetched the registration form.
|
|
|
|
When you want to give someone your XMPP chat username, or when you want to add
|
|
someone else as a contact, you need to specify it in full, like you would an email address.
|
|
|
|
Once you've chosen your user name and password, click **Register**. If
|
|
Successful, you'll be automatically logged in to your new account.
|
|
|
|
|br|
|
|
|
|
.. figure:: images/add-contact.png
|
|
:align: left
|
|
:alt: Adding a contact in converse.js
|
|
|
|
The form for adding a new contact
|
|
|
|
|
|
Adding a contact
|
|
================
|
|
|
|
In order to start chatting with someone, you first need to add them as a contact.
|
|
|
|
To do this, click the **Add a contact** link in the **Contacts** tab. This will
|
|
slide open a dropdown in which you can type the username of the person you'd
|
|
like to add.
|
|
|
|
Remember, an XMPP username (also called a JID or Jabber ID) is similar to an
|
|
email address, in that you have both the user's *handle* and the *domain name*
|
|
of the provider, separated with an **@** sign.
|
|
|
|
Once you've typed the username and clicked submit, your request will be sent to
|
|
this person. If they are online, they will immediately be notified of your
|
|
request, otherwise they'll see it next time they come online.
|
|
|
|
Technically, when you add someone as a contact, you're doing two things. Firstly,
|
|
you are adding the contact to your *roster* (think of it as an address book) and secondly
|
|
you are asking to be notified whenever that person comes online.
|
|
|
|
.. figure:: images/pending-contact.jpg
|
|
:align: left
|
|
:alt: A pending contact
|
|
|
|
A pending contact
|
|
|
|
A pending contact
|
|
-----------------
|
|
|
|
The person you are adding as a contact has the option to either accept or decline your request.
|
|
Until that decision has been made, they will appear in your roster as a
|
|
so-called *pending* contact. In other words, their final status is pending on whether
|
|
they accept or decline your request.
|
|
|
|
.. figure:: images/ungrouped-contact.png
|
|
:align: right
|
|
:alt: A normal, ungrouped contact
|
|
|
|
A normal contact
|
|
|
|
A normal contact
|
|
----------------
|
|
|
|
If the person accepts your contact request, they will get a *chat status
|
|
indicator* in your roster and will also become clickable. Clicking on the name
|
|
of the user will open a chat box in which you can then start chatting with that
|
|
user.
|
|
|
|
.. figure:: images/remove-contact.png
|
|
:align: left
|
|
:alt: Removing a contact
|
|
|
|
Removing a contact
|
|
|
|
Removing a contact
|
|
==================
|
|
|
|
To remove a contact, hover your mouse over their name and then click on the
|
|
trash icon. You will be prompted to confirm, and if you do, the contact will no
|
|
longer be visible in your roster.
|
|
|