feat(ngMessages): add support for default message

gdangelo · Narretz · commit 74298b6c0304 · 2018-06-01T13:53:40.000+02:00
Added support for showing default message when no values are mapped with ng-message. Closes angular#12008
diff --git a/src/ngMessages/messages.js b/src/ngMessages/messages.js
@@ -18,7 +18,7 @@ var jqLite;
  * sequencing based on the order of how the messages are defined in the template.
  *
  * Currently, the ngMessages module only contains the code for the `ngMessages`, `ngMessagesInclude`
- * `ngMessage` and `ngMessageExp` directives.
+ * `ngMessage`, `ngMessageExp` and `ngMessageDefault` directives.
  *
  * ## Usage
  * The `ngMessages` directive allows keys in a key/value collection to be associated with a child element
@@ -257,6 +257,19 @@ var jqLite;
  * .some-message.ng-leave.ng-leave-active {}
  * ```
  *
+ * ## Displaying a default message
+ * If the ngMessages renders no inner ngMessage directive (that is to say when the key values does not
+ * match the attribute value present on each ngMessage directive), then it will render a default message
+ * using the ngMessageDefault directive.
+ *
+ * ```html
+ * <div ng-messages="myForm.myField.$error" role="alert">
+ *   <div ng-message="required">This field is required</div>
+ *   <div ng-message="minlength">This field is too short</div>
+ *   <div ng-message-default>This is a default message</div>
+ * </div>
+ * ```
+ *
  * {@link ngAnimate Click here} to learn how to use JavaScript animations or to learn more about ngAnimate.
  */
 angular.module('ngMessages', [], function initAngularHelpers() {
@@ -289,6 +302,9 @@ angular.module('ngMessages', [], function initAngularHelpers() {
    * A remote template can also be used to promote message reusability and messages can also be
    * overridden.
    *
+   * A default message can also be displayed when no `ngMessage` directive is inserted, using the
+   * `ngMessageDefault` directive.
+   *
    * {@link module:ngMessages Click here} to learn more about `ngMessages` and `ngMessage`.
    *
    * @usage
@@ -298,13 +314,15 @@ angular.module('ngMessages', [], function initAngularHelpers() {
    *   <ANY ng-message="stringValue">...</ANY>
    *   <ANY ng-message="stringValue1, stringValue2, ...">...</ANY>
    *   <ANY ng-message-exp="expressionValue">...</ANY>
+   *   <ANY ng-message-default>...</ANY>
    * </ANY>
    *
    * <!-- or by using element directives -->
    * <ng-messages for="expression" role="alert">
    *   <ng-message when="stringValue">...</ng-message>
    *   <ng-message when="stringValue1, stringValue2, ...">...</ng-message>
    *   <ng-message when-exp="expressionValue">...</ng-message>
+   *   <ng-message-default>...</ng-message-default>
    * </ng-messages>
    * ```
    *
@@ -333,6 +351,7 @@ angular.module('ngMessages', [], function initAngularHelpers() {
    *         <div ng-message="required">You did not enter a field</div>
    *         <div ng-message="minlength">Your field is too short</div>
    *         <div ng-message="maxlength">Your field is too long</div>
+   *         <div ng-message-default>This field has an input error</div>
    *       </div>
    *     </form>
    *   </file>
@@ -409,8 +428,15 @@ angular.module('ngMessages', [], function initAngularHelpers() {
           });
 
           if (unmatchedMessages.length !== totalMessages) {
+            // Unset default message if set
+            if (ctrl.default) ctrl.default.detach();
+
             $animate.setClass($element, ACTIVE_CLASS, INACTIVE_CLASS);
           } else {
+
+            // Set default message if no other matched
+            if (ctrl.default) ctrl.default.attach();
+
             $animate.setClass($element, INACTIVE_CLASS, ACTIVE_CLASS);
           }
         };
@@ -428,23 +454,31 @@ angular.module('ngMessages', [], function initAngularHelpers() {
           }
         };
 
-        this.register = function(comment, messageCtrl) {
-          var nextKey = latestKey.toString();
-          messages[nextKey] = {
-            message: messageCtrl
-          };
-          insertMessageNode($element[0], comment, nextKey);
-          comment.$$ngMessageNode = nextKey;
-          latestKey++;
+        this.register = function(comment, messageCtrl, isDefault) {
+          if (isDefault) {
+            ctrl.default = messageCtrl;
+          } else {
+            var nextKey = latestKey.toString();
+            messages[nextKey] = {
+              message: messageCtrl
+            };
+            insertMessageNode($element[0], comment, nextKey);
+            comment.$$ngMessageNode = nextKey;
+            latestKey++;
+          }
 
           ctrl.reRender();
         };
 
-        this.deregister = function(comment) {
-          var key = comment.$$ngMessageNode;
-          delete comment.$$ngMessageNode;
-          removeMessageNode($element[0], comment, key);
-          delete messages[key];
+        this.deregister = function(comment, isDefault) {
+          if (isDefault) {
+            delete ctrl.default;
+          } else {
+            var key = comment.$$ngMessageNode;
+            delete comment.$$ngMessageNode;
+            removeMessageNode($element[0], comment, key);
+            delete messages[key];
+          }
           ctrl.reRender();
         };
 
@@ -647,9 +681,44 @@ angular.module('ngMessages', [], function initAngularHelpers() {
    *
    * @param {expression} ngMessageExp|whenExp an expression value corresponding to the message key.
    */
-  .directive('ngMessageExp', ngMessageDirectiveFactory());
+  .directive('ngMessageExp', ngMessageDirectiveFactory())
 
-function ngMessageDirectiveFactory() {
+  /**
+   * @ngdoc directive
+   * @name ngMessageDefault
+   * @restrict AE
+   * @scope
+   *
+   * @description
+   * `ngMessageDefault` is a directive with the purpose to show and hide a default message.
+   * For `ngMessageDefault` to operate, no `ngMessage` inner directive should be displayed
+   * in the parent `ngMessages` directive.
+   *
+   * More information about using `ngMessageDefault` can be found in the
+   * {@link module:ngMessages `ngMessages` module documentation}.
+   *
+   * @usage
+   * ```html
+   * <!-- using attribute directives -->
+   * <ANY ng-messages="expression" role="alert">
+   *   <ANY ng-message="stringValue">...</ANY>
+   *   <ANY ng-message="stringValue1, stringValue2, ...">...</ANY>
+   *   <ANY ng-message-default>...</ANY>
+   * </ANY>
+   *
+   * <!-- or by using element directives -->
+   * <ng-messages for="expression" role="alert">
+   *   <ng-message when="stringValue">...</ng-message>
+   *   <ng-message when="stringValue1, stringValue2, ...">...</ng-message>
+   *   <ng-message-default>...</ng-message-default>
+   * </ng-messages>
+   * ```
+   *
+   * @param ngMessageDefault|when no ngMessage matches.
+  */
+  .directive('ngMessageDefault', ngMessageDirectiveFactory(true));
+
+function ngMessageDirectiveFactory(isDefault) {
   return ['$animate', function($animate) {
     return {
       restrict: 'AE',
@@ -658,25 +727,28 @@ function ngMessageDirectiveFactory() {
       terminal: true,
       require: '^^ngMessages',
       link: function(scope, element, attrs, ngMessagesCtrl, $transclude) {
-        var commentNode = element[0];
-
-        var records;
-        var staticExp = attrs.ngMessage || attrs.when;
-        var dynamicExp = attrs.ngMessageExp || attrs.whenExp;
-        var assignRecords = function(items) {
-          records = items
-              ? (isArray(items)
-                  ? items
-                  : items.split(/[\s,]+/))
-              : null;
-          ngMessagesCtrl.reRender();
-        };
+        var commentNode, records, staticExp, dynamicExp;
+
+        if (!isDefault) {
+          commentNode = element[0];
+          staticExp = attrs.ngMessage || attrs.when;
+          dynamicExp = attrs.ngMessageExp || attrs.whenExp;
+
+          var assignRecords = function(items) {
+            records = items
+                ? (isArray(items)
+                      ? items
+                      : items.split(/[\s,]+/))
+                : null;
+            ngMessagesCtrl.reRender();
+          };
 
-        if (dynamicExp) {
-          assignRecords(scope.$eval(dynamicExp));
-          scope.$watchCollection(dynamicExp, assignRecords);
-        } else {
-          assignRecords(staticExp);
+          if (dynamicExp) {
+            assignRecords(scope.$eval(dynamicExp));
+            scope.$watchCollection(dynamicExp, assignRecords);
+          } else {
+            assignRecords(staticExp);
+          }
         }
 
         var currentElement, messageCtrl;
@@ -701,7 +773,7 @@ function ngMessageDirectiveFactory() {
                   // If the message element was removed via a call to `detach` then `currentElement` will be null
                   // So this handler only handles cases where something else removed the message element.
                   if (currentElement && currentElement.$$attachId === $$attachId) {
-                    ngMessagesCtrl.deregister(commentNode);
+                    ngMessagesCtrl.deregister(commentNode, isDefault);
                     messageCtrl.detach();
                   }
                   newScope.$destroy();
@@ -716,14 +788,14 @@ function ngMessageDirectiveFactory() {
               $animate.leave(elm);
             }
           }
-        });
+        }, isDefault);
 
         // We need to ensure that this directive deregisters itself when it no longer exists
         // Normally this is done when the attached element is destroyed; but if this directive
         // gets removed before we attach the message to the DOM there is nothing to watch
         // in which case we must deregister when the containing scope is destroyed.
         scope.$on('$destroy', function() {
-          ngMessagesCtrl.deregister(commentNode);
+          ngMessagesCtrl.deregister(commentNode, isDefault);
         });
       }
     };
diff --git a/test/ngMessages/messagesSpec.js b/test/ngMessages/messagesSpec.js
@@ -661,6 +661,49 @@ describe('ngMessages', function() {
   );
 
 
+  describe('default message', function() {
+    it('should render a default message when no message matches', inject(function($rootScope, $compile) {
+      element = $compile('<div ng-messages="col">' +
+                         '  <div ng-message="val">Message is set</div>' +
+                         '  <div ng-message-default>Default message is set</div>' +
+                         '</div>')($rootScope);
+      $rootScope.$digest();
+
+      expect(element.text().trim()).toBe('Default message is set');
+
+      $rootScope.$apply(function() {
+        $rootScope.col = { val: true };
+      });
+
+      expect(element.text().trim()).toBe('Message is set');
+    }));
+
+    it('should handle a default message with ngIf', inject(function($rootScope, $compile) {
+      element = $compile('<div ng-messages="col">' +
+                         '  <div ng-message="val">Message is set</div>' +
+                         '  <div ng-if="default" ng-message-default>Default message is set</div>' +
+                         '</div>')($rootScope);
+      $rootScope.default = true;
+      $rootScope.$digest();
+
+      expect(element.text().trim()).toBe('Default message is set');
+
+      $rootScope.$apply('default = false');
+
+      expect(element.text().trim()).toBe('');
+
+      $rootScope.$apply('default = true');
+
+      expect(element.text().trim()).toBe('Default message is set');
+
+      $rootScope.$apply(function() {
+        $rootScope.col = { val: true };
+      });
+
+      expect(element.text().trim()).toBe('Message is set');
+    }));
+  });
+
   describe('when including templates', function() {
     they('should work with a dynamic collection model which is managed by ngRepeat',
       {'<div ng-messages-include="...">': '<div ng-messages="item">' +
