Version: 8.3

Custom validator implemented using remote module

Level: advanced

The @creatio-devkit/common library includes a wide set of out-of-the-box validators that cover most data quality requirements on Freedom UI pages. Learn more: validators schema section. For business scenarios with more specific requirements — for example, checking a field value against an external source or applying conditional logic across multiple attributes — Creatio lets you implement custom validators and apply them directly to Freedom UI page elements.

Creatio lets you implement custom validators in the following ways:

Using the validators section of the Freedom UI page schema. Example: Implement the field value validation on a page.
Using a remote module.

To implement a custom validator using remote module, complete the following steps.

1. Create an Angular project

To create an Angular project to develop a custom validator, follow the instructions: Create an Angular project.

2. Install npm packages

To install npm packages, follow the instructions: Install npm packages.

3. Create a custom validator

Ensure the project includes the "AGENTS.md" file. Instructions: Create a custom Freedom UI component (step 1).
For Creatio version 8.3.4 and later, run the ng g class features/runtime/validators/some-validator-name.validator command in the Visual Studio Code terminal to create an Angular class in the project, where some-validator-name.validator is a custom class name. This adds the SomeValidatorNameValidator class files to the "src/app/features/runtime/validators" project directory.

For Creatio version 8.3.3 and earlier
Run the ng g class some-validator-name.validator command in the Visual Studio Code terminal to create an Angular class in the project, where some-validator-name.validator is a custom class name. This adds the SomeValidatorNameValidator class file to the "src/app" project directory.

Implement the validator.

Open the "some-validator-name.validator.ts" file.
Flag the SomeValidatorNameValidator class using the @CrtValidator decorator.
Extend the BaseValidator class from the @creatio-devkit/common library.
Override the async field.
Override the validate() method that validates data in the field.
Import the required functionality from the libraries into the file.
Save the file.

"some-validator-name.validator.ts" file
/* Import the required functionality from the libraries. */
import {
  BaseValidator,
  CrtControlState,
  CrtValidationErrors,
  CrtValidator,
  ValidatorParametersValues
} from "@creatio-devkit/common";

/* Add the CrtValidator decorator to the SomeValidatorNameValidator class. */
@CrtValidator({
  type: 'usr.SomeValidatorNameValidator',
})

export class SomeValidatorNameValidator extends BaseValidator {
  constructor(private _name: string) {
    super();
  }
  /* Override the async field. */
  protected override async = false;
  /* Override the validate() method that validates data in the field. */
  public validate(
    control: CrtControlState,
    params?: ValidatorParametersValues
  ): CrtValidationErrors | null {

    /* Implement the logic of the method. */

    const value = control.value as string;

    if (value === this._name) {
      return {
        error: {
          message: 'Validation error message'
        },
      }
    }
    return null;
  }
}

Inject dependencies.

Open the "some-validator-name.validator.ts" file.
Create the SOME_TOKEN_NAME injection token using the InjectionToken class. Use the token to work with Angular DI (dependency injection).
Inject the dependency into the constructor of the SomeValidatorNameValidator class using the @CrtInject decorator.
Import the required functionality from the libraries into the file.
Save the file.

"some-validator-name.validator.ts" file
/* Import the required functionality from the libraries. */
import { InjectionToken } from "@angular/core";
import { CrtInject } from "@creatio-devkit/common";

/* The SOME_TOKEN_NAME token that works with Angular DI (dependency injection). */
export const SOME_TOKEN_NAME = new InjectionToken<string>('SOME_TOKEN_NAME');

export class SomeValidatorNameValidator extends BaseValidator {
  /* Inject the dependency using the @CrtInject decorator. */
  constructor(@CrtInject(SOME_TOKEN_NAME) private _name: string) {
    super();
  }

}

Register the SomeValidatorNameValidator validator and the SOME_TOKEN_NAME token.

For Creatio version 8.3.4 and later, the template already contains the runtime feature activation and bootstrapCrtModule() call. Extend the existing runtime feature files to register the validator.

Open the "runtime-feature.module.ts" file.
Add the SomeValidatorNameValidator validator to the validators section in the @CrtModule decorator.

Add the configuration object to the providers section in the @NgModule decorator.

Set the provide property to "SOME_TOKEN_NAME."
Set the useValue property to the validation value.

"runtime-feature.module.ts" file
/* Import the required functionality from the libraries. */
import { ApplicationRef, DoBootstrap, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CrtModule } from '@creatio-devkit/common';
import {
  SomeValidatorNameValidator,
  SOME_TOKEN_NAME
} from './validators/some-validator-name.validator';

@CrtModule({
  /* Specify that SomeValidatorNameValidator is a validator. */
  validators: [SomeValidatorNameValidator],
})
@NgModule({
  imports: [BrowserModule],
  providers: [
    {
      provide: SOME_TOKEN_NAME,
      useValue: 'SomeValue'
    }
  ],
})
export class RuntimeFeatureModule implements DoBootstrap {
  ngDoBootstrap(_appRef: ApplicationRef): void {}
}

Open the "runtime.feature-definition.ts" file.

Add the public type property of the validator to the discovery.validators section.

"runtime.feature-definition.ts" file
/* Import the required functionality from the libraries. */
import type {
  RemoteDesignerDefinitionsLoadContext,
  RemoteFeatureDefinition
} from '@creatio-devkit/common';

export const runtimeFeatureDefinition = {
  id: 'some-validator-name-runtime',
  discovery: {
    viewElements: [],
    validators: [
      {
        type: 'usr.SomeValidatorNameValidator'
      }
    ],
  },
  loadDesignerDefinitions: (context: RemoteDesignerDefinitionsLoadContext) =>
    import('./runtime.designer-definitions').then(
      (m) => m.loadRuntimeDesignerDefinitions(context)),
  activate: () =>
    import('./runtime.feature-activation').then((m) => m.activateRuntimeFeature()),
} satisfies RemoteFeatureDefinition;

Import the required functionality from the libraries into the files.
Save the files.

For Creatio version 8.3.3 and earlier

Register the SomeValidatorNameValidator validator and the SOME_TOKEN_NAME token in the AppModule root module.

Open the "app.module.ts" file.
Add the SomeValidatorNameValidator validator to the validators section in the @CrtModule decorator.
Add the configuration object to the providers section in the @NgModule decorator.
- Set the provide property to "SOME_TOKEN_NAME."
- Set the useValue property to the validation value.
Implement the resolveDependency() method in the bootstrapCrtModule() method of the AppModule root module. The bootstrapCrtModule() method registers the SomeValidatorNameValidator validator flagged using the @CrtModule decorator. The resolveDependency() method receives the dependencies of the SomeValidatorNameValidator validator.
Import the required functionality from the libraries into the file.
Save the file.

"app.module.ts" file
/* Import the required functionality from the libraries. */
import {
  DoBootstrap,
  Injector,
  NgModule,
  ProviderToken
} from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { bootstrapCrtModule, CrtModule } from '@creatio-devkit/common';
import {
  SomeValidatorNameValidator,
  SOME_TOKEN_NAME
} from "./some-validator-name.validator";

@CrtModule({
  /* Specify that SomeValidatorNameValidator is a validator. */
  validators: [SomeValidatorNameValidator],
})
@NgModule({
  imports: [BrowserModule],
  providers: [{
    provide: SOME_TOKEN_NAME,
    useValue: 'SomeValue'
  }],

})
export class AppModule implements DoBootstrap {
  constructor(private _injector: Injector) { }

  ngDoBootstrap(): void {
    /* Bootstrap CrtModule definitions. */
    bootstrapCrtModule('some_package_name', AppModule, {
      resolveDependency: (token) =>
        this._injector.get(<ProviderToken<unknown>>token)
    });
  }
}

Run the npm run build command in the Visual Studio Code terminal to build the project.

As a result, the build will be added to the "dist" directory of the Angular project.

4. Add the custom validator to the Freedom UI page

Repeat steps 1-5 of the instructions: Add the custom Freedom UI component to the Freedom UI page.

Bind the usr.SomeValidatorNameValidator validator to the corresponding model attribute in the viewModelConfigDiff schema section.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    {
        "operation": "merge",
        "path": [
            "attributes"
        ],
        "values": {
            "SomeField": {
                "modelConfigDiff": {
                    "path": "PDS.SomeField"
                },
                "validators": {
                    "usr.SomeValidatorNameValidator": {
                        "type": "usr.SomeValidatorNameValidator",
                        "params": {}
                    }
                }
            },
        }
    }
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Click Save.

As a result, the custom validator will be applied to the corresponding element on the Freedom UI page.

Resources

Remote module template (for Creatio version 8.3.4 and later)

Remote module template (for Creatio version 8.3.3 and earlier)

1. Create an Angular project​

2. Install npm packages​

3. Create a custom validator​

4. Add the custom validator to the Freedom UI page​

See also​

Resources​

1. Create an Angular project

2. Install npm packages

3. Create a custom validator

4. Add the custom validator to the Freedom UI page

See also

Resources