Tesserae - Validator

Validator

Description

The Validator is a utility component designed to orchestrate and centralize the validation of multiple UI elements. It registers components that implement validation, tracks which of them the user has interacted with, and triggers visual state updates based on their current validity. Use this component when you need to validate forms or groups of input components in a fluent and efficient manner.

Usage

Instantiate the Validator using the static helper from Tesserae.UI. Register your UI components (such as TextBox or Dropdown) with custom validation logic. This allows you to show validation messages dynamically as users interact with the form or when the entire form is revalidated (for instance, on form submission).

Below is a simple example demonstrating its usage:

validator-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new MyForm();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class MyForm : IComponent
    {
        public HTMLElement Render()
        {
            // Create the validator
            var validator = Validator().OnValidation(validity =>
            {
                console.log(validity == ValidationState.Invalid
                    ? "Some fields are invalid"
                    : "All fields are valid");
            });

            // Create input controls
            var nameTextBox = TextBox("").Required();
            var ageTextBox = TextBox("").Required();

            // Register validation for the name TextBox: must not be empty.
            nameTextBox.Validation(tb =>
                string.IsNullOrWhiteSpace(tb.Text) ? "Please enter your name" : null,
                validator);

            // Register validation for the age TextBox: must be a valid positive integer.
            ageTextBox.Validation(tb =>
                Validation.NonZeroPositiveInteger(tb) ?? null,
                validator);

            // Optionally, check if all values are valid
            console.log("Is form valid? " + validator.AreCurrentValuesAllValid());
        
            return ageTextBox.Render();}
    }
}

API reference

class

Validator

public sealed class Validator

A Validator class that coordinates validation for multiple components.

Constructors

Constructor

Validator

public Validator()

Initializes a new instance of the Validator class.

Properties

Property

Validator.IsValid

public bool IsValid { get ; }

This will trigger the validation logic for EVERY registered component and return false if any of them are not in a valid state (and, by doing so, their display state will be updated accordingly)

Methods

Delegate

Validator.OnValidationHandler

public delegate void OnValidationHandler(ValidationState validity)

The haveEncounteredInvalidValue value indicates whether any invalid values have been encountered SO FAR - components will only be validated as a User edits them OR when a Revalidate call is made (or the IsValid property is checked), which indicates an action such a form submission is about to occur and that EVERYTHING should be checked (unless such an action has occurred, we want to give Users a chance to fill things in BEFORE we shout at them about it)

Method

Validator.Register<T>

public void Register<T>(ICanValidate<T> component, Func<bool> wouldBeValid, Action validate) where T : ICanValidate<T>

Registers a component with the validator.

Type Parameters

T: The type of the component.

Parameters

component: The component to register.
wouldBeValid: A function that returns whether the component would be valid without updating its visual state.
validate: An action that performs validation and updates the component's visual state.

Method

Validator.ResetState

public void ResetState()

Resets the validation state of all registered components.

Method

Validator.RegisterFromCallback

public void RegisterFromCallback(Func<bool> isInvalid, Action onRevalidation)

Registers a custom validation logic not tied to a specific component.

Parameters

isInvalid: A function that returns whether the state is invalid.
onRevalidation: An action to perform on revalidation.

Method

Validator.OnValidation

public Validator OnValidation(OnValidationHandler onValidation)

Adds a validation event handler.

Parameters

onValidation: The validation event handler.

Returns

The current instance of the type.

Method

Validator.Debounce

public Validator Debounce(int delayInMs)

Sets the debounce delay for validation. The milliseconds must be a value of at least one, trying to disable Debounce by passing a zero (or negative) value is not supported.

Parameters

delayInMs: The delay in milliseconds.

Returns

The current instance of the type.

Method

Validator.Debounce

public Validator Debounce(int delayInMs, int maxDelayInMs)

Sets the debounce delay and maximum delay for validation.

Parameters

delayInMs: The delay in milliseconds.
maxDelayInMs: The maximum delay in milliseconds.

Returns

The current instance of the type.

Method

Validator.AreCurrentValuesAllValid

public bool AreCurrentValuesAllValid()

This will check whether the form's values would currently be considered valid but without updating any the visual states relating to validity - this may be used when a form is being displayed to the User where the fields MIGHT all have been pre-populated and so the form may be valid already (but if it's not valid yet then we don't want the fields that the User hasn't edited yet to be shown as invalid until they've had a chance to interact with them). This would be used if the submit on the form should be set to disabled initially if the form is invalid (or enabled if IS valid) and subsequently updated on each ValidationOccured event.

Method

Validator.Revalidate

public bool Revalidate()

Triggers validation for all registered components and returns whether they are all valid.

Returns

True if all components are valid, false otherwise.

Method

Validator.GetValidity

private ValidationState GetValidity(bool validateOnlyUserEditedComponents, bool updateComponentAppearances)

This will return false if any of the components that were checked were found to be in an invalid state (the components checked depends upon validateOnlyUserEditedComponents and which registered components that the User has interacted with)

Samples

Basic Form Validation Example

The following sample demonstrates how to set up a simple form with two text boxes. Each text box has its own validation logic, and a validator is used to update the UI based on the current validity of the form.

validator-2-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new FormExample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class FormExample : IComponent
    {
        public HTMLElement Render()
        {
            // Create the validator and set up a handler for validation events.
            var validator = Validator().OnValidation(validity =>
            {
                // Log the current state – useful for enabling/disabling submit buttons.
                console.log(validity == ValidationState.Invalid ? "Invalid!" : "Valid!");
            });

            // Create two text boxes with validation rules.
            var nameBox = TextBox("").Required();
            nameBox.Validation(tb =>
                string.IsNullOrWhiteSpace(tb.Text) ? "Name cannot be empty" : null,
                validator);

            var ageBox = TextBox("").Required();
            ageBox.Validation(tb =>
                Validation.NonZeroPositiveInteger(tb) ?? "Age must be a positive integer",
                validator);

            // Use a button to force validation on click.
            var validateButton = Button("Validate").OnClick((s, b) => validator.Revalidate());

            // Arrange components in a vertical stack.
            return Stack().Children(
                Label("Name").SetContent(nameBox),
                Label("Age").SetContent(ageBox),
                validateButton
            ).Render();
        }
    }
}

Referenced by

Observables

Validator

Description

Usage

API reference

Constructors

Validator

Properties

Validator.IsValid

Methods

Validator.OnValidationHandler

Validator.Register<T>

Type Parameters

Parameters

Validator.ResetState

Validator.RegisterFromCallback

Parameters

Validator.OnValidation

Parameters

Returns

Validator.Debounce

Parameters

Returns

Validator.Debounce

Parameters

Returns

Validator.AreCurrentValuesAllValid

Validator.Revalidate

Returns

Validator.GetValidity

Samples

Basic Form Validation Example

See also

Referenced by