Version: 8.3

Custom converter implemented using remote module

Level: advanced

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

Creatio lets you implement custom converters in the following ways:

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

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

1. Create an Angular project

To create an Angular project to develop a custom converter, 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 converter

Creatio lets you implement synchronous or asynchronous custom converters using remote module. The procedure for implementing a custom converter is similar for various types of converters.

To create a custom converter:

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/converters/some-converter-name.converter command in the Visual Studio Code terminal to create an Angular class in the project, where some-converter-name.converter is a custom class name. This adds the SomeConverterNameConverter class files to the "src/app/features/runtime/converters" project directory.

For Creatio version 8.3.3 and earlier
Run the ng g class some-converter-name.converter command in the Visual Studio Code terminal to create an Angular class in the project, where some-converter-name.converter is a custom class name. This adds the SomeConverterNameConverter class files to the "src/app" project directory.
Specify that the SomeConverterNameConverter class is a converter.
1. Open the "some-converter-name.converter.ts" file.
2. Create the SomeConverterNameConverter class that implements the interface from the @creatio-devkit/common library. The SomeConverterNameConverter class implements one of the following interfaces:
  - Converter<V, R> for synchronous converters.
  - Converter<V, Promise<R>> for asynchronous converters.
  Where V is the type of the convertible attribute and R is the type of the conversion result.
3. Flag the SomeConverterNameConverter class using the @CrtConverter decorator.
4. Import the required functionality from the libraries into the file.
5. Save the file.
"some-converter-name.converter.ts" file
```
/* Import the required functionality from the libraries. */
import { Converter, CrtConverter } from "@creatio-devkit/common";

/* Register the SomeConverterNameConverter as a Freedom UI converter. */
@CrtConverter({
  type: 'usr.SomeConverterNameConverter',
})

/* The class for synchronous converters. */
export class SomeConverterNameConverter implements Converter<string, string> {
}

/* The class for asynchronous converters. */
export class SomeConverterNameConverter implements Converter<string, Promise<string>> {
}
```

Inject dependencies.

Open the "some-converter-name.converter.ts" file.
Create the SOME_TOKEN_NAME injection token using the InjectionToken class. Use the token to work with Angular DI (dependency injection). Alternatively, you can inject a client web service directly using Angular DI instead of using an injection token.
Inject the dependency into the constructor of the SomeConverterNameConverter class using the @CrtInject decorator.
Import the required functionality from the libraries into the file.
Save the file.

"some-converter-name.converter.ts" file
/* Import the required functionality from the libraries. */
import { InjectionToken } from "@angular/core";
import { Converter, 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');

/* The class for synchronous converters. */
export class SomeConverterNameConverter implements Converter<string, string> {
  constructor(@CrtInject(SOME_TOKEN_NAME) private _separator: string) { };
}

/* The class for asynchronous converters. */
export class SomeConverterNameConverter implements Converter<string, Promise<string>> {
  constructor(@CrtInject(SOME_TOKEN_NAME) private _separator: string) { };
}

Register the SomeConverterNameConverter converter 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 converter.

Open the "runtime-feature.module.ts" file.
Add the SomeConverterNameConverter converter to the converters 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 ' ' (a single space).

"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 {
  SomeConverterNameConverter,
  SOME_TOKEN_NAME
} from './converters/some-converter-name.converter';

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

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

Add the public type property of the converter to the discovery.converters 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-converter-name-runtime',
  discovery: {
    viewElements: [],
    converters: [
      {
        type: 'usr.SomeConverterNameConverter'
      }
    ],
  },
  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 SomeConverterNameConverter converter and the SOME_TOKEN_NAME token in the AppModule root module.

Open the "app.module.ts" file.
Add the SomeConverterNameConverter converter to the converters 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 ' ' (a single space).
Implement the resolveDependency() method in the bootstrapCrtModule() method of the AppModule root module. The bootstrapCrtModule() method registers the SomeConverterNameConverter converter flagged using the @CrtModule decorator. The resolveDependency() method receives the dependencies of the SomeConverterNameConverter converter.
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 { bootstrapCrtModule, CrtModule } from '@creatio-devkit/common';
import {
  SomeConverterNameConverter,
  SOME_TOKEN_NAME
} from './some-converter-name.converter';

@CrtModule({
  /* Specify that SomeConverterNameConverter is a converter. */
  converters: [SomeConverterNameConverter]
})
@NgModule({
  providers: [
    {
      provide: SOME_TOKEN_NAME,
      useValue: ' '
    },
  ],
})
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),
    });
  }
}

Implement the conversion of an incoming value.

Open the "some-converter-name.converter.ts" file.
Implement a method of the SomeConverterNameConverter interface. Implement one of the following methods:
- convert(value: V, context: ViewModelContext, ...params: unknown[]): R; for synchronous converters.
- async convert(value: V, context: ViewModelContext, ...params: unknown[]): R; for asynchronous converters.
Where V is the type of the convertible attribute and R is the type of the conversion result.
Import the required functionality from the libraries into the file.
Save the file.

"some-converter-name.converter.ts" file
/* Import the required functionality from the libraries. */
import { Converter, ViewModelContext } from "@creatio-devkit/common";

/* The class for synchronous converters. */
export class SomeConverterNameConverter implements Converter<string, string> {

  /* Implement the convert() method for synchronous converters. */
  public convert(
    value: string,
    context: ViewModelContext,
    ...params: string[]
  ): string {
    return [value, ...params].join(this._separator);
  }
}

/* The class for asynchronous converters. */
export class SomeConverterNameConverter implements Converter<string, Promise<string>> {

  /* Implement the convert() method for asynchronous converters. */
  public async convert(
    value: string,
    context: ViewModelContext,
    ...params: string[]
    ): Promise<string> {
      /* Implement some async action. */

      await new Promise(function(resolve) {
        setTimeout(resolve, 100);
      });
      return [value, ...params].join(this._separator);
  }
}

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 converter 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.SomeConverterNameConverter converter to the needed property of the corresponding model attribute in the viewConfigDiff schema section. Creatio lets you set converter parameters. Learn more: Implement field value conversion.

viewConfigDiff schema section
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        "operation": "insert",
        "name": "SomeComponentName",
        "values": {
            /* Apply converter to the $SomeAttributeName attribute.
            Use a synchronous or asynchronous converter. */
            "caption": "$SomeAttributeName | usr.SomeConverterNameConverter :'SomeConverterParameter'",
        },
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

Click Save.

As a result, the custom converter 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 converter​

4. Add the converter to the Freedom UI page​

See also​

Resources​

1. Create an Angular project

2. Install npm packages

3. Create a custom converter

4. Add the converter to the Freedom UI page

See also

Resources