plugin_development.rst 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395
  1. .. raw:: html
  2. <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
  3. .. _`writing-a-plugin`:
  4. Writing a plugin
  5. ================
  6. Introduction
  7. ------------
  8. Converse.js is exposes a plugin architecture which allows developers to modify
  9. and extend its functionality.
  10. Specifically, plugins enable developers to extend and override existing objects,
  11. functions and `Backbone <http://backbonejs.org/>`_ models and views that make up
  12. Converse.js, and also give them the ability to write new models and views.
  13. Various core features of Converse.js, such as
  14. `Message Archive Management <https://xmpp.org/extensions/xep-0313.html>`_ and
  15. `Group chats <https://xmpp.org/extensions/xep-0045.html>`_ are implemented
  16. as plugins, thereby showing their power and flexibility.
  17. Converse.js uses `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_ as
  18. its plugin architecture.
  19. To more deeply understand how this plugin architecture works, please read the
  20. `pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
  21. and to understand its inner workins, please refer to the `annotated source code
  22. <https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
  23. Playing with a Converse.js plugin in JSFiddle
  24. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  25. Because Converse.js consists only of JavaScript, HTML and CSS (with no backend
  26. code required like PHP, Python or Ruby) it runs fine in JSFiddle.
  27. Here's an Fiddle with a Converse.js plugin that calls `alert` once it gets
  28. initialized and also when a chat message gets rendered:
  29. https://jsfiddle.net/4drfaok0/15/
  30. Registering a plugin
  31. --------------------
  32. You register a converse.js plugin as follows:
  33. .. code-block:: javascript
  34. converse.plugins.add('myplugin', {
  35. initialize: function () {
  36. // This method gets called once converse.initialize has been called
  37. // and the plugin itself has been loaded.
  38. // Inside this method, you have access to the closured
  39. // _converse object as an attribute on "this".
  40. // E.g. this._converse
  41. },
  42. });
  43. .. note:: It's important that `converse.plugins.add` is called **before**
  44. `converse.initialize` is called. Otherwise the plugin will never get
  45. registered and never get called.
  46. Whitelisting of plugins
  47. -----------------------
  48. As of converse.js 3.0.0 and higher, plugins need to be whitelisted before they
  49. can be used. This is because plugins have access to a powerful API. For
  50. example, they can read all messages and send messages on the user's behalf.
  51. To avoid malicious plugins being registered (i.e. by malware infected
  52. advertising networks) we now require whitelisting.
  53. To whitelist a plugin simply means to specify :ref:`whitelisted_plugins` when
  54. you call ``converse.initialize``.
  55. Security and access to the inner workings
  56. -----------------------------------------
  57. The globally available ``converse`` object, which exposes the API methods, such
  58. as ``initialize`` and ``plugins.add``, is a wrapper that encloses and protects
  59. a sensitive inner object, named ``_converse`` (not the underscore prefix).
  60. This inner ``_converse`` object contains all the Backbone models and views,
  61. as well as various other attributes and functions.
  62. Within a plugin, you will have access to this internal
  63. `"closured" <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures>`_
  64. ``_converse`` object, which is normally not exposed in the global variable scope.
  65. The inner ``_converse`` object is made private in order to safely hide and
  66. encapsulate sensitive information and methods which should not be exposed
  67. to any 3rd-party scripts that might be running in the same page.
  68. Loading a plugin module
  69. -----------------------
  70. Converse.js uses the UMD (Universal Modules Definition) as its module syntax.
  71. This makes modules loadable via `require.js`, `webpack` or other module
  72. loaders, but also includable as old-school `<script>` tags in your HTML.
  73. Here's an example of the plugin shown above wrapped inside a UMD module:
  74. .. code-block:: javascript
  75. (function (root, factory) {
  76. if (typeof define === 'function' && define.amd) {
  77. // AMD. Register as a module called "myplugin"
  78. define("myplugin", ["converse"], factory);
  79. } else {
  80. // Browser globals. If you're not using a module loader such as require.js,
  81. // then this line below executes. Make sure that your plugin's <script> tag
  82. // appears after the one from converse.js.
  83. factory(converse);
  84. }
  85. }(this, function (converse) {
  86. converse.plugins.add('myplugin', {
  87. initialize: function () {
  88. // This method gets called once converse.initialize has been called
  89. // and the plugin itself has been loaded.
  90. // Inside this method, you have access to the closured
  91. // _converse object as an attribute on "this".
  92. // E.g. this._converse
  93. },
  94. });
  95. });
  96. Accessing 3rd party libraries
  97. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98. Immediately inside the module shown above you can access 3rd party libraries (such
  99. moment, underscore and jQuery) via the ``converse.env`` map.
  100. The code for it would look something like this:
  101. .. code-block:: javascript
  102. // Commonly used utilities and variables can be found under the "env"
  103. // namespace of the "converse" global.
  104. var Strophe = converse.env.Strophe,
  105. $iq = converse.env.$iq,
  106. $msg = converse.env.$msg,
  107. $pres = converse.env.$pres,
  108. $build = converse.env.$build,
  109. b64_sha1 = converse.env.b64_sha1;
  110. $ = converse.env.jQuery,
  111. _ = converse.env._,
  112. moment = converse.env.moment;
  113. These dependencies are closured so that they don't pollute the global
  114. namespace, that's why you need to access them in such a way inside the module.
  115. Overrides
  116. ---------
  117. Plugins can override core code or code from other plugins. Refer to the full
  118. example at the bottom for code details.
  119. Use the ``overrides`` functionality with caution. It basically resorts to
  120. monkey patching which pollutes the call stack and can make your code fragile
  121. and prone to bugs when Converse.js gets updated. Too much use of ``overrides``
  122. is therefore a "code smell" which should ideally be avoided.
  123. A better approach is to listen to the events emitted by Converse.js, and to add
  124. your code in event handlers. This is however not always possible, in which case
  125. the overrides are a powerful tool.
  126. .. _`optional_dependencies`:
  127. Optional plugin dependencies
  128. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  129. When using ``overrides``, the code that you want to override (which is either
  130. in ``converse-core`` or in other plugins), needs to be loaded already by the
  131. type the ``overrides`` object is being parsed.
  132. So it's important to include overridden plugins in the AMD ``define`` statement
  133. at the top of the plugin module.
  134. However, sometimes you want to override parts of another plugin if it exists, but you
  135. don't want anything to break if it doesn't exist (for example when using a
  136. custom build which excludes that plugin). An example is the
  137. `converse-dragresize <https://github.com/jcbrand/converse.js/blob/master/src/converse-dragresize.js>`_
  138. plugin, which will add drag-resize handles to the headlines box (which shows
  139. messages of type ``headline``) but doesn't care if that particular plugin isn't
  140. actually loaded.
  141. In this case, you can't specify the plugin as a dependency in the ``define``
  142. statement at the top of the plugin, since it might not always be available,
  143. which would cause ``require.js`` to throw an error.
  144. To resolve this problem we have the ``optional_dependencies`` Array attribute.
  145. With this you can specify those dependencies which need to be loaded before
  146. your plugin, if they exist. If they don't exist, they won't be ignored.
  147. If the setting :ref:`strict_plugin_dependencies` is set to true,
  148. an error will be raised if the plugin is not found, thereby making them
  149. non-optional.
  150. Extending converse.js's configuration settings
  151. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  152. Converse.js comes with various :ref:`configuration-settings`_ that can be used to
  153. modify its functionality and behavior.
  154. All configuration settings have default values which can be overridden when
  155. `converse.initialize` (see :ref:`initialize`_) gets called.
  156. Plugins often need their own additional configuration settings and you can add
  157. these settings with the `_converse.api.settings.update` method (see
  158. :ref:`settings-update`_).
  159. Exposing promises
  160. ~~~~~~~~~~~~~~~~~
  161. Converse.js has a ``waitUntil`` API method (see :ref:`waituntil-grouping`_)
  162. which allows you to wait for various promises to resolve before executing a
  163. piece of code.
  164. You can add new promises for your plugin by calling
  165. ``_converse.api.promises.add`` (see :ref:`promises-grouping`_).
  166. Generally, your plugin will then also be responsible for making sure these
  167. promises are resolved. You do this by calling ``_converse.api.emit``, which not
  168. only resolves the plugin but will also emit an event with the same name.
  169. A full example plugin
  170. ---------------------
  171. .. code-block:: javascript
  172. (function (root, factory) {
  173. if (typeof define === 'function' && define.amd) {
  174. // AMD. Register as a module called "myplugin"
  175. define("<%= name %>", ["converse"], factory);
  176. } else {
  177. // Browser globals. If you're not using a module loader such as require.js,
  178. // then this line below executes. Make sure that your plugin's <script> tag
  179. // appears after the one from converse.js.
  180. factory(converse);
  181. }
  182. }(this, function (converse) {
  183. // Commonly used utilities and variables can be found under the "env"
  184. // namespace of the "converse" global.
  185. var Strophe = converse.env.Strophe,
  186. $iq = converse.env.$iq,
  187. $msg = converse.env.$msg,
  188. $pres = converse.env.$pres,
  189. $build = converse.env.$build,
  190. b64_sha1 = converse.env.b64_sha1;
  191. $ = converse.env.jQuery,
  192. _ = converse.env._,
  193. moment = converse.env.moment;
  194. // The following line registers your plugin.
  195. converse.plugins.add("<%= name %>", {
  196. /* Optional dependencies are other plugins which might be
  197. * overridden or relied upon, and therefore need to be loaded before
  198. * this plugin. They are called "optional" because they might not be
  199. * available, in which case any overrides applicable to them will be
  200. * ignored.
  201. *
  202. * NB: These plugins need to have already been loaded via require.js.
  203. *
  204. * It's possible to make optional dependencies non-optional.
  205. * If the setting "strict_plugin_dependencies" is set to true,
  206. * an error will be raised if the plugin is not found.
  207. */
  208. 'optional_dependencies': [],
  209. /* Converse.js's plugin mechanism will call the initialize
  210. * method on any plugin (if it exists) as soon as the plugin has
  211. * been loaded.
  212. */
  213. 'initialize': function () {
  214. /* Inside this method, you have access to the private
  215. * `_converse` object.
  216. */
  217. var _converse = this._converse;
  218. _converse.log("The <%= name %> plugin is being initialized");
  219. /* From the `_converse` object you can get any configuration
  220. * options that the user might have passed in via
  221. * `converse.initialize`. These values are stored in the
  222. * "user_settings" attribute.
  223. *
  224. * You can also specify new configuration settings for this
  225. * plugin, or override the default values of existing
  226. * configuration settings. This is done like so:
  227. */
  228. _converse.api.settings.update({
  229. 'initialize_message': 'Initializing <%= name %>!'
  230. });
  231. /* The user can then pass in values for the configuration
  232. * settings when `converse.initialize` gets called.
  233. * For example:
  234. *
  235. * converse.initialize({
  236. * "initialize_message": "My plugin has been initialized"
  237. * });
  238. *
  239. * And the configuration setting is then available via the
  240. * `user_settings` attribute:
  241. */
  242. alert(this._converse.user_settings.initialize_message);
  243. /* Besides `_converse.api.settings.update`, there is also a
  244. * `_converse.api.promises.add` method, which allows you to
  245. * add new promises that your plugin is obligated to fulfill.
  246. *
  247. * This method takes a string or a list of strings which
  248. * represent the promise names:
  249. *
  250. * _converse.api.promises.add('myPromise');
  251. *
  252. * Your plugin should then, when appropriate, resolve the
  253. * promise by calling `_converse.api.emit`, which will also
  254. * emit an event with the same name as the promise.
  255. * For example:
  256. *
  257. * _converse.api.emit('operationCompleted');
  258. *
  259. * Other plugins can then either listen for the event
  260. * `operationCompleted` like so:
  261. *
  262. * _converse.api.listen.on('operationCompleted', function { ... });
  263. *
  264. * or they can wait for the promise to be fulfilled like so:
  265. *
  266. * _converse.api.waitUntil('operationCompleted', function { ... });
  267. */
  268. },
  269. /* If you want to override some function or a Backbone model or
  270. * view defined elsewhere in converse.js, then you do that under
  271. * the "overrides" namespace.
  272. */
  273. 'overrides': {
  274. /* For example, the private *_converse* object has a
  275. * method "onConnected". You can override that method as follows:
  276. */
  277. 'onConnected': function () {
  278. // Overrides the onConnected method in converse.js
  279. // Top-level functions in "overrides" are bound to the
  280. // inner "_converse" object.
  281. var _converse = this;
  282. // Your custom code can come here ...
  283. // You can access the original function being overridden
  284. // via the __super__ attribute.
  285. // Make sure to pass on the arguments supplied to this
  286. // function and also to apply the proper "this" object.
  287. _converse.__super__.onConnected.apply(this, arguments);
  288. // Your custom code can come here ...
  289. },
  290. /* Override converse.js's XMPPStatus Backbone model so that we can override the
  291. * function that sends out the presence stanza.
  292. */
  293. 'XMPPStatus': {
  294. 'sendPresence': function (type, status_message, jid) {
  295. // The "_converse" object is available via the __super__
  296. // attribute.
  297. var _converse = this.__super__._converse;
  298. // Custom code can come here ...
  299. // You can call the original overridden method, by
  300. // accessing it via the __super__ attribute.
  301. // When calling it, you need to apply the proper
  302. // context as reference by the "this" variable.
  303. this.__super__.sendPresence.apply(this, arguments);
  304. // Custom code can come here ...
  305. }
  306. }
  307. }
  308. });
  309. }));