Skip to main content
Version: 8.0

Implement a custom request handler using remote module

Level: intermediate
Important

The example is relevant to Creatio version 8.0.8 and later.

Example

Add request handlers that execute the following actions:

  • Display current date and time in the Label type component on the record page of the custom Requests section.
  • Change the value in the Label type component after a user clicks the custom button.

Implement handlers using a remote module created in Angular framework.

1. Create an Angular project to develop a custom request handler using remote module​

To create an Angular project to develop a custom request handler using remote module, follow the instruction in a separate article: Implement custom UI component using remote module.

2. Create a custom request using remote module​

  1. Create an Angular class in the project. To do this, run the ng g class update-current-time.request command at the command line terminal of Microsoft Visual Studio Code.

    As a result, Microsoft Visual Studio Code will add the UpdateCurrentTimeRequest class files to the src/app/ project directory.

  2. Implement the request.

    1. Open the update-current-time.request.ts file.
    2. Inherit the BaseRequest class from the @creatio-devkit/common library.
    3. Add the type and parameter of the request.
    4. Import the required functionality from the libraries into the class.
    5. Save the file.
    update-current-time.request.ts file
    /* Import the required functionality from the libraries. */
    import { BaseRequest } from "@creatio-devkit/common";

    export class UpdateCurrentTimeRequest extends BaseRequest{
      /* The type and parameters of the request. */
      public dateTime!: string;
    }

  3. 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. Create a custom service using remote module​

  1. Create an Angular class in the project. To do this, run the ng g class date-time.service command at the command line terminal of Microsoft Visual Studio Code.

    As a result, Microsoft Visual Studio Code will add the DateTimeService class files to the src/app/ project directory.

  2. Implement the service that generates current date and time.

    1. Open the date-time.service.ts file.
    2. Flag the DateTimeService class using the Injectable decorator.
    3. Implement the getCurrentDateTime() method that receives current date and time.
    4. Import the required functionality from the libraries into the class.
    5. Save the file.
    date-time.service.ts file
    /* Import the required functionality from the libraries. */
    import { formatDate } from "@angular/common";
    import { Injectable } from "@angular/core";

    @Injectable({
      providedIn: 'root',
    })
    export class DateTimeService {
      /* Receive current date and time. */
      public getCurrentDateTime(dateTime: string): Promise<{
        dateTime: Record<string, unknown>
      }> {
        /* Return current date and time. */
        return Promise.resolve({
          dateTime: {'dateTime': formatDate(new Date(), 'medium', 'en')}
        });
      }
    }

  3. 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. Create custom request handlers using remote module​

  1. Create a custom handler that displays current date and time on the Freedom UI page.

    1. Set up the Freedom UI page.

      1. Use the Records & business processes template to create a custom Requests app. To do this, follow the instruction in the user documentation: Manage apps.

      2. Open the Requests form page page in the working area of the Requests app page.

      3. Add a Label type component to the working area of the Freedom UI Designer.

      4. 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.

      5. Add a CurrentDateTime attribute that stores data about the current date and time to the viewModelConfig schema section.

        viewModelConfig schema section
        viewModelConfig: /**SCHEMA_VIEW_MODEL_CONFIG*/{
            "attributes": {
                ...,
                /* The attribute that stores the current date and time. */
                "CurrentDateTime": {}
            }
        }/**SCHEMA_VIEW_MODEL_CONFIG*/,

      6. Bind the caption property of the Label element to the $CurrentDateTime model attribute in the viewConfigDiff schema section.

        viewConfigDiff schema section
        viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
            ...,
            {
                "operation": "insert",
                "name": "Label",
                "values": {
                    ...,
                    /* Bind the CurrentDateTime attribute to the caption property. */
                    "caption": "$CurrentDateTime",
                    ...
                },
                ...
            }
        ]/**SCHEMA_VIEW_CONFIG_DIFF*/,

      7. Click Save on the Client Module Designer's toolbar.

    2. Create an Angular class in the project. To do this, run the ng g class update-current-time.handler command at the command line terminal of Microsoft Visual Studio Code.

      As a result, Microsoft Visual Studio Code will add the UpdateCurrentTimeHandler class files to the src/app/ project directory.

    3. Implement the handler.

      1. Open the update-current-time.handler.ts file.

      2. Add the configuration object that declares the request handler.

        • Set the type property to usr.UpdateCurrentTimeHandler.
        • Set the requestType property to crt.UpdateCurrentTimeRequest.

      3. Flag the UpdateCurrentTimeHandler class using the CrtRequestHandler decorator.

      4. Inherit the BaseRequestHandler class from the @creatio-devkit/common library.

      5. Implement the handling of the request result.

      6. Generate the value to display in the component of Freedom UI page.

      7. Import the required functionality from the libraries into the class.

      8. Save the file.

      update-current-time.handler.ts file
      /* Import the required functionality from the libraries. */
      import { BaseRequestHandler, CrtRequestHandler } from "@creatio-devkit/common";
      import { DateTimeService } from "./date-time.service";
      import { UpdateCurrentTimeRequest } from "./update-current-time.request";

      /* Add the CrtRequestHandler decorator to the UpdateCurrentTimeHandler class. */
      @CrtRequestHandler({
          type: 'usr.UpdateCurrentTimeHandler',
          requestType: 'crt.UpdateCurrentTimeRequest',
        })

      export class UpdateCurrentTimeHandler extends BaseRequestHandler{
        constructor(private _dateTimeService: DateTimeService) {
          super();
        }
        public async handle(request: UpdateCurrentTimeRequest): Promise<unknown> {
          const result = await this._dateTimeService.getCurrentDateTime(request.dateTime);
          const dateTime = result.dateTime[request.dateTime] ?? 0
          /* Generate the value to display in the component of Freedom UI page. */
          request.$context['CurrentDateTime'] = dateTime;
          return dateTime;
        }
      }

  2. Create a custom handler that is executed when Creatio initializes a Freedom UI page.

    1. Create an Angular class in the project. To do this, run the ng g class page-init-current-time.handler command at the command line terminal of Microsoft Visual Studio Code.

      As a result, Microsoft Visual Studio Code will add the PageInitCurrentTimeHandler class files to the src/app/ project directory.

    2. Implement the handler.

      1. Open the page-init-current-time.handler.ts file.

      2. Add the configuration object that declares the request handler.

        • Set the type property to usr.PageInitCurrentTimeHandler.
        • Set the requestType property to crt.HandleViewModelInitRequest.
        • Set the scopes property to UsrRequests_FormPage. The request handler is executed when Creatio initializes the Freedom UI page that has the UsrRequests_FormPage code.

      3. Flag the PageInitCurrentTimeHandler class using the CrtRequestHandler decorator.

      4. Inherit the BaseRequestHandler class from the @creatio-devkit/common library.

      5. Implement the update of the current date and time when Creatio initializes the Freedom UI page.

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

      7. Save the file.

      page-init-current-time.handler.ts file
      /* Import the required functionality from the libraries. */
      import { BaseRequest, BaseRequestHandler, CrtRequestHandler, HandlerChainService } from "@creatio-devkit/common";
      import { UpdateCurrentTimeRequest } from "./update-current-time.request";

      /* Add the CrtRequestHandler decorator to the PageInitCurrentTimeHandler class. */
      @CrtRequestHandler({
        type: 'usr.PageInitCurrentTimeHandler',
        requestType: 'crt.HandleViewModelInitRequest',
        scopes: ['UsrRequests_FormPage'],
      })

      export class PageInitCurrentTimeHandler extends BaseRequestHandler{
        public async handle(request: BaseRequest): Promise<unknown> {
          /* Update the current date and time when Creatio initializes the Freedom UI page. */
          await HandlerChainService.instance.process({
            type: 'crt.UpdateCurrentTimeRequest',
            dateTime: 'dateTime',
            $context: request.$context
          } as UpdateCurrentTimeRequest);
          
          return this.next?.handle(request);
        }
      }

  3. Register the handlers.

    1. Open the app.module.ts file.
    2. Add the UpdateCurrentTimeHandler and PageInitCurrentTimeHandler handlers to the requestHandlers section in the CrtModule decorator.
    3. Import the required functionality from the libraries into the class.
    4. Save the file.
    app.module.ts file
    /* Import the required functionality from the libraries. */
    import { CrtModule } from '@creatio-devkit/common';
    import { PageInitCurrentTimeHandler } from './page-init-current-time.handler';
    import { UpdateCurrentTimeHandler } from './update-current-time.handler';
    ...

    @CrtModule({
      ...,
      /* Specify that UpdateCurrentTimeHandler and PageInitCurrentTimeHandler are request handlers. */
      requestHandlers: [
        UpdateCurrentTimeHandler,
        PageInitCurrentTimeHandler
      ],
    })
    ...

  4. 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.

5. Add the request implemented using remote module to the Freedom UI page​

  1. Repeat steps 2-7 of the procedure to implement custom UI component using remote module.

  2. Add a Button type component to the working area of the Freedom UI Designer.

  3. 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.

  4. Change the clicked property value for the RefreshCurrentDateTimeButton element in the viewConfigDiff schema section to request configuration object.

    • Enter the crt.UpdateCurrentTimeRequest request name in the request property.
    • Enter the configuration object of parameters in the params property.
    viewConfigDiff schema section
    viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
        {
            "operation": "insert",
            "name": "RefreshCurrentDateTimeButton",
            "values": {
                ...,
                "clicked": {
                    /* Bind the sending of the custom crt.UpdateCurrentTimeRequest request to the button click event. */
                    "request": "crt.UpdateCurrentTimeRequest",
                    "params": {
                        "dateTime": "dateTime"
                    }
                }
            },
            ...
        },
        ...
    ]/**SCHEMA_VIEW_CONFIG_DIFF*/,

  5. Click Save on the Client Module Designer’s toolbar.

As a result, Creatio will add the request to the Freedom UI page.

Outcome of the example​

To view the outcome of the example:

  1. Open the Requests app page and click Run app.
  2. Click New on the Requests app toolbar.
  3. Click Refresh date and time on the request page toolbar.

As a result, Creatio will display current date and time on the request page.

Creatio will update the current date and time when you click the Refresh date and time.

The handlers are implemented using the remote module created in Angular framework.

Source code​

/* 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 { PageInitCurrentTimeHandler } from './page-init-current-time.handler';
import { UpdateCurrentTimeHandler } from './update-current-time.handler';

@CrtModule({
    /* Specify that the component is a view element. */
    viewElements: [],
    /* Specify that UpdateCurrentTimeHandler and PageInitCurrentTimeHandler are request handlers. */
    requestHandlers: [
    UpdateCurrentTimeHandler,
    PageInitCurrentTimeHandler
    ],
})
@NgModule({
    declarations: [],
    imports: [BrowserModule],
    providers: [],
})
export class AppModule implements DoBootstrap {
    constructor(private _injector: Injector) {}

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

Resources​

*.zip archive that contains the implemented Freedom UI app

Angular project that contains the implemented example