Chapril/xmpp.chapril.org-conversejs
Chapril/xmpp.chapril.org-conversejs
24
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Merge remote-tracking branch 'origin/master'

Browse Source
This commit is contained in:
Weblate 2017-09-03 22:13:04 +02:00
commit 97ccb6c4e8
14 changed files with 186 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/builds.rst
View File

@ -47,7 +47,7 @@ This command does the following:
* Also, the CSS files in the ``./css`` directory will be minified.
The Javascript build files are contained in the ``./dist`` directory:
The JavaScript build files are contained in the ``./dist`` directory:
.. code-block:: bash

10
docs/source/configuration.rst
View File

@ -261,7 +261,7 @@ If ``authentication`` is set to ``anonymous``, then you will also need to provid
server's domain via the `jid`_ setting.
This is a useful setting if you'd like to create a custom login form in your
website. You'll need to write some Javascript to accept that custom form's
website. You'll need to write some JavaScript to accept that custom form's
login credentials, then you can pass those credentials (``jid`` and
``password``) to ``converse.initialize`` to start converse.js and log the user
into their XMPP account.
@ -1341,7 +1341,7 @@ xhr_custom_status
* Default: ``false``
.. note::
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
This option will let converse.js make an AJAX POST with your changed custom chat status to a
remote server.
@ -1350,7 +1350,7 @@ xhr_custom_status_url
---------------------
.. note::
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
* Default: Empty string
@ -1367,7 +1367,7 @@ xhr_user_search
* Default: ``false``
.. note::
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
There are two ways to add users.
@ -1392,7 +1392,7 @@ xhr_user_search_url
-------------------
.. note::
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
* Default: Empty string

6
docs/source/developer_api.rst
View File

@ -50,7 +50,7 @@ Public API methods
==================
Publich API methods are those methods that are accessible on the global
``window.converse`` object. They are public, because any Javascript in the page
``window.converse`` object. They are public, because any JavaScript in the page
can call them. Public methods therefore don't expose any sensitive or closured
data. To do that, you'll need to create a plugin, which has access to the
private API method.
@ -325,7 +325,7 @@ room under the ``with`` key.
The ``start`` and ``end`` parameters are used to query for messages
within a certain timeframe. The passed in date values may either be ISO8601
formatted date strings, or Javascript Date objects.
formatted date strings, or JavaScript Date objects.
.. code-block:: javascript
@ -1070,7 +1070,7 @@ Example:
The **listen** grouping
-----------------------
Converse.js emits events to which you can subscribe from your own Javascript.
Converse.js emits events to which you can subscribe from your own JavaScript.
Concerning events, the following methods are available under the "listen"
grouping:

4
docs/source/developer_guidelines.rst
View File

@ -9,7 +9,7 @@ Developer guidelines
:depth: 2
:local:
If you want to work with the non-minified Javascript and CSS files you'll soon
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.
@ -97,7 +97,7 @@ 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
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

6
docs/source/features.rst
View File

@ -21,7 +21,7 @@ The OTR protocol not only **encrypts your messages**, it provides ways to
**plausible deniability** and **perfect forward secrecy** by generating
new encryption keys for each conversation.
In its current state, Javascript cryptography is fraught with dangers and
In its current state, JavaScript cryptography is fraught with dangers and
challenges that make it impossible to reach the same standard of security that
is available with native "desktop" software.
@ -29,8 +29,8 @@ This is due to its runtime malleability, the way it is "installed" (e.g.
served) and the browser's lack of cryptographic primitives needed to implement
secure crypto.
For harsh but fairly valid criticism of Javascript cryptography, read:
`Javascript Cryptography Considered Harmful <http://www.matasano.com/articles/javascript-cryptography/>`_.
For harsh but fairly valid criticism of JavaScript cryptography, read:
`JavaScript Cryptography Considered Harmful <http://www.matasano.com/articles/javascript-cryptography/>`_.
To get an idea on how this applies to OTR support in Converse.js, please read
`my thoughts on it <https://opkode.com/media/blog/2013/11/11/conversejs-otr-support>`_.

2
docs/source/index.rst
View File

@ -23,7 +23,7 @@ Introduction
============
Converse.js 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.
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
(software-as-a-service) solution, is that your users can have a much more

295
docs/source/plugin_development.rst
View File

@ -14,24 +14,36 @@ Writing a plugin
Introduction
------------
Developers are able to extend and override the objects, functions and the
Backbone models and views that make up converse.js by means of writing plugins.
Converse.js is exposes a plugin architecture which allows developers to modify
and extend its functionality.
Specifically, plugins enable developers to extend and override existing objects,
functions and `Backbone <http://backbonejs.org/>`_ models and views that make up
Converse.js, and also give them the ability to write new models and views.
Various core features of Converse.js, such as
`Message Archive Management <https://xmpp.org/extensions/xep-0313.html>`_ and
`Group chats <https://xmpp.org/extensions/xep-0045.html>`_ are implemented
as plugins, thereby showing their power and flexibility.
Converse.js uses `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_ as
its plugin architecture.
To understand how this plugin architecture works, please read the
To more deeply understand how this plugin architecture works, please read the
`pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
and to understand its inner workins, please refer to the `annotated source code
<https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
Below you'll find an example plugin. Because convers.js is only Javascript,
HTML and CSS (with no backend code required like PHP, Python or Ruby) it runs
fine in JSFiddle.
Playing with a Converse.js plugin in JSFiddle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here's an Fiddle with a plugin that calls `alert` when the plugin gets
initialized and when a message gets rendered: https://jsfiddle.net/4drfaok0/15/
Because Converse.js consists only of JavaScript, HTML and CSS (with no backend
code required like PHP, Python or Ruby) it runs fine in JSFiddle.
Here's an Fiddle with a Converse.js plugin that calls `alert` once it gets
initialized and also when a chat message gets rendered:
https://jsfiddle.net/4drfaok0/15/
Registering a plugin
--------------------
@ -231,148 +243,157 @@ A full example plugin
.. code-block:: javascript
(function (root, factory) {
if (typeof define === 'function' && define.amd) {
// AMD. Register as a module called "myplugin"
define("myplugin", ["converse"], factory);
} else {
// Browser globals. If you're not using a module loader such as require.js,
// then this line below executes. Make sure that your plugin's <script> tag
// appears after the one from converse.js.
factory(converse);
}
}(this, function (converse) {
(function (root, factory) {
if (typeof define === 'function' && define.amd) {
// AMD. Register as a module called "myplugin"
define("<%= name %>", ["converse"], factory);
} else {
// Browser globals. If you're not using a module loader such as require.js,
// then this line below executes. Make sure that your plugin's <script> tag
// appears after the one from converse.js.
factory(converse);
}
}(this, function (converse) {
// Commonly used utilities and variables can be found under the "env"
// namespace of the "converse" global.
var Strophe = converse.env.Strophe,
$iq = converse.env.$iq,
$msg = converse.env.$msg,
$pres = converse.env.$pres,
$build = converse.env.$build,
b64_sha1 = converse.env.b64_sha1;
$ = converse.env.jQuery,
_ = converse.env._,
moment = converse.env.moment;
// Commonly used utilities and variables can be found under the "env"
// namespace of the "converse" global.
var Strophe = converse.env.Strophe,
$iq = converse.env.$iq,
$msg = converse.env.$msg,
$pres = converse.env.$pres,
$build = converse.env.$build,
b64_sha1 = converse.env.b64_sha1;
$ = converse.env.jQuery,
_ = converse.env._,
moment = converse.env.moment;
// The following line registers your plugin.
converse.plugins.add('myplugin', {
// The following line registers your plugin.
converse.plugins.add("<%= name %>", {
initialize: function () {
// Converse.js's plugin mechanism will call the initialize
// method on any plugin (if it exists) as soon as the plugin has
// been loaded.
/* Optional dependencies are other plugins which might be
* overridden or relied upon, and therefore need to be loaded before
* this plugin. They are called "optional" because they might not be
* available, in which case any overrides applicable to them will be
* ignored.
*
* NB: These plugins need to have already been loaded via require.js.
*
* It's possible to make optional dependencies non-optional.
* If the setting "strict_plugin_dependencies" is set to true,
* an error will be raised if the plugin is not found.
*/
'optional_dependencies': [],
var _converse = this._converse;
/* Converse.js's plugin mechanism will call the initialize
* method on any plugin (if it exists) as soon as the plugin has
* been loaded.
*/
'initialize': function () {
/* Inside this method, you have access to the private
* `_converse` object.
*/
var _converse = this._converse;
_converse.log("The <%= name %> plugin is being initialized");
// Inside this method, you have access to the closured
// _converse object, from which you can get any configuration
// options that the user might have passed in via
// converse.initialize. These values are stored in the
// "user_settings" attribute.
/* From the `_converse` object you can get any configuration
* options that the user might have passed in via
* `converse.initialize`. These values are stored in the
* "user_settings" attribute.
*
* You can also specify new configuration settings for this
* plugin, or override the default values of existing
* configuration settings. This is done like so:
*/
_converse.api.settings.update({
'initialize_message': 'Initializing <%= name %>!'
});
// We can also specify new configuration settings for this
// plugin, or override the default values of existing
// configuration settings. This is done like so:
/* The user can then pass in values for the configuration
* settings when `converse.initialize` gets called.
* For example:
*
* converse.initialize({
* "initialize_message": "My plugin has been initialized"
* });
*
* And the configuration setting is then available via the
* `user_settings` attribute:
*/
alert(this._converse.user_settings.initialize_message);
_converse.api.settings.update({
'initialize_message': 'Initialized', // New configuration setting
'auto_subscribe': true, // New default value for an
// existing "core" configuration setting
});
/* Besides `_converse.api.settings.update`, there is also a
* `_converse.api.promises.add` method, which allows you to
* add new promises that your plugin is obligated to fulfill.
*
* This method takes a string or a list of strings which
* represent the promise names:
*
* _converse.api.promises.add('myPromise');
*
* Your plugin should then, when appropriate, resolve the
* promise by calling `_converse.api.emit`, which will also
* emit an event with the same name as the promise.
* For example:
*
* _converse.api.emit('operationCompleted');
*
* Other plugins can then either listen for the event
* `operationCompleted` like so:
*
* _converse.api.listen.on('operationCompleted', function { ... });
*
* or they can wait for the promise to be fulfilled like so:
*
* _converse.api.waitUntil('operationCompleted', function { ... });
*/
},
// The user can then pass in values for the configuration
// settings when `converse.initialize` gets called.
// For example:
//
// converse.initialize({
// "initialize_message": "My plugin has been initialized"
// });
//
// And the configuration setting is then available via the
// `user_settings` attribute:
/* If you want to override some function or a Backbone model or
* view defined elsewhere in converse.js, then you do that under
* the "overrides" namespace.
*/
'overrides': {
/* For example, the private *_converse* object has a
* method "onConnected". You can override that method as follows:
*/
'onConnected': function () {
// Overrides the onConnected method in converse.js
// alert(this._converse.user_settings.initialize_message);
// Top-level functions in "overrides" are bound to the
// inner "_converse" object.
var _converse = this;
// Besides `_converse.api.settings.update`, there is also a
// `_converse.api.promises.add` method, which allows you to
// add new promises that your plugin is obligated to fulfill.
// Your custom code can come here ...
// This method takes a string or a list of strings which
// represent the promise names.
// You can access the original function being overridden
// via the __super__ attribute.
// Make sure to pass on the arguments supplied to this
// function and also to apply the proper "this" object.
_converse.__super__.onConnected.apply(this, arguments);
_converse.api.promises.add('operationCompleted');
// Your custom code can come here ...
},
// Your plugin should then, when appropriate, resolve the
// promise by calling `_converse.api.emit`, which will also
// emit an event with the same name as the promise.
// For example:
// _converse.api.emit('operationCompleted');
//
// Other plugins can then either listen for the event
// `operationCompleted` like so:
// `_converse.api.listen.on('operationCompleted', function { ... });`
//
// or they can wait for the promise to be fulfilled like so:
// `_converse.api.waitUntil('operationCompleted', function { ... });`
},
/* Override converse.js's XMPPStatus Backbone model so that we can override the
* function that sends out the presence stanza.
*/
'XMPPStatus': {
'sendPresence': function (type, status_message, jid) {
// The "_converse" object is available via the __super__
// attribute.
var _converse = this.__super__._converse;
// Optional dependencies are other plugins which might be
// overridden or relied upon, and therefore need to be loaded before
// this plugin. They are called "optional" because they might not be
// available, in which case any overrides applicable to them will be
// ignored.
// Custom code can come here ...
// It's possible however to make optional dependencies non-optional.
// If the setting "strict_plugin_dependencies" is set to true,
// an error will be raised if the plugin is not found.
//
// NB: These plugins need to have already been loaded via require.js.
// You can call the original overridden method, by
// accessing it via the __super__ attribute.
// When calling it, you need to apply the proper
// context as reference by the "this" variable.
this.__super__.sendPresence.apply(this, arguments);
optional_dependencies: [],
overrides: {
// If you want to override some function or a Backbone model or
// view defined elsewhere in converse.js, then you do that under
// this "overrides" namespace.
// For example, the inner protected *_converse* object has a
// method "onConnected". You can override that method as follows:
onConnected: function () {
// Overrides the onConnected method in converse.js
// Top-level functions in "overrides" are bound to the
// inner "_converse" object.
var _converse = this;
// Your custom code comes here.
// ...
// You can access the original function being overridden
// via the __super__ attribute.
// Make sure to pass on the arguments supplied to this
// function and also to apply the proper "this" object.
_converse.__super__.onConnected.apply(this, arguments);
},
XMPPStatus: {
// Override converse.js's XMPPStatus Backbone model so that we can override the
// function that sends out the presence stanza.
sendPresence: function (type, status_message, jid) {
// The "_converse" object is available via the __super__
// attribute.
var _converse = this.__super__._converse;
// Custom code can come here
// ...
// You can call the original overridden method, by
// accessing it via the __super__ attribute.
// When calling it, you need to apply the proper
// context as reference by the "this" variable.
this.__super__.sendPresence.apply(this, arguments);
}
}
}
});
}));
// Custom code can come here ...
}
}
}
});
}));

6
docs/source/quickstart.rst
View File

@ -13,7 +13,7 @@ Use the content delivery network
--------------------------------
Converse.js has a `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_, provided by `KeyCDN <http://keycdn.com/>`_,
which hosts its Javascript and CSS files.
which hosts its JavaScript and CSS files.
The latest versions of these files are available at these URLs:
@ -44,7 +44,7 @@ Initializing Converse.js
You'll then need to initialize Converse.js 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
To quickly get started, you can put the following JavaScript code at the
bottom of your page (after the closing *</body>* element)::
<script>
@ -75,7 +75,7 @@ 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.
then the mobile JavaScript build and its CSS will be used.
Excluding 3rd party dependencies
--------------------------------

2
docs/source/security.rst
View File

@ -57,7 +57,7 @@ Addititional measures
Besides the measures mentioned above, integrators and hosts can also take
further security precautions.
The most effective is to avoid serving untrusted 3rd party Javascript (e.g.
The most effective is to avoid serving untrusted 3rd party JavaScript (e.g.
advertisements and analytics).
Another option is to forego the use of a global ``converse`` object (which

6
docs/source/style_guide.rst
View File

@ -14,10 +14,10 @@ Software Style Guide
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>`_
`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.
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.
@ -103,7 +103,7 @@ and method invocations.
Checking for equality
---------------------
Javascript has a strict ``===`` and less strict ``==`` equality operator. The
JavaScript has a strict ``===`` and less strict ``==`` equality operator. The
stricter equality operator also does type checking. To avoid subtle bugs when
doing comparisons, always use the strict equality check.

2
docs/source/theming.rst
View File

@ -71,7 +71,7 @@ Creating dist files
===================
Once you've themed converse.js, you'll want to create new minified distribution
files of all the Javascript and CSS.
files of all the JavaScript and CSS.
Please refer to the :doc:`builds` section for information on how this is done.

4
docs/source/translations.rst
View File

@ -59,7 +59,7 @@ translated into, do the following
Please make sure to add the following attributes at the top of the file (under
*Content-Transfer-Encoding*). They are required as configuration settings for Jed,
the Javascript translations library that we're using.
the JavaScript translations library that we're using.
.. code-block:: po
@ -90,7 +90,7 @@ The resulting `.po` file is then what gets translated.
-----------------------------------------------------
Generating a Javascript file from a translations file
Generating a JavaScript file from a translations file
-----------------------------------------------------
Unfortunately `Jed <http://slexaxton.github.io/Jed>`_, which we use for

4
docs/source/troubleshooting.rst
View File

@ -42,13 +42,13 @@ 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
Conflicts with other JavaScript libraries
=========================================
Problem:
---------
You are using other Javascript libraries (like JQuery plugins), and
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

2
index.html
View File

@ -12,11 +12,11 @@
<link type="text/css" rel="stylesheet" media="screen" href="css/bootstrap.min.css" />
<link type="text/css" rel="stylesheet" media="screen" href="css/font-awesome.min.css" />
<link type="text/css" rel="stylesheet" media="screen" href="css/theme.min.css" />
<link type="text/css" rel="stylesheet" media="screen" href="css/converse.css" />
<script type="text/javascript" src="analytics.js"></script>
<noscript><p><img src="//stats.opkode.com/piwik.php?idsite=1" style="border:0;" alt="" /></p></noscript>
<script src="src/website.js"></script>
<![if gte IE 11]>
<link type="text/css" rel="stylesheet" media="screen" href="css/converse.css" />
<script src="dist/converse.min.js"></script>
<![endif]>
</head>