LogoLogo
HomeDiscourseBlogDiscord
  • Introduction
  • Introduction
    • Quick start
    • Aurelia for new developers
    • Hello world
      • Creating your first app
      • Your first component - part 1: the view model
      • Your first component - part 2: the view
      • Running our app
      • Next steps
  • Templates
    • Template Syntax
      • Attribute binding
      • Event binding
      • Text interpolation
      • Template promises
      • Template references
      • Template variables
      • Globals
    • Custom attributes
    • Value converters (pipes)
    • Binding behaviors
    • Form Inputs
    • CSS classes and styling
    • Conditional Rendering
    • List Rendering
    • Lambda Expressions
    • Local templates (inline templates)
    • SVG
  • Components
    • Component basics
    • Component lifecycles
    • Bindable properties
    • Styling components
    • Slotted content
    • Scope and context
    • CustomElement API
    • Template compilation
      • processContent
      • Extending templating syntax
      • Modifying template parsing with AttributePattern
      • Extending binding language
      • Using the template compiler
      • Attribute mapping
  • Getting to know Aurelia
    • Routing
      • @aurelia/router
        • Getting Started
        • Creating Routes
        • Routing Lifecycle
        • Viewports
        • Navigating
        • Route hooks
        • Router animation
        • Route Events
        • Router Tutorial
        • Router Recipes
      • @aurelia/router-lite
        • Getting started
        • Router configuration
        • Configuring routes
        • Viewports
        • Navigating
        • Lifecycle hooks
        • Router hooks
        • Router events
        • Navigation model
        • Transition plan
    • App configuration and startup
    • Enhance
    • Template controllers
    • Understanding synchronous binding
    • Dynamic composition
    • Portalling elements
    • Observation
      • Observing property changes with @observable
      • Effect observation
      • HTML observation
      • Using observerLocator
    • Watching data
    • Dependency injection (DI)
    • App Tasks
    • Task Queue
    • Event Aggregator
  • Developer Guides
    • Animation
    • Testing
      • Overview
      • Testing attributes
      • Testing components
      • Testing value converters
      • Working with the fluent API
      • Stubs, mocks & spies
    • Logging
    • Building plugins
    • Web Components
    • UI virtualization
    • Errors
      • 0001 to 0023
      • 0088 to 0723
      • 0901 to 0908
    • Bundlers
    • Recipes
      • Apollo GraphQL integration
      • Auth0 integration
      • Containerizing Aurelia apps with Docker
      • Cordova/Phonegap integration
      • CSS-in-JS with Emotion
      • DOM style injection
      • Firebase integration
      • Markdown integration
      • Multi root
      • Progress Web Apps (PWA's)
      • Securing an app
      • SignalR integration
      • Strongly-typed templates
      • TailwindCSS integration
      • WebSockets Integration
      • Web Workers Integration
    • Playground
      • Binding & Templating
      • Custom Attributes
        • Binding to Element Size
      • Integration
        • Microsoft FAST
        • Ionic
    • Migrating to Aurelia 2
      • For plugin authors
      • Side-by-side comparison
    • Cheat Sheet
  • Aurelia Packages
    • Validation
      • Validation Tutorial
      • Plugin Configuration
      • Defining & Customizing Rules
      • Architecture
      • Tagging Rules
      • Model Based Validation
      • Validation Controller
      • Validate Binding Behavior
      • Displaying Errors
      • I18n Internationalization
      • Migration Guide & Breaking Changes
    • i18n Internationalization
    • Fetch Client
      • Overview
      • Setup and Configuration
      • Response types
      • Working with forms
      • Intercepting responses & requests
      • Advanced
    • Event Aggregator
    • State
    • Store
      • Configuration and Setup
      • Middleware
    • Dialog
  • Tutorials
    • Building a ChatGPT inspired app
    • Building a realtime cryptocurrency price tracker
    • Building a todo application
    • Building a weather application
    • Building a widget-based dashboard
    • React inside Aurelia
    • Svelte inside Aurelia
    • Synthetic view
    • Vue inside Aurelia
  • Community Contribution
    • Joining the community
    • Code of conduct
    • Contributor guide
    • Building and testing aurelia
    • Writing documentation
    • Translating documentation
Powered by GitBook
On this page
  • Validation trigger
  • Explicit validation controller

Was this helpful?

Export as PDF
  1. Aurelia Packages
  2. Validation

Validate Binding Behavior

PreviousValidation ControllerNextDisplaying Errors

Last updated 1 year ago

Was this helpful?

The validate binding behavior, as the name suggests, adds the validation behavior to a property binding. In other words, it "mark"s the associated property binding as a target for validation by registering the binding to the validation controller.

This is how the validation controller comes to know of the bindings that need to be validated when validationController.validate() method is called.

You must have noticed plenty examples of the validate binding behavior in the demos so far. For completeness, this can be used as follows.

<html-element target.bind="source & validate:[trigger]:[validationController]:[rules]"></html-element>

Note that the binding behavior has three optional arguments: trigger, validation controller, and rules.

Validation trigger

This dictates when the validation is performed. The valid values are as follows.

  • manual: Use the validation controller's validate() method to validate all bindings.

  • blur: Validate the binding when the binding's target element fires a DOM "blur" event.

  • focusout: Validate the binding when the target element fires a DOM "focusout" event. This is useful when the actual input is wrapped in a custom element, and the validate binding behavior is used on the custom element. In that case, the blur trigger does not work as the blur event does not bubble. See the difference in action below.

  • change: Validate the binding when the source property is updated (usually triggered by some change in view).

  • changeOrBlur: Validate the binding when the binding's target element fires a DOM "blur" event and when the source property is updated.

  • changeOrFocusout: Validate the binding when the binding's target element fires a DOM "focusout" event and when the source property is updated.

There is an important point to note about the changeOrEVENT triggers. The change-triggered validation is ineffective till the associated property is validated once, either by manually calling ValidationController#validate or by event-triggered (blur or focusout) validation. This prevents showing a validation failure message immediately in case of an incomplete input, which might be the case if validation is triggered for every change.

Note the distinction made between incomplete and invalid input. The event-triggered validation is ineffective until the property is dirty, i.e. any changes were made. This prevents showing a validation failure message when there is a blur or focusout event without changing the property. This behavior delays bugging the user and "reward"s eagerly.

The examples above show an explicit usage of trigger. However, this is an optional value; when used, it overrides the default trigger configured. The default trigger is used for that instance when the value is omitted. The default validation trigger is focusout, although it can be changed using the DefaultTrigger registration customization option.

import { ValidationHtmlConfiguration, ValidationTrigger } from '@aurelia/validation-html';
import Aurelia from 'aurelia';

Aurelia
  .register(ValidationHtmlConfiguration.customize((options) => {
    // customization callback
    options.DefaultTrigger = ValidationTrigger.changeOrFocusout;
  }))
  .app(component)
  .start();

Explicit validation controller

However, an instance of validation can be explicitly bound to the binding behavior, using the positional argument. This is useful when you use multiple instances of validation controllers to perform a different validation set.

In the example below, there are two injected controllers and the property person.age the validationController2 is used. Playing with the example, you can see that the person.age does not get validated by the scoped validation controller instance.

The binding behavior, by default, registers the binding to the closest (in terms of dependency injection container) available instance of the validation controller. Note that the validation controller instance can be made available for the scope using the newInstanceForScope resolver (refer for more details). If no instance of validation controller is available, it throws an error.

Injecting a controller instance