- Separated the usage of a validator function to it's own function

- Updated the docs accordingly

Author: maenriquez

.docs/angular-meteor/client/views/api/api.auth.html

@@ -22,7 +22,9 @@
 
     $meteor.waitForUser()
 
-    $meteor.requireUser([validatorFn])
+    $meteor.requireUser()
+
+    $meteor.requireValidUser(validatorFn)
 
     $meteor.loginWithPassword(user, password)
 
@@ -119,7 +121,7 @@ <h3><p><code><span class="pln">waitForUser();</span></code></p></h3>
     });
 
 <br>
-<h3><p><code><span class="pln">requireUser([validatorFn]);</span></code></p></h3>
+<h3><p><code><span class="pln">requireUser();</span></code></p></h3>
 
 Resolves the promise successfully if a user is authenticated and rejects otherwise.
 <br>
@@ -128,10 +130,6 @@ <h3><p><code><span class="pln">requireUser([validatorFn]);</span></code></p></h3
 You can catch the rejected promise and redirect the unauthenticated user to a different page, such as the login page.
 <br>
 See the <a href="/tutorial/step_08#authenticationwithrouters">“Authentication with Routers”</a> section of our tutorial for more information and a full example.
-<br>
-This method can receive a function as a parameter, which can be used to do custom validation prior to resolving/rejecting the promise.
-<br>
-If the validator function is present, the method will only resolve if the function returns true. If it returns a string, it will reject the promise with such string. Otherwise (false, null, undefined) it will reject the promise with the "FORBIDDEN" error string.
 
 
 
@@ -150,34 +148,77 @@ <h3><p><code><span class="pln">requireUser([validatorFn]);</span></code></p></h3
             return $meteor.requireUser();
           }]
         }
-      })
-      .state('admin', {
-        url: '/admin',
-        templateUrl: 'client/views/admin.ng.html',
-        controller: 'AdminController'
-        resolve: {
-          "currentUser": ["$meteor", function($meteor){
-            return $meteor.requireUser(function(user) {
-              return user.username==='admin';
-            });
-          }]
+      });
+
+    app.run(["$rootScope", "$state", function($rootScope, $state) {
+      $rootScope.$on("$stateChangeError", function(event, toState, toParams, fromState, fromParams, error) {
+        // We can catch the error thrown when the $meteor.requireUser() promise is rejected
+        // and redirect the user back to the login page
+        if (error === "AUTH_REQUIRED") {
+            // It is better to use $state instead of $location. See Issue #283.
+            $state.go('logIn');
         }
-      })
-      .state('admin2', {
-        url: '/admin2',
-        templateUrl: 'client/views/admin2.ng.html',
-        controller: 'Admin2Controller'
+      });
+    }]);
+
+<br>
+<h3><p><code><span class="pln">requireValidUser(validatorFn);</span></code></p></h3>
+
+Resolves the promise successfully if a user is authenticated and the validatorFn returns true; rejects otherwise.
+<br>
+This is useful in cases where you want to require a route to have an authenticated user and do extra validation like the user's role or group.
+<br>
+You can catch the rejected promise and redirect the unauthenticated user to a different page, such as the login page.
+<br>
+See the <a href="/tutorial/step_08#authenticationwithrouters">“Authentication with Routers”</a> section of our tutorial for more information and a full example.
+<br>
+The mandatory validator function will be called with the authenticated user as the single param and it's expected to return true in order to resolve. If it returns a string, the promise will be rejected using said string as the reason. Any other return (false, null, undefined) will be rejected with the default "FORBIDDEN" reason.
+
+
+
+----
+
+#### Example
+
+    // In route config ('ui-router' in the example, but works with 'ngRoute' the same way)
+    $stateProvider
+      .state('home', {
+        url: '/',
+        templateUrl: 'client/views/home.ng.html',
+        controller: 'HomeController'
         resolve: {
           "currentUser": ["$meteor", function($meteor){
-            return $meteor.requireUser(function(user) {
-              if (user.username==='admin2') {
-                return true;
-              }
-
-              return 'UNAUTHORIZED';
-            });
+            return $meteor.requireUser();
           }]
         }
+       })
+       .state('admin', {
+         url: '/admin',
+         templateUrl: 'client/views/admin.ng.html',
+         controller: 'AdminController'
+         resolve: {
+           "currentUser": ["$meteor", function($meteor){
+             return $meteor.requireUser(function(user) {
+               return user.username==='admin';
+             });
+           }]
+         }
+       })
+       .state('admin2', {
+         url: '/admin2',
+         templateUrl: 'client/views/admin2.ng.html',
+         controller: 'Admin2Controller'
+         resolve: {
+           "currentUser": ["$meteor", function($meteor){
+             return $meteor.requireUser(function(user) {
+               if (user.username==='admin2') {
+                 return true;
+               }
+
+               return 'UNAUTHORIZED';
+             });
+           }]
+         }
       });
 
     app.run(["$rootScope", "$state", function($rootScope, $state) {
@@ -196,7 +237,7 @@ <h3><p><code><span class="pln">requireUser([validatorFn]);</span></code></p></h3
             break;
           default:
             $state.go('internal-client-error');
-		}
+        }
       });
     }]);
 

angular-meteor.js

@@ -68,6 +68,7 @@ angularMeteor.service('$meteor', ['$meteorCollection', '$meteorObject', '$meteor
     this.call = $meteorMethods.call;
     this.loginWithPassword = $meteorUser.loginWithPassword;
     this.requireUser = $meteorUser.requireUser;
+    this.requireValidUser = $meteorUser.requireValidUser;
     this.waitForUser = $meteorUser.waitForUser;
     this.createUser = $meteorUser.createUser;
     this.changePassword = $meteorUser.changePassword;

modules/angular-meteor-user.js

@@ -12,6 +12,7 @@ angularMeteorUser.run(['$rootScope', '$meteorUtils', function($rootScope, $meteo
 
 angularMeteorUser.service('$meteorUser', ['$rootScope', '$meteorUtils', '$q',
   function($rootScope, $meteorUtils, $q){
+    var self = this;
 
     this.waitForUser = function(){
 
@@ -25,31 +26,35 @@ angularMeteorUser.service('$meteorUser', ['$rootScope', '$meteorUtils', '$q',
       return deferred.promise;
     };
 
-    this.requireUser = function(validatorFn){
+    this.requireUser = function(){
 
       var deferred = $q.defer();
 
       $meteorUtils.autorun($rootScope, function(){
         if ( !Meteor.loggingIn() ) {
           if ( Meteor.user() == null)
             deferred.reject("AUTH_REQUIRED");
-          else if (validatorFn) {
-            var valid = validatorFn( Meteor.user() );
-
-            if ( valid === true )
-              deferred.resolve( Meteor.user() );
-            else if ( typeof valid === "string" )
-              deferred.reject( valid );
-            else
-              deferred.reject( "FORBIDDEN" );
-          } else
+          else
             deferred.resolve( Meteor.user() );
         }
       });
 
       return deferred.promise;
     };
 
+    this.requireValidUser = function(validatorFn) {
+      return self.requireUser().then(function(user){
+        var valid = validatorFn( user );
+
+        if ( valid === true )
+          return user;
+        else if ( typeof valid === "string" )
+          return $.reject( valid );
+        else
+          return $q.reject( "FORBIDDEN" );
+	  });
+	};
+
     this.loginWithPassword = function(user, password){
 
       var deferred = $q.defer();