laxar-input-control

An AngularJS directive that adds powerful interactive validation to form elements, for LaxarJS widgets.

This directive can be used in combination with ngModel to enrich a simple input field with type information in order to perform automatic syntactical validation, parsing and formatting. Additionally it is possible to add semantic validators based on simple AngularJS directives using a simple interface of a controller defined within the input directive. Whenever there is an error (be it semantic or syntactic) a tooltip is shown as long as the input field is focused. Additionally the input field and its label (associated through nesting or by for+id attribute) receives the class ax-error.

Installation

To use this control you should install it into your LaxarJS v2 project:

npm install --save laxar-input-control

This control only works for LaxarJS widget that are targeting AngularJS v1.

Usage

Add the axInput directive to your form controls, along with ngModel. Supported value types for ax-input are string, decimal, integer, date and time.

Examples

A required decimal input with maximum value:

<input ng-model="someDecimal"
       ax-input="decimal"
       ax-input-maximum-value="100000"
       ax-input-required="true">

A date input with value range and date picker UI. The latter requires the laxar-date-picker-control:

<input ng-model="someDate"
       ax-input="date"
       ax-input-range="'2010-01-02, 2014-03-01'"
       ax-input-required="true"
       ax-date-picker>

A decimal input with special formatting:

<input ng-model="someDecimal"
       ax-input="decimal"
       ax-input-formatting="{groupingSeparator: '_', decimalPlaces: 4}">

Builtin Validation Directives

Basic semantic validation directives that are already available are:

• ax-input-required (all types): Requires a value to be entered into the input field

• ax-input-maximum-value="$maximum" (all except string): requires the value to be below or equal to $maximum. For dates the value 'now' can also be used.

• ax-input-minimum-value="$minimum" (all except string): requires the value to be greater or equal to $minimum. For dates also the value 'now' can be used.

• ax-input-range="$minimum, $maximum" (all except string): requires the value to be greater or equal to $minimum AND below or equal to $maximum

• ax-input-maximum-length="$maximumLength" (string only): requires the string's length to be below or equal to $maximumLength

• ax-input-minimum-length="$minimumLength" (string only): requires the string's length to be greater than or equal to $minimumLength

• ax-input-tooltip-placement (all types): if set, this string (left/right/bottom/top) is forwarded to the bootstrap tooltip component to determine tooltip placement on screen. Otherwise, the position is determined automatically depending on the type of form element and its position on screen (left/right for select boxes, top/bottom for other controls).

• ax-input-tooltip-on-parent: if set, the tooltip is attached to the parent of the form control.

• ax-input-display-errors-immediately="$immediately": If $immediately evaluates to true, validation errors are presented to the user immediately by CSS styling and tooltip. Otherwise, errors are only shown when the field has been changed (ngModelController.$dirty) or after the event axInput.validate has been received. The default is true but may be changed to false in future major releases. It can be changed using the configuration controls.laxar-input-control.displayErrorsImmediately.

  The complementary event axInput.setPristine may be broadcast to reset the (visual) validation state. It has the same effect as calling $setPristine() on the AngularJS form controller or on the model controller associated with an axInput directive.

Writing a custom semantic validator is as easy as writing a directive requiring the axInputController and calling addSemanticValidator with the validator function as first argument and an error message generator function as second argument. A look at the included semantic validators should be sufficient to know how this works.

Formatting of the displayed value can be controlled using the ax-input-formatting attribute. This takes an object having the following entries:

• groupingSeparator (default: .): Grouping seperator for decimal and integer values
• decimalSeparator (default: ,): Decimal separator for decimal values
• decimalPlaces (default: 2): Number of decimal places to display. Applies rounding if necessary.
• decimalTruncation (default: FIXED): How to treat insignificant decimal places (trailing zeros):
  • FIXED: uses a fraction length of exactly decimalPlaces, padding with zeros
  • BOUNDED: uses a fraction length up to decimalPlaces, no padding
  • NONE: unbounded fraction length (only limited by numeric precision), no padding
• dateFormat (default: MM/DD/YYYY): Format for date values
• dateTwoDigitYearWrap (default: 68): the two digit year value where below or equal 20xx is assumed and above 19xx
• timeFormat: (default: HH:mm): Format for time values
• dateFallbackFormats: an array of formats to try parsing the value when using dateFormat fails
• timeFallbackFormats: an array of formats to try parsing the value when using timeFormat fails

Formats for date and time are given in Moment.js syntax.

Custom Validation Messages

The axInput control comes with a default set of validation messages for its builtin validators, available for german (de) and english (en and en_GB) localization. Although we may add some more localizations in the future (hey, this could be the chance for your first contribution ;-)) it may always be necessary to use custom validation messages in a widget.

This can be achieved by using the axInputValidationMessage directive. Its value can be any valid AngularJS expression, that evaluates to either a map defining translations for any of the keys found in the provided messages.json file, or a single string that should be used for any kind of validation error.

Example: Using a simple constant within a template

<input ng-model="value"
       ax-input="decimal"
       ax-input-validation-message="'Please insert a correct decimal number.'">

Example: Binding to the scope of e.g. a widget

<input ng-model="value"
       ax-input="decimal"
       ax-input-validation-message="validationMessages">

$scope.value = 13;
$scope.validationMessages = {
   SYNTAX_TYPE_DECIMAL: 'Insert a valid decimal number!',
   // ... more messages
};