Merge pull request #139 from isaacplmann/master

Tests and documentation for escChar

Author: lukepfeiffer10

README.md

@@ -66,13 +66,16 @@ Inside of `ui-options`, you can customize these four properties:
 * `clearOnBlurPlaceholder` - default: `false`,
 * `eventsToHandle` - default: `['input', 'keyup', 'click', 'focus']`
 * `addDefaultPlaceholder` - default: `true`
+* `escChar` - default: `'\\'`
 
 When customizing `eventsToHandle`, `clearOnBlur`, or `addDefaultPlaceholder`, the value you supply will replace the default. To customize `eventsToHandle`, be sure to replace the entire array.
 
 Whereas, `maskDefinitions` is an object, so any custom object you supply will be merged together with the defaults using `angular.extend()`. This allows you to override the defaults selectively, if you wish.
 
 When setting `clearOnBlurPlaceholder` to `true`, it will show the placeholder text instead of the empty mask. It requires the `ui-mask-placeholder` attribute to be set on the input to display properly.
 
+If the `escChar` (\\ by default) is encountered in a mask, the next character will be treated as a literal and not a mask definition key.  To disable the `escChar` feature completely, set `escChar` to `null`.
+
 #### Global customization
 In addition to customizing behaviors for a specific element, you can also customize the behaviors globally. To do this, simply use the `uiMaskConfig` provider in your app configuration. Example:
 

src/mask.js

@@ -10,6 +10,7 @@ angular.module('ui.mask', [])
             },
             clearOnBlur: true,
             clearOnBlurPlaceholder: false,
+            escChar: '\\',
             eventsToHandle: ['input', 'keyup', 'click', 'focus'],
             addDefaultPlaceholder: true
         })
@@ -373,9 +374,17 @@ angular.module('ui.mask', [])
                                             numberOfOptionalCharacters = 0,
                                             splitMask = mask.split('');
 
+                                    var inEscape = false;
                                     angular.forEach(splitMask, function(chr, i) {
-                                        if (linkOptions.maskDefinitions[chr]) {
-
+                                        if (inEscape) {
+                                            inEscape = false;
+                                            maskPlaceholder += chr;
+                                            characterCount++;
+                                        }
+                                        else if (linkOptions.escChar === chr) {
+                                            inEscape = true;
+                                        }
+                                        else if (linkOptions.maskDefinitions[chr]) {
                                             maskCaretMap.push(characterCount);
 
                                             maskPlaceholder += getPlaceholderChar(i - numberOfOptionalCharacters);

test/maskSpec.js

@@ -379,6 +379,98 @@ describe("uiMask", function () {
     });
   });
 
+  describe("escChar", function () {
+    it("should escape default mask definitions", function() {
+      var escapeHtml = "<input name='input' ng-model='x' ui-mask='{{mask}}'>",
+          input  = compileElement(escapeHtml);
+      scope.$apply(function() {
+        scope.x = '';
+        scope.mask = '\\A\\9\\*\\?*';
+      });
+      expect(input.attr("placeholder")).toBe("A9*?_");
+      input.val("a").triggerHandler("input");
+      expect(input.val()).toBe("A9*?a");
+    });
+    it("should not confuse entered values with escaped values", function() {
+      var escapeHtml = "<input name='input' ng-model='x' ui-mask='{{mask}}'>",
+          input  = compileElement(escapeHtml);
+      scope.$apply(function() {
+        scope.x = '';
+        scope.mask = '\\A\\9\\*\\?****';
+      });
+      expect(input.attr("placeholder")).toBe("A9*?____");
+      input.val("A9A9").triggerHandler("input");
+      expect(input.val()).toBe("A9*?A9A9");
+    });
+    it("should escape custom mask definitions", function() {
+      scope.options = {
+        maskDefinitions: {
+          "Q": /[Qq]/
+        }
+      };
+      var input  = compileElement(inputHtml);
+      scope.$apply(function() {
+        scope.x = '';
+        scope.mask = '\\QQ';
+      });
+      expect(input.attr("placeholder")).toBe("Q_");
+      input.val("q").triggerHandler("input");
+      expect(input.val()).toBe("Qq");
+    });
+    it("should escape normal characters", function() {
+      var input  = compileElement(inputHtml);
+      scope.$apply(function() {
+        scope.x = '';
+        scope.mask = '\\W*';
+      });
+      expect(input.attr("placeholder")).toBe("W_");
+      input.val("q").triggerHandler("input");
+      expect(input.val()).toBe("Wq");
+    });
+    it("should escape itself", function() {
+      var escapeHtml = "<input name='input' ng-model='x' ui-mask='{{mask}}'>",
+          input  = compileElement(escapeHtml);
+      scope.$apply(function() {
+        scope.x = '';
+        scope.mask = '\\\\*';
+      });
+      scope.$apply("x = ''");
+      scope.$apply("mask = '\\\\\\\\*'");
+      expect(input.attr("placeholder")).toBe("\\_");
+      input.val("a").triggerHandler("input");
+      expect(input.val()).toBe("\\a");
+    });
+    it("should change the escape character", function() {
+      scope.options = {
+        escChar: '!',
+        maskDefinitions: {
+          "Q": /[Qq]/
+        }
+      };
+      var input  = compileElement(inputHtml);
+      scope.$apply(function() {
+        scope.x = '';
+        scope.mask = '\\!A!9!*!Q!!!W*';
+      });
+      expect(input.attr("placeholder")).toBe("\\A9*Q!W_");
+      input.val("a").triggerHandler("input");
+      expect(input.val()).toBe("\\A9*Q!Wa");
+    });
+    it("should use null to mean no escape character", function() {
+      scope.options = {
+        escChar: null,
+      };
+      var input  = compileElement(inputHtml);
+      scope.$apply(function() {
+        scope.x = '';
+        scope.mask = '\\!A!9!*!!*';
+      });
+      expect(input.attr("placeholder")).toBe("\\!_!_!_!!_");
+      input.val("a").triggerHandler("input");
+      expect(input.val()).toBe("\\!a!_!_!!_");
+    });
+  });
+
   describe("placeholders", function () {
     it("should have default placeholder functionality", function() {
       var input = compileElement(inputHtml);