Update docs to mention desktop notifications. updates #443

docs/source/configuration.rst

@@ -574,6 +574,8 @@ formatted sound files. We need both, because neither format is supported by all
 You can set the URL where the sound files are hosted with the `sounds_path`_
 option.
 
+Requires the `src/converse-notification.js` plugin.
+
 .. _`prebind_url`:
 
 prebind_url
@@ -639,6 +641,18 @@ However, be aware that even if this value is set to ``false``, if the
 controlbox is open, and the page is reloaded, then it will stay open on the new
 page as well.
 
+.. _`show-desktop-notifications`:
+
+show_desktop_notifications
+--------------------------
+
+* Default: ``true``
+
+Should HTML5 desktop notifications be shown when the browser is not visible or
+blurred?
+
+Requires the `src/converse-notification.js` plugin.
+
 show_only_online_users
 ----------------------
 

docs/source/features.rst

@@ -39,13 +39,18 @@ 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
 communications privacy, then you're much better off using native software.
 
-Sound Notifications
-===================
+Notifications
+=============
 
 From version 0.8.1 Converse.js can play a sound notification when you receive a
 message.
 
-For more info, please see the :ref:`play-sounds` configuration setting.
+For more info, refer to the :ref:`play-sounds` configuration setting.
+
+It can also show `desktop notification messages <https://developer.mozilla.org/en-US/docs/Web/API/notification>`_
+when the browser is not currently visible.
+
+For more info, refer to the :ref:`show-desktop-notifications` configuration setting.
 
 Multilingual Support
 ====================

index.html

@@ -146,7 +146,8 @@
                             <li>Roster item exchange (<a href="http://xmpp.org/extensions/tmp/xep-0144-1.1.html" target="_blank">XEP 144</a>)</li>
                             <li>Chat statuses (online, busy, away, offline)</li>
                             <li>Custom status messages</li>
-                            <li>Typing and state notifications (<a href="http://xmpp.org/extensions/xep-0085.html" target="_blank">XEP 85</a>)</li>
+                            <li>Typing and chat state notifications (<a href="http://xmpp.org/extensions/xep-0085.html" target="_blank">XEP 85</a>)</li>
+                            <li>Desktop notification messages when the browser is not visible</li>
                             <li>Messages appear in all connected chat clients (<a href="http://xmpp.org/extensions/xep-0280.html" target="_blank">XEP 280</a>)</li>
                             <li>Third person "/me" messages (<a href="http://xmpp.org/extensions/xep-0245.html" target="_blank">XEP 245</a>)</li>
                             <li>XMPP Ping (<a href="http://xmpp.org/extensions/xep-0199.html" target="_blank">XEP 199</a>)</li>

src/converse-notification.js

@@ -34,6 +34,7 @@
             var converse = this.converse;
             // Configuration values for this plugin
             var settings = {
+                show_desktop_notifications: true,
                 play_sounds: false,
                 sounds_path: '/sounds/',
                 notification_icon: '/logo/conversejs.png'
@@ -113,7 +114,8 @@
                  * message was received.
                  */
                 if (!supports_html5_notification ||
-                        this.windowState !== 'blur' ||
+                        !converse.show_desktop_notifications ||
+                        converse.windowState !== 'blur' ||
                         Notification.permission !== "granted") {
                     return;
                 }