To implement a custom converter using remote module:
- Create an Angular project to develop a custom converter using remote module.
- Create a custom converter using remote module.
- Implement the business logic of the custom converter using remote module.
- Add the converter implemented using remote module to the Freedom UI page.
1. Create an Angular project to develop a custom converter using remote module
Develop a custom converter in a dedicated npm package using an external IDE. This example covers the custom converter development in Microsoft Visual Studio Code.
You can create an Angular project to develop a custom converter in multiple ways, similarly to creating an Angular project to develop a custom UI component using remote module. To do this, follow the instruction in a separate article: Custom UI component implemented using remote module.
2. Create a custom converter using remote module
You can implement synchronous or asynchronous custom converters. The procedure for implementing a custom converter is similar for various types of converters.
-
Create an Angular class in the project. To do this, run the ng g class some_converter_name.converter command at the command line terminal of Microsoft Visual Studio Code.
some_converter_name.converter is an arbitrary class name.
As a result, Microsoft Visual Studio Code will add the SomeConverterNameConverter class files to the src/app/ project directory.
-
Specify that the SomeConverterNameConverter class is a converter.
- Open the some_converter_name.converter.ts file.
-
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
V is type of convertible attribute.
R is type of conversion result.
- Flag the SomeConverterNameConverter class using the CrtConverter decorator.
- Import the required functionality from the libraries to the class.
- Save the file.
-
Inject dependencies.
- Open the some_converter_name.converter.ts file.
- Create the SOME_TOKEN_NAME instance of the InjectionToken class (optional). Use the token to work with Angular DI (dependency injection). You can use a client web service instead of the token.
- Flag the SOME_TOKEN_NAME token using the CrtInject decorator.
- Import the required functionality from the libraries into the class.
- Save the file.
-
Register the SomeConverterNameConverter converter as a converter and the SOME_TOKEN_NAME token.
- 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 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 class.
- Save the file.
- Build the project. To do this, run the npm run build command at the command line terminal of Microsoft Visual Studio Code.
As a result, Microsoft Visual Studio Code will add the build to the dist directory of the Angular project. The build will have the <%projectName%> name specified on step 1.
3. Implement the business logic of the custom converter using remote module
-
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
V is the type of convertible attribute.
R is the type of conversion result.
- Import the required functionality from the libraries into the class.
- Save the file.
- Build the project. To do this, run the npm run build command at the command line terminal of Microsoft Visual Studio Code.
As a result, Microsoft Visual Studio Code will add the build to the dist directory of the Angular project. The build will have the <%projectName%> name specified on step 1.
4. Add the converter implemented using remote module to the Freedom UI page
- Repeat steps 1-6 of the procedure to implement a custom UI component using remote module.
-
Bind the custom converter implemented using a remote module to the caption property of the corresponding model attribute in the viewConfigDiff schema section. Creatio lets you set converter parameters. Learn more in a separate article: Customize page fields.
- Click Save on the Client Module Designer’s toolbar.
As a result, Creatio will apply the converter to the element on the Freedom UI page.
1. Create an Angular project to develop a custom converter using remote module
To create an Angular project to develop a custom converter using remote module, follow the instruction in a separate article: Implement custom UI component using remote module.
2. Create a custom converter using remote module
-
Create an Angular class in the project. To do this, run the ng g class concat.converter command at the command line terminal of Microsoft Visual Studio Code.
As a result, Microsoft Visual Studio Code will add the ConcatConverter class files to the src/app/ project directory.
-
Specify that the ConcatConverter class is a converter.
- Open the concat.converter.ts file.
- Create the ConcatConverter class that implements the Converter<string, string> interface from the @creatio-devkit/common library.
- Flag the ConcatConverter class using the CrtConverter decorator.
- Import the required functionality from the libraries into the class.
- Save the file.
-
Inject dependencies.
- Open the concat.converter.ts file.
- Create the CONCAT_SEPARATOR_TOKEN instance of the InjectionToken class. The token works with Angular DI (dependency injection).
- Flag the CONCAT_SEPARATOR_TOKEN token using the CrtInject decorator.
- Import the required functionality from the libraries into the class.
- Save the file.
-
Register the ConcatConverter converter as a converter and the CONCAT_SEPARATOR_TOKEN token.
- Open the app.module.ts file.
- Add the ConcatConverter converter to the converters section in the CrtModule decorator.
-
Add the configuration object to the providers section in the NgModule decorator.
- Set provide property to CONCAT_SEPARATOR_TOKEN.
- Set useValue property to space.
- Implement the resolveDependency() method in the bootstrapCrtModule() method of the AppModule root module. The bootstrapCrtModule() method registers the ConcatConverter converter flagged using the CrtModule decorator. The resolveDependency() method receives the dependencies of the ConcatConverter converter.
- Import the required functionality from the libraries into the class.
- Save the file.
Complete source code of the app.module.ts file - Build the project. To do this, run the npm run build command at the command line terminal of Microsoft Visual Studio Code.
As a result, Microsoft Visual Studio Code will add the build to the dist directory of the Angular project. The build will have the sdk_remote_module_package name.
3. Implement the business logic of the custom converter using remote module
-
Implement the conversion of an incoming value.
- Open the concat.converter.ts file.
- Implement the convert(value: string, context: ViewModelContext, ...params: string[]): string; method of the ConcatConverter interface.
- Import the required functionality from the libraries into the class.
- Save the file.
Complete source code of the concat.converter.ts file - Build the project. To do this, run the npm run build command at the command line terminal of Microsoft Visual Studio Code.
As a result, Microsoft Visual Studio Code will add the build to the dist directory of the Angular project. The build will have the sdk_remote_module_package name.
4. Add the converter implemented using remote module to the Freedom UI page
- Repeat steps 1-7 of the procedure to Implement custom UI component using remote module.
- Add a Label type component to the working area of the Freedom UI Designer.
- Click the
button in the action panel of the Freedom UI Designer. After you save the page settings, Creatio opens the source code of the Freedom UI page.
-
Bind the caption property of the Label element to the $UsrName model attribute in the viewConfigDiff schema section. $UsrName is the value of the Name field. Add the usr.Converter converter with the 'is the request name' parameter to the $UsrName attribute.
Complete source code of the page schema - Click Save on the Client Module Designer’s toolbar.
As a result, Creatio will add the converter to the Freedom UI page.
Outcome of the example
To view the outcome of the example:
- Open the Requests app page and click Run app.
- Click New on the Requests app toolbar.
- Enter "REQ-001" in the Name input.
As a result, Creatio will display the converted value on the request page. The synchronous converter is implemented using a remote module created in Angular framework.
