Expose webNotification.requestPermission #5

Author: sagiegurari

README.md

@@ -62,7 +62,7 @@ $('.some-button').on('click', function onClick() {
 
 In case you wish to use service worker web notifications, you must provide the serviceWorkerRegistration in the options as follows:
 
-````js
+```js
 navigator.serviceWorker.register('service-worker.js').then(function(registration) {
     $('.some-button').on('click', function onClick() {
         webNotification.showNotification('Example Notification', {
@@ -94,7 +94,21 @@ navigator.serviceWorker.register('service-worker.js').then(function(registration
         });
     });
 });
-````
+```
+
+In case you wish to invoke the permissions API manually you can use the webNotification.requestPermission function.<br>
+This function triggers the request permissions dialog in case permissions were not already granted.
+
+```js
+//manually ask for notification permissions (invoked automatically if needed and allowRequest=true)
+webNotification.requestPermission(function onRequest(granted) {
+    if (granted) {
+        console.log('Permission Granted.');
+    } else {
+        console.log('Permission Not Granted.');
+    }
+});
+```
 
 When using an AMD loader (such as RequireJS) or CommonJS type loader, the webNotification object is not automatically defined on the window scope.
 
@@ -129,7 +143,7 @@ See [contributing guide](.github/CONTRIBUTING.md)
 
 | Date        | Version | Description |
 | ----------- | ------- | ----------- |
-| 2018-06-14  | v1.0.27 | Maintenance |
+| 2018-06-25  | v1.0.28 | Expose webNotification.requestPermission #5 |
 | 2018-06-14  | v1.0.26 | Better error detection on chrome mobile #4 |
 | 2017-08-25  | v1.0.21 | Support service worker web notifications |
 | 2017-01-31  | v1.0.3  | Removed polyfill dependency |

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-web-notification",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "Web Notifications made easy.",
   "authors": [
     "Sagie Gur-Ari <[email protected]>"

docs/CHANGELOG.md

@@ -1,6 +1,6 @@
 | Date        | Version | Description |
 | ----------- | ------- | ----------- |
-| 2018-06-14  | v1.0.27 | Maintenance |
+| 2018-06-25  | v1.0.28 | Expose webNotification.requestPermission #5 |
 | 2018-06-14  | v1.0.26 | Better error detection on chrome mobile #4 |
 | 2017-08-25  | v1.0.21 | Support service worker web notifications |
 | 2017-01-31  | v1.0.3  | Removed polyfill dependency |

docs/api.md

@@ -12,6 +12,9 @@
 <dt><a href="#ShowNotificationCallback">ShowNotificationCallback</a> : <code>function</code></dt>
 <dd><p>&#39;showNotification&#39; callback.</p>
 </dd>
+<dt><a href="#PermissionsRequestCallback">PermissionsRequestCallback</a> : <code>function</code></dt>
+<dd><p>&#39;requestPermission&#39; callback.</p>
+</dd>
 </dl>
 
 <a name="webNotification"></a>
@@ -25,6 +28,7 @@ A simplified web notification API.
 * [webNotification](#webNotification) : <code>object</code>
     * [.allowRequest](#webNotification.allowRequest) : <code>Boolean</code>
     * [.permissionGranted](#webNotification.permissionGranted)
+    * [.requestPermission([callback])](#webNotification.requestPermission)
     * [.showNotification([title], [options], [callback])](#webNotification.showNotification)
 
 <a name="webNotification.allowRequest"></a>
@@ -39,6 +43,28 @@ True to enable automatic requesting of permissions if needed.
 True if permission is granted, else false.
 
 **Access**: public  
+<a name="webNotification.requestPermission"></a>
+
+### webNotification.requestPermission([callback])
+Triggers the request permissions dialog in case permissions were not already granted.
+
+**Access**: public  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [callback] | [<code>PermissionsRequestCallback</code>](#PermissionsRequestCallback) | Called with the permissions result (true enabled, false disabled) |
+
+**Example**  
+```js
+//manually ask for notification permissions (invoked automatically if needed and allowRequest=true)
+webNotification.requestPermission(function onRequest(granted) {
+ if (granted) {
+     console.log('Permission Granted.');
+ } else {
+     console.log('Permission Not Granted.');
+ }
+});
+```
 <a name="webNotification.showNotification"></a>
 
 ### webNotification.showNotification([title], [options], [callback])
@@ -128,3 +154,15 @@ navigator.serviceWorker.register('service-worker.js').then(function(registration
 | [error] | <code>error</code> | The error object in case of any error |
 | [hide] | <code>function</code> | The hide notification function |
 
+<a name="PermissionsRequestCallback"></a>
+
+## PermissionsRequestCallback : <code>function</code>
+'requestPermission' callback.
+
+**Kind**: global typedef  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [error] | <code>error</code> | The error object in case of any error |
+| [hide] | <code>function</code> | The hide notification function |
+

package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-web-notification",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "Web Notifications made easy.",
   "author": {
     "name": "Sagie Gur-Ari",

project/config/README-template.md

@@ -62,7 +62,7 @@ $('.some-button').on('click', function onClick() {
 
 In case you wish to use service worker web notifications, you must provide the serviceWorkerRegistration in the options as follows:
 
-````js
+```js
 navigator.serviceWorker.register('service-worker.js').then(function(registration) {
     $('.some-button').on('click', function onClick() {
         webNotification.showNotification('Example Notification', {
@@ -94,7 +94,21 @@ navigator.serviceWorker.register('service-worker.js').then(function(registration
         });
     });
 });
-````
+```
+
+In case you wish to invoke the permissions API manually you can use the webNotification.requestPermission function.<br>
+This function triggers the request permissions dialog in case permissions were not already granted.
+
+```js
+//manually ask for notification permissions (invoked automatically if needed and allowRequest=true)
+webNotification.requestPermission(function onRequest(granted) {
+    if (granted) {
+        console.log('Permission Granted.');
+    } else {
+        console.log('Permission Not Granted.');
+    }
+});
+```
 
 When using an AMD loader (such as RequireJS) or CommonJS type loader, the webNotification object is not automatically defined on the window scope.
 

test/helpers/notify-mock.js

@@ -1,14 +1,19 @@
 window.Notification = (function Notification() {
     'use strict';
 
+    var noop = function () {
+            return undefined;
+    };
+
     var permissionInfo = {
         value: null
     };
 
     var oncePermission;
 
     var Lib = function (title, options) {
-        Lib.validateNotification(title, options);
+        var validateNotification = Lib.validateNotification || noop;
+        validateNotification(title, options);
 
         var self = this;
         self.close = function () {
@@ -28,6 +33,12 @@ window.Notification = (function Notification() {
     });
 
     Lib.requestPermission = function (callback) {
+        if (Lib.errorOnPermission) {
+            setTimeout(function () {
+                callback(new Error('test'));
+            }, 5);
+        }
+
         if (oncePermission) {
             oncePermission();
             oncePermission = null;
@@ -37,9 +48,7 @@ window.Notification = (function Notification() {
     };
 
     Lib.setValidationNotification = function (validateNotification) {
-        Lib.validateNotification = validateNotification || function noop() {
-            return undefined;
-        };
+        Lib.validateNotification = validateNotification || noop;
     };
 
     Lib.setAllowed = function (validateNotification) {

test/spec/web-notification-spec.js

@@ -84,6 +84,58 @@ describe('simple-web-notification', function () {
         });
     });
 
+    describe('requestPermission', function () {
+        it('no callback', function () {
+            assert.isTrue(window.webNotification.lib.MOCK_NOTIFY);
+            window.Notification.errorOnPermission = true;
+
+            window.webNotification.requestPermission();
+
+            window.Notification.errorOnPermission = false;
+        });
+
+        it('callback not a function', function () {
+            assert.isTrue(window.webNotification.lib.MOCK_NOTIFY);
+            window.Notification.errorOnPermission = true;
+
+            window.webNotification.requestPermission(true);
+
+            window.Notification.errorOnPermission = false;
+        });
+
+        it('allowed', function (done) {
+            assert.isTrue(window.webNotification.lib.MOCK_NOTIFY);
+            window.Notification.setAllowed();
+
+            window.webNotification.requestPermission(function (granted) {
+                assert.isTrue(granted);
+                done();
+            });
+        });
+
+        it('not allowed', function (done) {
+            assert.isTrue(window.webNotification.lib.MOCK_NOTIFY);
+            window.Notification.setNotAllowed();
+
+            window.webNotification.requestPermission(function (granted) {
+                assert.isFalse(granted);
+                done();
+            });
+        });
+
+        it('error', function (done) {
+            assert.isTrue(window.webNotification.lib.MOCK_NOTIFY);
+            window.Notification.errorOnPermission = true;
+
+            window.webNotification.requestPermission(function (granted) {
+                assert.isFalse(granted);
+                done();
+            });
+
+            window.Notification.errorOnPermission = false;
+        });
+    });
+
     describe('showNotification', function () {
         describe('allowed', function () {
             it('all info', function (done) {

web-notification.js

@@ -8,6 +8,14 @@
  * @param {function} [hide] - The hide notification function
  */
 
+/**
+ * 'requestPermission' callback.
+ *
+ * @callback PermissionsRequestCallback
+ * @param {error} [error] - The error object in case of any error
+ * @param {function} [hide] - The hide notification function
+ */
+
 /**
  * A simplified web notification API.
  *
@@ -265,6 +273,38 @@
         };
     };
 
+    /**
+     * Triggers the request permissions dialog in case permissions were not already granted.
+     *
+     * @function
+     * @memberof! webNotification
+     * @alias webNotification.requestPermission
+     * @public
+     * @param {PermissionsRequestCallback} [callback] - Called with the permissions result (true enabled, false disabled)
+     * @example
+     * ```js
+     * //manually ask for notification permissions (invoked automatically if needed and allowRequest=true)
+     * webNotification.requestPermission(function onRequest(granted) {
+     *  if (granted) {
+     *      console.log('Permission Granted.');
+     *  } else {
+     *      console.log('Permission Not Granted.');
+     *  }
+     * });
+     * ```
+     */
+    webNotification.requestPermission = function (callback) {
+        if (callback && typeof callback === 'function') {
+            if (isEnabled()) {
+                callback(true);
+            } else {
+                NotificationAPI.requestPermission(function onRequestDone() {
+                    callback(isEnabled());
+                });
+            }
+        }
+    };
+
     /**
      * Shows the notification based on the provided input.<br>
      * The callback invoked will get an error object (in case of an error, null in
@@ -352,19 +392,13 @@
             var title = data.title;
             var options = data.options;
 
-            if (isEnabled()) {
-                createAndDisplayNotification(title, options, callback);
-            } else if (webNotification.allowRequest) {
-                NotificationAPI.requestPermission(function onRequestDone() {
-                    if (isEnabled()) {
-                        createAndDisplayNotification(title, options, callback);
-                    } else {
-                        callback(new Error('Notifications are not enabled.'), null);
-                    }
-                });
-            } else {
-                callback(new Error('Notifications are not enabled.'), null);
-            }
+            webNotification.requestPermission(function onRequestDone(granted) {
+                if (granted) {
+                    createAndDisplayNotification(title, options, callback);
+                } else {
+                    callback(new Error('Notifications are not enabled.'), null);
+                }
+            });
         }
     };