Implement a custom converter using remote module

Level: advanced

To implement the example:

1. Create an Angular project. Read more >>>
2. Install npm packages. Read more >>>
3. Create a custom converter. Read more >>>
4. Add the converter to the Freedom UI page. Read more >>>

Example

Add a custom converter to the custom request page. The converter adds the "is the request name" string to the Name field value. Display the converted value as a Label component. Implement the synchronous converter using a remote module created in Angular framework.

1. Create an Angular project

To create an Angular project, follow the instructions: Create an Angular project.

For this example:

• <%projectName%> macro is set to "sdk_custom_converter."
• <%vendorPrefix%> macro is set to "usr."

As a result, an Angular project to develop a custom converter using a remote module will be added. The project contains:

• A RemoteEntryDefinition object exported from the "src/main.ts" file.
• The runtime feature files used to implement converter.
• The optional design feature files.
• The "sdk_custom_converter-runtime" runtime feature ID.

2. Install npm packages

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

As a result, required npm packages are installed.

3. Create a custom converter

1. Ensure the project includes the "AGENTS.md" file. Instructions: Create a custom Freedom UI component (step 1).

2. Run the ng g class features/runtime/converters/concat.converter command in the Visual Studio Code terminal to create an Angular class in the project. This adds the ConcatConverter class files to the "src/app/features/runtime/converters" project directory.

3. Specify that the ConcatConverter class is a converter.

   1. Open the "concat.converter.ts" file.
   2. Implement the Converter<string, string> interface from the @creatio-devkit/common library in the ConcatConverter class.
   3. Flag the ConcatConverter class using the @CrtConverter decorator.
   4. Import the required functionality from the libraries into the class.
   5. Save the file.
   "concat.converter.ts" file

   /* Import the required functionality from the libraries. */
   import { Converter, CrtConverter } from "@creatio-devkit/common";
   
   /* Add the CrtConverter decorator to the ConcatConverter class. */
   @CrtConverter({
     type: 'usr.ConcatConverter',
   })
   
   export class ConcatConverter implements Converter<string, string> {
   }

4. Inject dependencies.

   1. Open the "concat.converter.ts" file.
   2. Create the CONCAT_SEPARATOR_TOKEN injection token using the InjectionToken class. Use the token to work with Angular DI (dependency injection).
   3. Inject the dependency into the constructor of the ConcatConverter class using the @CrtInject decorator.
   4. Import the required functionality from the libraries into the class.
   5. Save the file.
   "concat.converter.ts" file

   /* Import the required functionality from the libraries. */
   import { InjectionToken } from "@angular/core";
   import { Converter, CrtInject } from "@creatio-devkit/common";
   
   /* The CONCAT_SEPARATOR_TOKEN token that works with Angular DI (dependency injection). */
   export const CONCAT_SEPARATOR_TOKEN =
     new InjectionToken<string>('CONCAT_SEPARATOR_TOKEN');
   
   export class ConcatConverter implements Converter<string, string> {
     /* Inject the dependency using the @CrtInject decorator. */
     constructor(@CrtInject(CONCAT_SEPARATOR_TOKEN) private _separator: string) { }
   }

5. Register the ConcatConverter converter and the CONCAT_SEPARATOR_TOKEN token. The template already contains the runtime feature activation and bootstrapCrtModule() call. Extend the existing runtime feature files to register the converter.

   1. Open the "runtime-feature.module.ts" file.

   2. Add the ConcatConverter converter to the converters section in the @CrtModule decorator.

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

      • Set the provide property to "CONCAT_SEPARATOR_TOKEN."
      • 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 {
        ConcatConverter,
        CONCAT_SEPARATOR_TOKEN
      } from './converters/concat.converter';
      
      @CrtModule({
        /* Specify that ConcatConverter is a converter. */
        converters: [ConcatConverter],
      })
      @NgModule({
        declarations: [],
        imports: [BrowserModule],
        providers: [
          {
            provide: CONCAT_SEPARATOR_TOKEN,
            useValue: ' ',
          },
        ],
      })
      export class RuntimeFeatureModule implements DoBootstrap {
        ngDoBootstrap(_appRef: ApplicationRef): void {}
      }

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

   5. 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';
      
      /**
       * Root definition for the runtime feature.
       *
       * Describes the view elements this remote package contributes at runtime
       * and provides the entry points used to load designer metadata and activate
       * the feature.
       */
      export const runtimeFeatureDefinition = {
        id: 'sdk_custom_converter-runtime',
        discovery: {
          viewElements: [],
          converters: [
            {
              type: 'usr.ConcatConverter',
            },
          ],
        },
        loadDesignerDefinitions: (context: RemoteDesignerDefinitionsLoadContext) =>
          import('./runtime.designer-definitions').then((m) => m.loadRuntimeDesignerDefinitions(context)),
        activate: () =>
          import('./runtime.feature-activation').then((m) => m.activateRuntimeFeature()),
      } satisfies RemoteFeatureDefinition;

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

   7. Save the files.

6. Implement the conversion of an incoming value.

   1. Open the "concat.converter.ts" file.
   2. Implement the convert(value: string, context: ViewModelContext, ...params: string[]): string; method of the ConcatConverter interface.
   3. Import the required functionality from the libraries into the class.
   4. Save the file.
   "concat.converter.ts" file

   /* Import the required functionality from the libraries. */
   import { Converter, ViewModelContext } from "@creatio-devkit/common";
   
   export class ConcatConverter implements Converter<string, string> {
   
     /* Implement the convert() method. */
     public convert(
       value: string,
       context: ViewModelContext,
       ...params: string[]
     ): string {
       return [value, ...params].join(this._separator);
     }
   }

7. 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. The build will have the "sdk_custom_converter" name.

4. Add the converter to the Freedom UI page

1. Repeat steps 1-4 of the instructions: Add the custom Freedom UI component to the Freedom UI page. For this example, create a Requests app.

2. Add a label of the request prefix.

   1. Drag the Label component to the canvas.

   2. Fill out the component parameters.

      Parameter	Value
      Style	Body
      Text color	#757575
      Element code	UsrRequestPrefix

3. Click → Source code to open the source code of the Freedom UI page.

4. Bind the converter to the label.

   1. Go to the viewConfigDiff schema section → UsrRequestPrefix element.
   2. Add a UsrName attribute to the caption property.
   3. Bind the usr.ConcatConverter :'is the request name' converter to the $UsrName attribute in the caption property.
   viewConfigDiff schema section

   viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
       {
           "operation": "insert",
           "name": "Label",
           "values": {
               /* Apply the usr.ConcatConverter converter to the $UsrName attribute. */
               "caption": "$UsrName | usr.ConcatConverter :'is the request name'",
           },
       }
   ]/**SCHEMA_VIEW_CONFIG_DIFF*/,

5. Click Save.

As a result, the custom converter will be added to the request page.

View the result

1. Open the Requests section.
2. Create a request that has an arbitrary name. For example, "Vacation."

As a result, Creatio will add the "is the request name" string to the request name. The synchronous converter is implemented using a remote module created in the Angular framework.

---

Resources

*.zip archive that contains the implemented Freedom UI app

Angular project that contains the implemented example