Version: 8.1

Custom request handler implemented using remote module

Level: intermediate

Creatio lets you implement the business logic of the Freedom UI page using request handlers. Creatio executes request handlers when an event is triggered on a visual element of a Freedom UI page. You can use base request handlers or implement a new one. Base handlers are executed at different life cycle stages. Learn more: Creatio front-end architecture.

For example, use request handlers to customize the data export from section list. To do this, add a button to the Freedom UI page, implement a custom request handler and bind the sending of custom request to the clicked button event. Learn more: Excel data export (user documentation).

You can modify the business logic of a request handler based on the type of related request. View the request type in the component documentation or source code of the schema that implements the request logic.

You can implement a custom request handler in the following ways:

Use the handlers schema section of the Freedom UI page. Supported in Creatio 8.0 Atlas and later. View examples that invoke handlers in separate articles: Page customization examples.
Use a remote module.

To implement a custom request handler using remote module:

Create an Angular project to develop a custom request handler using remote module.
Create a custom request using remote module.
Create a custom service using remote module.
Create custom request handlers using remote module.
Add the request implemented using remote module to the Freedom UI page.

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

Develop a custom request handler in a dedicated npm package using an external IDE. This example covers the request handler development in Microsoft Visual Studio Code.

You can create an Angular project to develop a custom request handler 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 request using remote module

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

As a result, Microsoft Visual Studio Code will add the SomeRequestNameRequest class files to the src/app/ project directory.
Implement the request.
1. Open the some-request-name.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.
some-request-name.request.ts file
```
/* Import the required functionality from the libraries. */
import { BaseRequest } from "@creatio-devkit/common";

export class SomeRequestNameRequest extends BaseRequest{
  /* The type and parameters of the request. */
  public someParameterName!: someParatemerType;
}
```
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. Create a custom service using remote module

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

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

Implement the service that receives data from external web service.

Open the some-service-name.service.ts file.
Flag the SomeServiceNameService class using the Injectable decorator.
Implement the someMethodName() method that receives data from external web service.
Import the required functionality from the libraries into the class.
Save the file.

some-service-name.service.ts file
/* Import the required functionality from the libraries. */
import { Injectable } from "@angular/core";

@Injectable({
  providedIn: 'root',
})
export class SomeServiceNameService {
  /* Receive data from external web service. */
  public someMethodName(someParameterName: someParatemerType): Promise<{
    someParameterName: Record<string, number>
  }> {
    /* Implement the business logic. */
    ...

    /* Return data from external web service. */
    return Promise.resolve({
      someParameterName: {'someParameterName': /* Receive data from external web service. */ }
    });
  }
}

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

Create a custom handler that displays data received from the external web service on the Freedom UI page.

Set up the Freedom UI page.

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

Add a SomeAttributeName attribute that stores data received from the external web service to the viewModelConfigDiff schema section.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG*/{
    "attributes": {
        ...,
        /* The attribute that stores data received from the external web service. */
        "SomeAttributeName": {}
    }
}/**SCHEMA_VIEW_MODEL_CONFIG*/,

Bind the caption property of the corresponding component to the $SomeAttributeName model attribute in the viewConfigDiff schema section.

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

Click Save on the Client Module Designer's toolbar.

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

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

Implement the handler.

Open the some-handler-name.handler.ts file.
Add the configuration object that declares the request handler.
- Set type property to usr.SomeHandlerNameHandler. The type property is the type of handler.
- Set requestType property to crt.UpdateCurrentTimeRequest. The type property is the type of request to execute the handler specified in the type property.
Flag the SomeHandlerNameHandler class using the CrtRequestHandler decorator.
Inherit the BaseRequestHandler class from the @creatio-devkit/common library.
Implement the handling of the request result.
Generate the value to display in the component of Freedom UI page.
Import the required functionality from the libraries into the class.
Save the file.

some-handler-name.handler.ts file
/* Import the required functionality from the libraries. */
import { BaseRequestHandler, CrtRequestHandler } from "@creatio-devkit/common";
import { SomeServiceNameService } from "./some-service-name.service";
import { SomeRequestNameRequest } from "./some-request-name.request";

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

export class SomeHandlerNameHandler extends BaseRequestHandler{
  constructor(private _someServiceNameService: SomeServiceNameService) {
    super();
  }
  public async handle(request: SomeRequestNameRequest): Promise<unknown> {
    const result = await this._someServiceNameService.someMethodName(request.someParameterName);
    const someParameter1Name = result.someParameterName[request.someParameterName] ?? 0
    /* Generate the value to display in the component of Freedom UI page. */
    request.$context['SomeAttributeName'] = someParameter1Name;
    return someParameter1Name;
  }
}

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 some-handler1-name.handler command at the command line terminal of Microsoft Visual Studio Code.
  
  As a result, Microsoft Visual Studio Code will add the SomeHandler1NameHandler class files to the src/app/ project directory.
2. Implement the handler.
  1. Open the some-handler1-name.handler.ts file.
  2. Add the configuration object that declares the request handler.
    - Set type property to usr.SomeHandler1NameHandler.
    - Set requestType property to crt.HandleViewModelInitRequest.
    - Set scopes property to code of Freedom UI page. The request handler is executed when Creatio initializes the Freedom UI page that has the specified code. If the property is empty or missing, it is a global handler that Creatio executes on all Freedom UI pages.
  3. Flag the SomeHandler1NameHandler class using the CrtRequestHandler decorator.
  4. Inherit the BaseRequestHandler class from the @creatio-devkit/common library.
  5. Implement the update of data received from the external web service when Creatio initializes the Freedom UI page.
  6. Import the required functionality from the libraries into the class.
  7. Save the file.
  some-handler1-name.handler.ts file
```
/* Import the required functionality from the libraries. */
import { BaseRequest, BaseRequestHandler, CrtRequestHandler, HandlerChainService } from "@creatio-devkit/common";
import { SomeRequestNameRequest } from "./some-request-name.request";

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

export class SomeHandler1NameHandler extends BaseRequestHandler{
  public async handle(request: BaseRequest): Promise<unknown> {
    /* Update data received from the external web service when Creatio initializes the Freedom UI page. */
    await HandlerChainService.instance.process({
      type: 'crt.SomeRequestNameRequest',
      someParameterName: 'someParameterValue',
      $context: request.$context
    } as SomeRequestNameRequest);
    
    return this.next?.handle(request);
  }
}
```

Open the app.module.ts file.
Add the SomeHandlerNameHandler and SomeHandler1NameHandler handlers to the requestHandlers section in the CrtModule decorator.
Import the required functionality from the libraries into the class.
Save the file.

app.module.ts file
/* Import the required functionality from the libraries. */
import { CrtModule } from '@creatio-devkit/common';
import { SomeHandlerNameHandler } from './some-handler-name.handler';
import { SomeHandler1NameHandler } from './some-handler1-name.handler';
...

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

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.

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

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

Change the property value of the corresponding component in the viewConfigDiff schema section to request configuration object.

Enter the 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": "SomeButtonName",
        "values": {
            ...,
            "clicked": {
                /* Bind the sending of the custom request to the button click event. */
                "request": "crt.SomeRequestNameRequest",
                "params": {
                    "someParameterName": "someParameterValue"
                }
            }
        },
        ...
    },
    ...
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

Click Save on the Client Module Designer’s toolbar.

As a result, Creatio will add the request to the Freedom UI page. When an event initiates a request, the related handler will be executed.

Resources

Page customization examples

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

2. Create a custom request using remote module​

3. Create a custom service using remote module​

4. Create custom request handlers using remote module​

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

See also​

Resources​

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

2. Create a custom request using remote module

3. Create a custom service using remote module

4. Create custom request handlers using remote module

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

See also

Resources