2 * @license AngularJS v1.5.0
3 * (c) 2010-2016 Google, Inc. http://angularjs.org
6 (function(window, angular, undefined) {'use strict';
8 /* jshint ignore:start */
9 // this code is in the core, but not in angular-messages.js
10 var isArray = angular.isArray;
11 var forEach = angular.forEach;
12 var isString = angular.isString;
13 var jqLite = angular.element;
14 /* jshint ignore:end */
21 * The `ngMessages` module provides enhanced support for displaying messages within templates
22 * (typically within forms or when rendering message objects that return key/value data).
23 * Instead of relying on JavaScript code and/or complex ng-if statements within your form template to
24 * show and hide error messages specific to the state of an input field, the `ngMessages` and
25 * `ngMessage` directives are designed to handle the complexity, inheritance and priority
26 * sequencing based on the order of how the messages are defined in the template.
28 * Currently, the ngMessages module only contains the code for the `ngMessages`, `ngMessagesInclude`
29 * `ngMessage` and `ngMessageExp` directives.
32 * The `ngMessages` directive listens on a key/value collection which is set on the ngMessages attribute.
33 * Since the {@link ngModel ngModel} directive exposes an `$error` object, this error object can be
34 * used with `ngMessages` to display control error messages in an easier way than with just regular angular
35 * template directives.
38 * <form name="myForm">
41 * <input type="text" ng-model="field" name="myField" required minlength="5" />
43 * <div ng-messages="myForm.myField.$error" role="alert">
44 * <div ng-message="required">You did not enter a field</div>
45 * <div ng-message="minlength, maxlength">
46 * Your email must be between 5 and 100 characters long
52 * Now whatever key/value entries are present within the provided object (in this case `$error`) then
53 * the ngMessages directive will render the inner first ngMessage directive (depending if the key values
54 * match the attribute value present on each ngMessage directive). In other words, if your errors
55 * object contains the following data:
58 * <!-- keep in mind that ngModel automatically sets these error flags -->
59 * myField.$error = { minlength : true, required : true };
62 * Then the `required` message will be displayed first. When required is false then the `minlength` message
63 * will be displayed right after (since these messages are ordered this way in the template HTML code).
64 * The prioritization of each message is determined by what order they're present in the DOM.
65 * Therefore, instead of having custom JavaScript code determine the priority of what errors are
66 * present before others, the presentation of the errors are handled within the template.
68 * By default, ngMessages will only display one error at a time. However, if you wish to display all
69 * messages then the `ng-messages-multiple` attribute flag can be used on the element containing the
70 * ngMessages directive to make this happen.
73 * <!-- attribute-style usage -->
74 * <div ng-messages="myForm.myField.$error" ng-messages-multiple>...</div>
76 * <!-- element-style usage -->
77 * <ng-messages for="myForm.myField.$error" multiple>...</ng-messages>
80 * ## Reusing and Overriding Messages
81 * In addition to prioritization, ngMessages also allows for including messages from a remote or an inline
82 * template. This allows for generic collection of messages to be reused across multiple parts of an
86 * <script type="text/ng-template" id="error-messages">
87 * <div ng-message="required">This field is required</div>
88 * <div ng-message="minlength">This field is too short</div>
91 * <div ng-messages="myForm.myField.$error" role="alert">
92 * <div ng-messages-include="error-messages"></div>
96 * However, including generic messages may not be useful enough to match all input fields, therefore,
97 * `ngMessages` provides the ability to override messages defined in the remote template by redefining
98 * them within the directive container.
101 * <!-- a generic template of error messages known as "my-custom-messages" -->
102 * <script type="text/ng-template" id="my-custom-messages">
103 * <div ng-message="required">This field is required</div>
104 * <div ng-message="minlength">This field is too short</div>
107 * <form name="myForm">
110 * <input type="email"
117 * <!-- any ng-message elements that appear BEFORE the ng-messages-include will
118 * override the messages present in the ng-messages-include template -->
119 * <div ng-messages="myForm.myEmail.$error" role="alert">
120 * <!-- this required message has overridden the template message -->
121 * <div ng-message="required">You did not enter your email address</div>
123 * <!-- this is a brand new message and will appear last in the prioritization -->
124 * <div ng-message="email">Your email address is invalid</div>
126 * <!-- and here are the generic error messages -->
127 * <div ng-messages-include="my-custom-messages"></div>
132 * In the example HTML code above the message that is set on required will override the corresponding
133 * required message defined within the remote template. Therefore, with particular input fields (such
134 * email addresses, date fields, autocomplete inputs, etc...), specialized error messages can be applied
135 * while more generic messages can be used to handle other, more general input errors.
137 * ## Dynamic Messaging
138 * ngMessages also supports using expressions to dynamically change key values. Using arrays and
139 * repeaters to list messages is also supported. This means that the code below will be able to
140 * fully adapt itself and display the appropriate message when any of the expression data changes:
143 * <form name="myForm">
146 * <input type="email"
152 * <div ng-messages="myForm.myEmail.$error" role="alert">
153 * <div ng-message="required">You did not enter your email address</div>
154 * <div ng-repeat="errorMessage in errorMessages">
155 * <!-- use ng-message-exp for a message whose key is given by an expression -->
156 * <div ng-message-exp="errorMessage.type">{{ errorMessage.text }}</div>
162 * The `errorMessage.type` expression can be a string value or it can be an array so
163 * that multiple errors can be associated with a single error message:
168 * <input type="email"
169 * ng-model="data.email"
175 * <div ng-messages="myForm.myEmail.$error" role="alert">
176 * <div ng-message-exp="'required'">You did not enter your email address</div>
177 * <div ng-message-exp="['minlength', 'maxlength']">
178 * Your email must be between 5 and 100 characters long
183 * Feel free to use other structural directives such as ng-if and ng-switch to further control
184 * what messages are active and when. Be careful, if you place ng-message on the same element
185 * as these structural directives, Angular may not be able to determine if a message is active
186 * or not. Therefore it is best to place the ng-message on a child element of the structural
190 * <div ng-messages="myForm.myEmail.$error" role="alert">
191 * <div ng-if="showRequiredError">
192 * <div ng-message="required">Please enter something</div>
198 * If the `ngAnimate` module is active within the application then the `ngMessages`, `ngMessage` and
199 * `ngMessageExp` directives will trigger animations whenever any messages are added and removed from
200 * the DOM by the `ngMessages` directive.
202 * Whenever the `ngMessages` directive contains one or more visible messages then the `.ng-active` CSS
203 * class will be added to the element. The `.ng-inactive` CSS class will be applied when there are no
204 * messages present. Therefore, CSS transitions and keyframes as well as JavaScript animations can
205 * hook into the animations whenever these classes are added/removed.
207 * Let's say that our HTML code for our messages container looks like so:
210 * <div ng-messages="myMessages" class="my-messages" role="alert">
211 * <div ng-message="alert" class="some-message">...</div>
212 * <div ng-message="fail" class="some-message">...</div>
216 * Then the CSS animation code for the message container looks like so:
220 * transition:1s linear all;
222 * .my-messages.ng-active {
223 * // messages are visible
225 * .my-messages.ng-inactive {
226 * // messages are hidden
230 * Whenever an inner message is attached (becomes visible) or removed (becomes hidden) then the enter
231 * and leave animation is triggered for each particular element bound to the `ngMessage` directive.
233 * Therefore, the CSS code for the inner messages looks like so:
237 * transition:1s linear all;
240 * .some-message.ng-enter {}
241 * .some-message.ng-enter.ng-enter-active {}
243 * .some-message.ng-leave {}
244 * .some-message.ng-leave.ng-leave-active {}
247 * {@link ngAnimate Click here} to learn how to use JavaScript animations or to learn more about ngAnimate.
249 angular.module('ngMessages', [])
258 * `ngMessages` is a directive that is designed to show and hide messages based on the state
259 * of a key/value object that it listens on. The directive itself complements error message
260 * reporting with the `ngModel` $error object (which stores a key/value state of validation errors).
262 * `ngMessages` manages the state of internal messages within its container element. The internal
263 * messages use the `ngMessage` directive and will be inserted/removed from the page depending
264 * on if they're present within the key/value object. By default, only one message will be displayed
265 * at a time and this depends on the prioritization of the messages within the template. (This can
266 * be changed by using the `ng-messages-multiple` or `multiple` attribute on the directive container.)
268 * A remote template can also be used to promote message reusability and messages can also be
271 * {@link module:ngMessages Click here} to learn more about `ngMessages` and `ngMessage`.
275 * <!-- using attribute directives -->
276 * <ANY ng-messages="expression" role="alert">
277 * <ANY ng-message="stringValue">...</ANY>
278 * <ANY ng-message="stringValue1, stringValue2, ...">...</ANY>
279 * <ANY ng-message-exp="expressionValue">...</ANY>
282 * <!-- or by using element directives -->
283 * <ng-messages for="expression" role="alert">
284 * <ng-message when="stringValue">...</ng-message>
285 * <ng-message when="stringValue1, stringValue2, ...">...</ng-message>
286 * <ng-message when-exp="expressionValue">...</ng-message>
290 * @param {string} ngMessages an angular expression evaluating to a key/value object
291 * (this is typically the $error object on an ngModel instance).
292 * @param {string=} ngMessagesMultiple|multiple when set, all messages will be displayed with true
295 * <example name="ngMessages-directive" module="ngMessagesExample"
296 * deps="angular-messages.js"
297 * animations="true" fixBase="true">
298 * <file name="index.html">
299 * <form name="myForm">
309 * <pre>myForm.myName.$error = {{ myForm.myName.$error | json }}</pre>
311 * <div ng-messages="myForm.myName.$error" style="color:maroon" role="alert">
312 * <div ng-message="required">You did not enter a field</div>
313 * <div ng-message="minlength">Your field is too short</div>
314 * <div ng-message="maxlength">Your field is too long</div>
318 * <file name="script.js">
319 * angular.module('ngMessagesExample', ['ngMessages']);
323 .directive('ngMessages', ['$animate', function($animate) {
324 var ACTIVE_CLASS = 'ng-active';
325 var INACTIVE_CLASS = 'ng-inactive';
328 require: 'ngMessages',
330 controller: ['$element', '$scope', '$attrs', function($element, $scope, $attrs) {
333 var nextAttachId = 0;
335 this.getAttachId = function getAttachId() { return nextAttachId++; };
337 var messages = this.messages = {};
338 var renderLater, cachedCollection;
340 this.render = function(collection) {
341 collection = collection || {};
344 cachedCollection = collection;
346 // this is true if the attribute is empty or if the attribute value is truthy
347 var multiple = isAttrTruthy($scope, $attrs.ngMessagesMultiple) ||
348 isAttrTruthy($scope, $attrs.multiple);
350 var unmatchedMessages = [];
351 var matchedKeys = {};
352 var messageItem = ctrl.head;
353 var messageFound = false;
354 var totalMessages = 0;
356 // we use != instead of !== to allow for both undefined and null values
357 while (messageItem != null) {
359 var messageCtrl = messageItem.message;
361 var messageUsed = false;
363 forEach(collection, function(value, key) {
364 if (!messageUsed && truthy(value) && messageCtrl.test(key)) {
365 // this is to prevent the same error name from showing up twice
366 if (matchedKeys[key]) return;
367 matchedKeys[key] = true;
370 messageCtrl.attach();
376 // unless we want to display multiple messages then we should
377 // set a flag here to avoid displaying the next message in the list
378 messageFound = !multiple;
380 unmatchedMessages.push(messageCtrl);
383 messageItem = messageItem.next;
386 forEach(unmatchedMessages, function(messageCtrl) {
387 messageCtrl.detach();
390 unmatchedMessages.length !== totalMessages
391 ? $animate.setClass($element, ACTIVE_CLASS, INACTIVE_CLASS)
392 : $animate.setClass($element, INACTIVE_CLASS, ACTIVE_CLASS);
395 $scope.$watchCollection($attrs.ngMessages || $attrs['for'], ctrl.render);
397 this.reRender = function() {
400 $scope.$evalAsync(function() {
402 cachedCollection && ctrl.render(cachedCollection);
408 this.register = function(comment, messageCtrl) {
409 var nextKey = latestKey.toString();
410 messages[nextKey] = {
413 insertMessageNode($element[0], comment, nextKey);
414 comment.$$ngMessageNode = nextKey;
420 this.deregister = function(comment) {
421 var key = comment.$$ngMessageNode;
422 delete comment.$$ngMessageNode;
423 removeMessageNode($element[0], comment, key);
424 delete messages[key];
428 function findPreviousMessage(parent, comment) {
429 var prevNode = comment;
430 var parentLookup = [];
431 while (prevNode && prevNode !== parent) {
432 var prevKey = prevNode.$$ngMessageNode;
433 if (prevKey && prevKey.length) {
434 return messages[prevKey];
437 // dive deeper into the DOM and examine its children for any ngMessage
438 // comments that may be in an element that appears deeper in the list
439 if (prevNode.childNodes.length && parentLookup.indexOf(prevNode) == -1) {
440 parentLookup.push(prevNode);
441 prevNode = prevNode.childNodes[prevNode.childNodes.length - 1];
443 prevNode = prevNode.previousSibling || prevNode.parentNode;
448 function insertMessageNode(parent, comment, key) {
449 var messageNode = messages[key];
451 ctrl.head = messageNode;
453 var match = findPreviousMessage(parent, comment);
455 messageNode.next = match.next;
456 match.next = messageNode;
458 messageNode.next = ctrl.head;
459 ctrl.head = messageNode;
464 function removeMessageNode(parent, comment, key) {
465 var messageNode = messages[key];
467 var match = findPreviousMessage(parent, comment);
469 match.next = messageNode.next;
471 ctrl.head = messageNode.next;
477 function isAttrTruthy(scope, attr) {
478 return (isString(attr) && attr.length === 0) || //empty attribute
479 truthy(scope.$eval(attr));
482 function truthy(val) {
483 return isString(val) ? val.length : !!val;
489 * @name ngMessagesInclude
494 * `ngMessagesInclude` is a directive with the purpose to import existing ngMessage template
495 * code from a remote template and place the downloaded template code into the exact spot
496 * that the ngMessagesInclude directive is placed within the ngMessages container. This allows
497 * for a series of pre-defined messages to be reused and also allows for the developer to
498 * determine what messages are overridden due to the placement of the ngMessagesInclude directive.
502 * <!-- using attribute directives -->
503 * <ANY ng-messages="expression" role="alert">
504 * <ANY ng-messages-include="remoteTplString">...</ANY>
507 * <!-- or by using element directives -->
508 * <ng-messages for="expression" role="alert">
509 * <ng-messages-include src="expressionValue1">...</ng-messages-include>
513 * {@link module:ngMessages Click here} to learn more about `ngMessages` and `ngMessage`.
515 * @param {string} ngMessagesInclude|src a string value corresponding to the remote template.
517 .directive('ngMessagesInclude',
518 ['$templateRequest', '$document', '$compile', function($templateRequest, $document, $compile) {
522 require: '^^ngMessages', // we only require this for validation sake
523 link: function($scope, element, attrs) {
524 var src = attrs.ngMessagesInclude || attrs.src;
525 $templateRequest(src).then(function(html) {
526 $compile(html)($scope, function(contents) {
527 element.after(contents);
529 // the anchor is placed for debugging purposes
530 var anchor = jqLite($document[0].createComment(' ngMessagesInclude: ' + src + ' '));
531 element.after(anchor);
533 // we don't want to pollute the DOM anymore by keeping an empty directive element
548 * `ngMessage` is a directive with the purpose to show and hide a particular message.
549 * For `ngMessage` to operate, a parent `ngMessages` directive on a parent DOM element
550 * must be situated since it determines which messages are visible based on the state
551 * of the provided key/value map that `ngMessages` listens on.
553 * More information about using `ngMessage` can be found in the
554 * {@link module:ngMessages `ngMessages` module documentation}.
558 * <!-- using attribute directives -->
559 * <ANY ng-messages="expression" role="alert">
560 * <ANY ng-message="stringValue">...</ANY>
561 * <ANY ng-message="stringValue1, stringValue2, ...">...</ANY>
564 * <!-- or by using element directives -->
565 * <ng-messages for="expression" role="alert">
566 * <ng-message when="stringValue">...</ng-message>
567 * <ng-message when="stringValue1, stringValue2, ...">...</ng-message>
571 * @param {expression} ngMessage|when a string value corresponding to the message key.
573 .directive('ngMessage', ngMessageDirectiveFactory())
584 * `ngMessageExp` is a directive with the purpose to show and hide a particular message.
585 * For `ngMessageExp` to operate, a parent `ngMessages` directive on a parent DOM element
586 * must be situated since it determines which messages are visible based on the state
587 * of the provided key/value map that `ngMessages` listens on.
591 * <!-- using attribute directives -->
592 * <ANY ng-messages="expression">
593 * <ANY ng-message-exp="expressionValue">...</ANY>
596 * <!-- or by using element directives -->
597 * <ng-messages for="expression">
598 * <ng-message when-exp="expressionValue">...</ng-message>
602 * {@link module:ngMessages Click here} to learn more about `ngMessages` and `ngMessage`.
604 * @param {expression} ngMessageExp|whenExp an expression value corresponding to the message key.
606 .directive('ngMessageExp', ngMessageDirectiveFactory());
608 function ngMessageDirectiveFactory() {
609 return ['$animate', function($animate) {
612 transclude: 'element',
613 priority: 1, // must run before ngBind, otherwise the text is set on the comment
615 require: '^^ngMessages',
616 link: function(scope, element, attrs, ngMessagesCtrl, $transclude) {
617 var commentNode = element[0];
620 var staticExp = attrs.ngMessage || attrs.when;
621 var dynamicExp = attrs.ngMessageExp || attrs.whenExp;
622 var assignRecords = function(items) {
626 : items.split(/[\s,]+/))
628 ngMessagesCtrl.reRender();
632 assignRecords(scope.$eval(dynamicExp));
633 scope.$watchCollection(dynamicExp, assignRecords);
635 assignRecords(staticExp);
638 var currentElement, messageCtrl;
639 ngMessagesCtrl.register(commentNode, messageCtrl = {
640 test: function(name) {
641 return contains(records, name);
644 if (!currentElement) {
645 $transclude(scope, function(elm) {
646 $animate.enter(elm, null, element);
647 currentElement = elm;
649 // Each time we attach this node to a message we get a new id that we can match
650 // when we are destroying the node later.
651 var $$attachId = currentElement.$$attachId = ngMessagesCtrl.getAttachId();
653 // in the event that the parent element is destroyed
654 // by any other structural directive then it's time
655 // to deregister the message from the controller
656 currentElement.on('$destroy', function() {
657 if (currentElement && currentElement.$$attachId === $$attachId) {
658 ngMessagesCtrl.deregister(commentNode);
659 messageCtrl.detach();
666 if (currentElement) {
667 var elm = currentElement;
668 currentElement = null;
677 function contains(collection, key) {
679 return isArray(collection)
680 ? collection.indexOf(key) >= 0
681 : collection.hasOwnProperty(key);
687 })(window, window.angular);