# Installation

## Instructions

Leverage [CommandBox](https://www.ortussolutions.com/products/commandbox) to install via your CLI

```bash
box install cbvalidation
```

The module will register several objects into WireBox using the `@cbvalidation` namespace. The validation manager is registered as `ValidationManager@cbvalidation`. It will also register several helper methods that can be used throughout the ColdBox application.

## System Requirements

* BoxLang 1+ (Preferred)
* Lucee 5+
* ColdFusion 2023+

## Mixins - Helper Methods

The module will also register the following methods in your handlers/interceptors/layouts/views

* `validate()`
* `validateOrFail()`
* `getValidationManager()`
* `validatehasValue()`
* `validateIsNullOrEmpty()`
* `assert()`

```javascript
/**
 * Validate an object or structure according to the constraints rules.
 *
 * @target An object or structure to validate
 * @fields The fields to validate on the target. By default, it validates on all fields
 * @constraints A structure of constraint rules or the name of the shared constraint rules to use for validation
 * @locale The i18n locale to use for validation messages
 * @excludeFields The fields to exclude from the validation
 * @includeFields The fields to include in the validation
 * @profiles If passed, a list of profile names to use for validation constraints
 *
 * @return cbvalidation.model.result.IValidationResult
 */
function validate()

/**
 * Validate an object or structure according to the constraints rules and throw an exception if the validation fails.
 * The validation errors will be contained in the `extendedInfo` of the exception in JSON format
 *
 * @target An object or structure to validate
 * @fields The fields to validate on the target. By default, it validates on all fields
 * @constraints A structure of constraint rules or the name of the shared constraint rules to use for validation
 * @locale The i18n locale to use for validation messages
 * @excludeFields The fields to exclude from the validation
 * @includeFields The fields to include in the validation
 * @profiles If passed, a list of profile names to use for validation constraints
 *
 * @return The validated object or the structure fields that where validated
 * @throws ValidationException
 */
function validateOrFail()

/**
 * Retrieve the application's configured Validation Manager
 */
function getValidationManager()

/**
 * Verify if the target value has a value
 * Checks for nullness or for length if it's a simple value, array, query, struct or object.
 */
boolean function validateHasValue( any targetValue )

/**
 * Check if a value is null or is a simple value and it's empty
 *
 * @targetValue the value to check for nullness/emptyness
 */
boolean function validateIsNullOrEmpty( any targetValue )

/**
 * This method mimics the Java assert() function, where it evaluates the target to a boolean value and it must be true
 * to pass and return a true to you, or throw an `AssertException`
 *
 * @target The tareget to evaluate for being true
 * @message The message to send in the exception
 *
 * @throws AssertException if the target is a false or null value
 * @return True, if the target is a non-null value. If false, then it will throw the `AssertError` exception
 */
boolean function assert( target, message="" )
```

## Delegate Mode

If you are using ColdBox 7, then you can use the `Validatable@cbValidation` delegate. Which will allow you to add these validation traits to any object you desire.

```javascript
// BoxLang Syntax
@delegates( "Validatable@cbValidation" )
class{}

// CFML Syntax
component delegates="Validatable@cbValidation"{}
```

The methods delegated by default are the following:

* `assert()`
* `getValidationManager()`
* `getValidationResults()`
* `isValid()`
* `validate()`
* `validateHasValue()`
* `validateIsNullOrEmpty()`
* `validateOrFail()`

You can also use the delegation for only certain methods if needed:

```javascript
// BoxLang Short Syntax
@delegates( "Validatable@cbValidation=validate,validateOrFail" )
class{}

// BoxLang Long Syntax via delegate injection
class{

    @inject( "Validatable@cbValidation" )
    @delegate( "validate,validateOrFail" )
    property name="validatable";

}

// ----------------------------------------------------------------

// CFML Short Syntax
component delegates="Validatable@cbValidation=validate,validateOrFail"{}

// Long Syntax via delegate injection
component{

  property name="validatable"
        inject="Validatable@cbValidation"
        delegate="validate,validateOrFail"

}
```

## WireBox Integration

The module will register several objects into WireBox using the `@cbvalidation` namespace. The validation manager is registered as `ValidationManager@cbvalidation`, which is the one you can inject and use anywhere you like.

```javascript
// get reference
property name="validationManager" inject="ValidationManager@cbvalidation";
```

{% hint style="danger" %}
Remember, you have the mixins available to you in your handlers/interceptors/layouts and views and the `Validatable@cbValidation` delegate for any model object.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://coldbox-validation.ortusbooks.com/overview/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.