Skip to content

Latest commit

 

History

History
160 lines (155 loc) · 13.9 KB

README.md

File metadata and controls

160 lines (155 loc) · 13.9 KB
Raw

#jTAC: JavaScript Types and Conditions

jTAC is a JavaScript library for enhancing data entry user interfaces. It expands jquery-validate, adding new rules and features. It also includes several jquery-ui widgets, including the DataTypeEditor, DateTextBox, and Calculator. jTAC is not jquery specific. You can use it in all of your JavaScript libraries.

Underlying validation are three tools that you will want to use in other situations: TypeManagers, Conditions, and Connections.

  • TypeManagers understand data types, like integers, dates, currencies, and email addresses. They provide parsers to convert strings into the native type and report errors when conversion fails. As a result, validation delegates significant work to TypeManagers.
  • Conditions are the actual validation rules, like “compare to value”, “range”, and “text length”.
  • Connections are used to access data from elements on the page or other sources. They work with HTML form elements, custom widgets that are composed of several form elements (like a checkbox list) or use API calls to get a value, and even your custom calculations that return a value. Conditions use Connections for all their data retrieval.

While jQuery is obviously supported, the jTAC core does not use jQuery, making its classes useable in other JavaScript frameworks. The jQuery tools are merely fully realized uses of these classes. It’s these classes that will contribute most to your application.

Getting started

  • Download jTAC using the Downloads button on the jTAC home page.
  • Add the contents of the Add contents to your site folder, perhaps in its own script folder.
  • Open the Users Guide.pdf and dig in. Read the overviews for TypeManagers, Conditions, and Connections because you will be using them to setup your validation rules.
  • If you want to customize the jTAC library, use the Development Site. It hosts jsunit test files.

The remaining text is an overview. If you want to dig into the details, grab the User's Guide now.

Improving jquery-validate's rules

jTAC was created when two key things collided: the author of a popular validation framework attempted to use jquery-validate v1.8. He was quickly frustrated by how inflexible the rules were. His existing solution already used the concepts of TypeManagers, Conditions, and Connections to build powerful validation rules. jTAC is his remedy. Let’s take a look at how jquery-validate’s rules are designed…

The rules within jquery-validate are limited to handling single cases. Take the Range rule that comes with query-validate. 

range: function( value, element, param ) {
  return this.optional(element) || ( value >= param[0] && value <= param[1] );
}

It evaluates a number against a minimum and maximum value. If you want the range to work with dates, you must create a new rule. 

dateRange: function( value, element, param ) {
  var min = convertTextToDate(param[0]);  // expected: "yyyy-MM-dd"
  var max = convertTextToDate(param[1]);
  var val = convertTextToDate(value);
  return this.optional(element) || ( val >= min && val <= min );
}

That convertTextToDate() function is a big deal, as it’s a parser that you have to write. You can write a simple date parser, but if you are dealing with localization or real-world user input, parsers can get pretty fancy.

Even if you create the new rule, it may not work with all ui-widgets. For example, your new DateRange will work with a textbox, but not a calendar widget, which requires an API call to access its value.

calendarDateRange: function( value, element, param ) {
   var min = convertTextToDate(param[0]); // expected: "yyyy-MM-dd"
   var max = convertTextToDate(param[1]);
   var val = element.calendar("getDate");  // value param is ignored
   return this.optional(element) || ( val >= min && val <= min );
}

A better way is to create a rule for ranges that handles any data type and source of data using TypeManagers and Connections. The following is pseudocode.

advrange: function( value, element, param ) {
   var tm = jTAC.create(param.datatype); // creates a TypeManager
   var conn = jTAC.connectionResolver(param.elementId); // creates a Connection
   value = tm.toValue(value);      // ensure it is in the native type
   var min = tm.toValueNeutral(param.minimum); // ensure native type
   var max = tm.toValueNeutral(param.maximum);
   return this.optional(element) ||
    ((tm.compare(value, min) >= 0) && (tm.compare(value, max) <= 0));
}

The above code is similar to what you will find in jTAC’s Condition object for the Range rule.

Here is a textbox setup using jTAC for its rules using unobtrusive setup:

<input type='text' id='textbox1' name='textbox1' 
   data-val="true"
   data-jtac-datatype="date" 
   data-val-datatypecheck="Enter a valid date"
   data-val-advrange="Value must be between {MINIMUM} and {MAXIMUM}"
   data-val-advrange-json="{'minimum': '2000-01-01', 'maximum'='2009-12-31'}" />

Note: All data-val properties are defined according to jquery-validate. Any of jTAC’s rules are the Condition name, except “required” and “range” which conflict with the native rules of the same name. Any properties to set on the Condition are assigned using JSON to the data-val-rulename-json attribute, as shown above.

You can also see here a second aspect of the enhanced jquery-validate framework: clear tokens in the error messages. Each validation rule defined by jTAC can define a default error message and convert any tokens you like.

Other improvements to jquery-validate

  • New rules including one that lets you built other rules into a single Boolean expression
  • Rules can operate on multiple data types. Includes support for: integer, float, currency, percent, date, time of day, duration, month+year, and day+month. You can expand and customize this.
  • Rules have properties to let you customize their behavior. For example, the rule for regular expression parsing includes properties to indicate “ignore case sensitive”, “global”, and “multiline” (the 3 options passed into the regular expression parser.)
  • Support for dependencies while in unobtrusive validation.
  • Build powerful dependencies without writing your own functions. Define any Condition object on the depends property of the param property for the validation rule.
  • Validation can use data from multiple fields. While the Compare Two Elements rule is obvious, also consider the simple Required rule. jTAC’s version allows you to define a list of elements to require, and then require one from the list, all, one or all, etc.
  • Validation can use data from fields that need to be accessed by API. Take a calendar widget that holds a selected date value. It may not have an <input> to host that value. Instead, it offers an API function like $("#calendar").getDate().
  • Powerful parsers to convert text into a native type. They support localized formats of dates, times, and numbers.
  • You don’t have to create a new validation rule for each string-based data type, like Phone Number and Email Address. There are TypeManagers defined to handle data types. So reuse the “DataTypeCheck” validation rule, assigning its datatype property to the appropriate TypeManager.
  • Validation can be done on calculated values, such as the result of adding two TextBoxes containing integers, without creating a new rule.
  • Can define the form’s validation options when using unobtrusive validation.
  • All strings shown to the user can be localized.
  • Expands how tokens work within error messages. They use clear words like {COUNT} and {MINIMUM} instead of {1} and {2}.
  • Tokens can be updated at runtime with information calculated during validation, such as {COUNT} can show the current number of characters typed.
  • The {LABEL} token can display the field’s label. Validators automatically know that <label for="textbox"> tags are the source of error messages. In addition, you can assign the data-msglabel attribute to the textbox with the appropriate label.
  • Highlight fields feature supports validation on multiple elements. For example, when the Compare Two Elements rule reports an error, both textboxes have their style sheet class changed.
  • Highlight fields feature supports changing the style sheet on the field label or a containing element without you writing code. Labels work automatically. Containing elements only need the data-jtac-valinputs attribute.
  • When using the highlight fields feature, individual inputs, labels, and containing elements can override the default style sheet classes on a case-by-case basis. Just define the alternative style sheet class in the data-jtac-errorclass attribute of the element.

More benefits of using jTAC

  • Localization supported for dates, times, and numbers. In addition to the built-in localization rules, it allows plugging in third party localization libraries. jquery-globalize support is already included as a plug in.
  • Multilingual support of text shown to the user, such as validation error messages.
  • TypeManagers convert strings to native types using a parser. Parsers are often very specialized. So jTAC provides plug-in parsers and includes two very powerful powers for date and times.
  • The entire framework is built for expansion by using classes. You can develop your own classes using inheritance. Extensive documentation is both in this PDF and inline. You may actually appreciate using jTAC’s class building framework for your own classes that are not used with jTAC.
  • Debugging is made easier by using the browser’s Console view where jTAC writes its error messages.
  • jTAC is open source and community driven. Submit your ideas and modifications at https://github.com/plblum/jtac.
  • The author, Peter Blum, is also the author of a successful commercial ASP.NET control suite, “Peter’s Data Entry Suite”. That product is similar to jTAC; it handles client-side validation and extends the features of textboxes. He has rolled in much of the knowledge learned from customers over a 10+ year period. Special cases are abound, whether is an option for parsing or dealing with an idiosyncrasy of a browser.