Pattern attribute / misc

1.  Pattern mode deactivates events and Luhn validation
2.  Improvements to the QUnit and demo pages
3.  Updated README

Author: kloverde

CHANGELOG.md

@@ -11,7 +11,7 @@
 # Release 1.2 (December 28, 2016)
 
 * Now confirmed to work on mobile!  See README.md for a list of tested browsers.
-* Change to event firing:  validation success & validation failure events were firing pre-blur with `preventInvalidInput` enabled.  This is contrary to the documentation, which states that these events do not fire in that scenario.  The documentation reflected the intended behavior; the events no longer fire in this scenario.
+* Change to event firing:  validation success & validation failure events were firing pre-blur with `preventInvalidInput` enabled.  This was contrary to the documentation, which stated that these events do not fire in that scenario.  The documentation reflected the intended behavior; the events no longer fire in this scenario.
 * Added credit card types (AMEX, VISA, MasterCard, Discover), plus a credit card type encompassing each of these types
 * Added a [Luhn](https://en.wikipedia.org/wiki/Luhn_algorithm) type
 * Updated and redesigned the demo page

README.md

@@ -1,11 +1,15 @@
 RestrictedTextField v1.4 (UPCOMING RELEASE)
 ========================
 
-# You've stumbled upon a development branch.  Have a look around if you want, but only use code that's posted on the releases page.
-
 See LICENSE for this software's licensing terms.
 
-RestrictedTextField is a jQuery plugin which uses regular expressions to validate and control input to HTML text fields.  Using 38 built-in types or types you define yourself, it allows you to suppress invalid keystrokes or to allow them into the field but be flagged incorrect.  Validation is performed on keystroke, paste and blur.
+RestrictedTextField is a jQuery plugin which uses regular expressions to validate and control input to HTML text fields.  RestrictedTextField has 38 built-in types and also allows you to define your own types.  Validation is performed on keystroke, paste and blur.
+
+You might not need this plugin for your purposes - the HTML5 `pattern` attribute provides most of the same functionality.  If, however, you must support browsers that don't support `pattern`, or if you want to make use of RestrictedTextField's additional features, then perhaps it might be a good fit for you.
+
+The biggest difference between this plugin and `pattern` is that RestrcitedTextField allows you to (optionally) suppress invalid keystrokes in real time, rather than allow them into the field to fail validation later.  If you do want to allow invalid characters in, however, you have that option.
+
+If you're only interested in `pattern`-based validation, you might still find RestrictedTextField useful.  It provides the ability to disable its own validation implementation and use `pattern` exclusively.  In this scenario, you'd just be using RestrictedTextField as a repository of pre-written regular expressions.  Although you could just copy the regular expressions from the source code, you might find it easier on code maintenance to not be dropping multiple copies of the same regular expressions into your project.
 
 
 ## Features
@@ -53,7 +57,7 @@ RestrictedTextField is a jQuery plugin which uses regular expressions to validat
 32.  MasterCard
 33.  Discover
 34.  Credit Card (combines all of the individual credit card types above)
-35.  [Luhn-valid](https://en.wikipedia.org/wiki/Luhn_algorithm) numbers
+35.  [Luhn](https://en.wikipedia.org/wiki/Luhn_algorithm) numbers - note:  if used with `pattern` mode enabled, successful validation is essentially meaningless.
 36.  US zip code (5 digits)
 37.  US zip code suffix (1-4 digits)
 38.  US zip code (5 digits with optional suffix)
@@ -86,7 +90,7 @@ RestrictedTextField is a jQuery plugin which uses regular expressions to validat
 
 Each credit card type enforces prefixes and length as specified by https://en.wikipedia.org/wiki/Payment_card_number in December, 2016.  [Luhn validation](https://en.wikipedia.org/wiki/Luhn_algorithm) is also performed.
 
-If you prefer not to use strictly-enforced credit card types (is Wikipedia correct, and is RestrictedTextField up-to-date?), you can use the Luhn type instead.  It performs basic mathematical validation, but it can only tell you that a value is invalid, not that a value IS valid.  Full validation would then be shifted to your payment card processor in the form of a rejected transaction -- or, if they provide an API for validation, you could use that.
+If you prefer not to use strictly-enforced credit card types (is Wikipedia correct, and is RestrictedTextField up-to-date?), you can use the Luhn type instead.  It performs basic mathematical validation, but that will only tell you that a credit card number is invalid, not that it IS valid.  Full validation would then be shifted to your payment card processor in the form of a rejected transaction -- or, if they provide an API for validation, you could use that, too.
 
 
 ## Configuration
@@ -96,12 +100,12 @@ If you prefer not to use strictly-enforced credit card types (is Wikipedia corre
 | `type`   | Text field type.  This is a required setting. | string | alpha, upperAlpha, lowerAlpha, alphaSpace, upperAlphaSpace, lowerAlphaSpace, alphanumeric, upperAlphanumeric, lowerAlphanumeric, alphanumericSpace, upperAlphanumericSpace, lowerAlphanumericSpace, int, positiveInt, negativeInt, strictInt, strictPositiveInt, strictNegativeInt, float, positiveFloat, negativeFloat, strictFloat, strictPositiveFloat, strictNegativeFloat, money, positiveMoney, negativeMoney, accountingMoney, negativeAccountingMoney, americanExpress, visa, masterCard, discover, creditCard, luhnNumber, usZip, usZip5, usZipSuffix | null |
 | `preventInvalidInput` | When enabled, invalid keystrokes are ignored (the value of the text field is not updated).  When disabled, invalid keystrokes are not ignored. | boolean | true/false | true |
 | `logger` | An optional callback function for logging.  If you want to enable logging, provide a function and then do whatever you wish with the message. | function | A function accepting the log message as a string argument | undefined |
-| `usePatternAttr` | When enabled, sets the HTML5 `pattern` attribute on the input field.  Check [caniuse.com](http://caniuse.com/#search=pattern) for browser support. | boolean | true/false | false |
+| `usePatternAttr` | When enabled, sets the HTML5 `pattern` attribute on the input field.  Check [caniuse.com](http://caniuse.com/#search=pattern) for browser support.  When pattern mode is enabled, RestrictedTextField does not fire its own validation events, nor does it perform Luhn validation on credit card types or the Luhn type.  Pattern mode is meant to be pure HTML5 behavior.  The only part of RestrictedTextField functionality that remains active is the automatic formatting of money types.| boolean | true/false | false |
 
 
 ## Events
 
-These events are fired based on the state of the text field.
+These events are fired based on the state of the text field, but only if `usePatternAttr` is disabled.
 
 | Event name        | Description                                                     |
 | ------------------| ----------------------------------------------------------------|

demo/demo.css

@@ -21,7 +21,7 @@ input.inputIgnored {
 }
 
 input.invalid {
-   border: 2px solid #FF0000;
+   border: 2px solid #FC8D3D;
 }
 
 input[type=submit] {

demo/demo.html

@@ -53,16 +53,9 @@ <h1>Test Drive</h1>
       <div id="instructions">
          <p>Here you can test drive RestrictedTextField's built-in types.  Select a type from the dropdown menu and use the checkboxes to further customize the configuration.</p>
 
-         <p>Regardless of the state of the &quot;Discard invalid keystrokes&quot; checkbox, validation is always performed on each keystroke and on blur.</p>
+         <p>If the <a href="http://caniuse.com/#search=pattern" target="_blank">pattern</a> attribute is disabled, RestrictedTextField uses its own validation implementation:  validation is performed on each keystroke and on blur, and is done regardless of the state of the &quot;Discard invalid keystrokes&quot; checkbox.  Event listeners flash the text field's border when a keystroke is discarded, and colors its border solid orange if an invalid character makes it into the field.</p>
 
-         <p>This demo declares event listeners that flash the text field's border when a keystroke is discarded, and colors its border solid red if an invalid character is allowed into the field.</p>
-
-         <p>
-            To better demonstrate the support of the <a href="http://caniuse.com/#search=pattern" target="_blank">pattern</a> attribute, the event listener which watches for invalid text
-            inside the field will be disabled when the pattern attribute is in use.  You'll notice that with the pattern attribute, the browser's built-in behavior alters the field's border
-            color, but only on blur.  Notice how this differs from RestrictedTextField's approach when the pattern attribute isn't turned on.  Note:  for types which require validation beyond
-            a regular expression (for example, a credit card number), the pattern attribute won't provide complete validation; you'll want to heed RestrictedTextField's validation events.
-         </p>
+         <p>Note that if using the pattern attribute, you will lose Luhn validation on credit card types and the Luhn type, as Luhn calculations cannot be performed with regular expressions.  Patten mode is meant to be a pure HTML5 validation.</p>
 
          <p>The demo initializes RestrictedTextField with a logging function, so you can open your browser's console to view events in real time.</p>
       </div>

demo/demo.js

@@ -24,7 +24,7 @@
          if( this.value !== "Select Type" ) {
             createField();
          } else {
-            $( "#fieldContainer" ).html( "" );
+            fieldContainer.hide();
             $( "#code" ).html( "" );
          }
       } );
@@ -42,9 +42,12 @@
       var fieldType = document.getElementById( "fieldTypes" ).value;
       var preventInvalid = $( "#preventInvalid" ).is( ":checked" );
       var usePatternAttr = $( "#usePatternAttr" ).is( ":checked" );
-      var fieldContainer = document.getElementById( "fieldContainer" );
+      var fieldContainer = $( "#fieldContainer" );
       var field = document.createElement( "input" );
       var submit = document.createElement( "input" );
+      var code = $( "#code" );
+
+      var fieldCreated = false;
 
       field.type = "text";
       field.id = "field";
@@ -53,9 +56,9 @@
       submit.type = "submit";
       submit.value = "Submit";
 
-      fieldContainer.innerHTML = descrMap[fieldType] + "<br/><br/>";
-      fieldContainer.appendChild( field );
-      fieldContainer.appendChild( submit );
+      fieldContainer.html( descrMap[fieldType] + "<br/><br/>" );
+      fieldContainer.append( field );
+      fieldContainer.append( submit );
 
       if( !usePatternAttr ) {
          $( submit ).on( "click", function(event) {
@@ -68,47 +71,60 @@
 
       field = $( field );
 
-      field.restrictedTextField( {
-         type : fieldType,
-         preventInvalidInput : preventInvalid,
-         usePatternAttr : usePatternAttr,
-         logger : log
-      } );
+      try {
+         field.restrictedTextField( {
+            type : fieldType,
+            preventInvalidInput : preventInvalid,
+            usePatternAttr : usePatternAttr,
+            logger : log
+         } );
 
-      field.on( "inputIgnored", function(event) {
-         var jqThis = $( this );
+         fieldCreated = true;
+      } catch( e ) {
+         fieldContainer.hide();
+         code.hide();
+         alert( e );
+      }
 
-         jqThis.removeClass( "invalid" );
-         jqThis.removeClass( "inputIgnored" );
+      if( fieldCreated ) {
+         fieldContainer.show();
+         code.show();
 
-         flashBorder( jqThis, "inputIgnored", 3, 150 );
-      } )
-      .on( "validationFailed", function(event) {
-         if( !usePatternAttr ) {
+         field.on( "inputIgnored", function(event) {
             var jqThis = $( this );
+
+            jqThis.removeClass( "invalid" );
             jqThis.removeClass( "inputIgnored" );
-            jqThis.addClass( "invalid" );
-         }
-      } )
-      .on( "validationSuccess", function(event) {
-         var jqThis = $( this );
 
-         jqThis.removeClass( "inputIgnored" );
-         jqThis.removeClass( "invalid" );
-      } );
+            flashBorder( jqThis, "inputIgnored", 3, 150 );
+         } )
+         .on( "validationFailed", function(event) {
+            if( !usePatternAttr ) {
+               var jqThis = $( this );
+               jqThis.removeClass( "inputIgnored" );
+               jqThis.addClass( "invalid" );
+            }
+         } )
+         .on( "validationSuccess", function(event) {
+            var jqThis = $( this );
+
+            jqThis.removeClass( "inputIgnored" );
+            jqThis.removeClass( "invalid" );
+         } );
 
-      $( "#code" ).html(
-         "<code>\n" +
-         "$( \"#field\" ).restrictedTextField( {<br/>\n" +
-         "&nbsp;&nbsp;&nbsp;type : \"" + fieldType + "\",<br/>\n" +
-         "&nbsp;&nbsp;&nbsp;preventInvalidInput : " + preventInvalid + ",<br/>\n" +
-         "&nbsp;&nbsp;&nbsp;usePatternAttr : " + usePatternAttr + ",<br/>\n" +
-         "&nbsp;&nbsp;&nbsp;logger : log<br/>\n" +
-         "} );<br/>\n" +
-         "</code>\n"
-      );
-
-      field.focus();
+         code.html(
+            "<code>\n" +
+            "$( \"#field\" ).restrictedTextField( {<br/>\n" +
+            "&nbsp;&nbsp;&nbsp;type : \"" + fieldType + "\",<br/>\n" +
+            "&nbsp;&nbsp;&nbsp;preventInvalidInput : " + preventInvalid + ",<br/>\n" +
+            "&nbsp;&nbsp;&nbsp;usePatternAttr : " + usePatternAttr + ",<br/>\n" +
+            "&nbsp;&nbsp;&nbsp;logger : function( msg ) { do stuff }<br/>\n" +
+            "} );<br/>\n" +
+            "</code>\n"
+         );
+
+         field.focus();
+      }
    }
 
    function flashBorder( jqField, cssClass, times, delayMillis ) {