Custom component - CustomComponent

The availability of functionality depends on the license and may not be available in all deployments.

The custom component (CustomComponent) allows you to create your own components for the application using the JavaScript.

A CustomComponent consists of eight elements:

• JavaScript script,

• component CSS styles,

• component HTML template,

• mappings of the component's input parameters,

• list of used services,

• list of actions available for this component,

• translations of texts for the component,

• preview.

Creating a component

A new component is created in the same way as other components. After navigating to the Library module and selecting the Custom components tab, click the Add custom component button and in the opened window set the name and location of the created artifact (More information about the editor itself: Custom Components Editor)

Illustration 1. Edit view of a newly created component

JavaScript script

Each CustomComponent consists of a single main function to which the component Scope is passed:

function($scope) {
  
}

Using the scope, the creator can, among other things, retrieve component data, input data, and react to certain lifecycle events of the component. The user can implement three system component methods:

• afterViewInit - executed when the component is added to the application's DOM structure,

• onModelChange - executed when the component's model (e.g., value) or input values change,

• onDestroy - executed when the component is removed from the application's DOM structure.

Additionally, the component scope provides several useful elements:

• fields:

  • domId - the component's ID in the application's DOM structure

  • componentId - the component ID

  • componentMid - the component MID

  • visible - variable controlling the component's visibility

  • translations - map of translations defined at component creation stage

  • componentId - map of component input parameters

  • componentData - map of the component's internal data (allows preserving the component's state)

  • componentInput - map of the component's input data (keys are defined in the Inputs section, separated by commas)

• methods:

  • getValue() - retrieves the component's current value

  • setValue(value) - sets the component's current value

  • querySelector(query) - returns the DOM element of the component that matched the selector.

  • putData(key, value) - sets a specified value (value) under the key (key) in the component data map - client-side only in the browser

  • saveData(key, value) - sets a specified value (value) under the key (key) in the component data map - also on the server side

  • getData(key) - retrieves the value stored under the key (key) in the component data map

  • translate(key) - returns the translation from the translations map

  • clean() - cleans the scope object when it is no longer used by the CustomComponent

  • callServiceProxy(serviceName, params) - allows calling ServiceProxy and ScriptService services synchronously

  • callServiceProxyAsync(serviceName, params) - allows calling ServiceProxy and ScriptService services asynchronously

  • initTooltip(id, element, data) - allows initializing a tooltip with the given identifier (required value, must meet all HTML ID attribute requirements) on the provided element

  • showTooltip(id) - shows the tooltip with the given id

  • hideTooltip(id) - hides the tooltip with the given id

  • destroyTooltip(id) - destroys the tooltip with the given id

  • destroyAllTooltips() - destroys all tooltips of the given component

  • goForward() - navigates to the next (allowed) page or submits the application (when the user is on the last page of the application)

  • goBackward() - navigates to the previous (allowed) page

  • setInactiveForward() - sets the button that navigates to the next page to locked (The availability of functionality depends on the license and may not be available in all deployments.)

  • setActiveForward() - sets the button that navigates to the next page to active (The availability of functionality depends on the license and may not be available in all deployments.)

  • triggerCustomEvent(eventName) - allows invoking a CustomEvent previously defined for the given component

  • sendCurrentValueEvent() - sends an event containing the current value of the CustomComponent along with its id

  • isPageValid() - returns information whether there are validation errors on the page

Component interfaces

interface ExCustomComponentScope {
    // Methods that can be provided
    onDestroy?: () => void;
    afterViewInit?: () => void;
    onModelChange?: () => void;
    onMessagesUpdate?: (messages: ExWidgetMessage[]) => void;
 
    // Fields provided by the platform
    domId: string;
    componentId: string;
    componentMid: string;
    translations: { [key: string]: string; };
    componentInput: { [key: string]: string[]; };
    componentData: { [key: string]: string; };
    serviceResponses: { [key: string]: { [key: string]: string }[] };
    visible: boolean;
 
    // Methods provided by the platform - should not be overridden
    callNative(nativeFunction: (api: NativeAppApi) => any): void
    getValue(): string;
    setValue(value: string): void;
    /**
     * @deprecated New CustomComponents should use querySelector
    */
    queryChild(query: string): JQuery;
    querySelector(query: string): Element;
    putData(key: string, value: string): void;
    saveData(key: string, value: string): void;
    getData(key: string): string;
    translate(key: string): string;
    schedule(func: () => any): void;
    clean(): void;
    callServiceProxy(serviceName: string, params: { [key: string]: string[] }): Observable<ExServiceProxyResponse>;
    callServiceProxyAsync(serviceName: string, params: { [key: string]: string[] }): Observable<ExServiceProxyResponse>;
    initTooltip(id: string, element: any, data: ExWidgetTooltip): void;
    destroyTooltip(id: string): void;
    showTooltip(id: string): void;
    hideTooltip(id: string): void;
    destroyAllTooltips(): void;
    goForward(): void;
    goBackward(): void;
    setActiveForward(): void;
    setInactiveForward(): void;
    triggerCustomEvent(event: string): void;
    sendCurrentValueEvent(): void;
    isPageValid(): Observable<boolean>;
}
 
interface ExServiceProxyResponse {
    name: string;
    componentId: string;
    response: { [key: string]: string }[];
}
 
interface ExWidgetTooltip {
    text: string;
    position: ExWidgetTooltipPosition;
    type: ExWidgetTooltipType;
    width?: number;
    height?: number;
    styleClasses?: string;
    onFocus?: boolean;
}
 
enum ExWidgetTooltipPosition {
    TOP,
    BOTTOM,
    LEFT,
    RIGHT,
    ADAPTIVE,
// Deprecated:
    LEFT_TOP,
    LEFT_BOTTOM,
    RIGHT_TOP,
    RIGHT_BOTTOM
}
 
enum ExWidgetTooltipType {
    HOVER,
    BUTTON
}
interface ExWidgetMessage {
    getMessage(): string;
    getType(): ExWidgetMessageType;
}
 
enum ExWidgetMessageType {
    VALIDATION_POPUP,
    VALIDATION,
    INFO,
    COMPONENT_INFO
}

Example of a component function

function($scope) {
      $scope.closePopup = function() {
        $scope.queryChild('.kg-positive-decision-popup-wrapper').fadeOut(200);
        $scope.saveData('visible', 'false');
      };
      $scope.afterViewInit = function() {
        let visible = $scope.getData('visible');
        if(visible === 'false') {
          $scope.queryChild('.kg-positive-decision-popup-wrapper').hide();
        } else {
          $scope.closeButton = $scope.queryChild('.kg-positive-decision-popup-close-button');
          $scope.closeButton.on('click', $scope.closePopup);
          $scope.nextButton = $scope.queryChild('.kg-positive-decision-popup-next-button');
          $scope.nextButton.on('click', $scope.closePopup)
        }
      };
    }

In the above example, a component presenting a popup on the application with information about a positive credit decision was defined:

Illustration 2. Popup designed using a CustomComponent

In line 6 a system function was defined afterViewInit initializing the buttons X and NEXT, and controlling the window's visibility. In line 2 a function executed when one of the two buttons is clicked was defined.

DOM structure of the popup:

<div class='kg-positive-decision-popup-wrapper'>
  <div class='kg-positive-decision-popup'>
    <div class='kg-positive-decision-popup-title-wrapper'>
        <div class='kg-positive-decision-popup-title'>
            _{kg.positive.decision.popup.title}
        </div>
        <button class='kg-positive-decision-popup-close-button'></button>
        <div class='clear'></div>
    </div>
    <div class='kg-positive-decision-popup-content-wrapper'>
        <div class='kg-positive-decision-popup-content-first-paragraph'>
            _{kg.positive.decision.popup.content.first.paragraph}
        </div>
        <div class='kg-positive-decision-popup-content-second-paragraph'>
            _{kg.positive.decision.popup.content.second.paragraph}
        </div>
    </div>
    <div class='kg-positive-decision-popup-next-button-wrapper'>
        <button class='kg-positive-decision-popup-next-button'>_{kg.positive.decision.popup.next.button}</button>
        <div class='clear'></div>
    </div>
  </div>
</div>

In the component template definition you can refer to defined translations using the convention _{TRANSLATION_KEY} - example in line 5.

Calling scripts or ServiceProxy

From within a CustomComponent you can call ServiceProxy and ScriptService services using the methods callServiceProxy and callServiceProxyAsync. Both methods return an Observable with a response in the following format:

{
    name: string;
    componentId: string;
    response: { [key: string]: string }[];
}

To obtain the response you should call the .subscribe() method known from RxJS. As in RxJS, it is also advisable to call unsubscribe() at the appropriate time on the returned object. For example, unsubscribe can be invoked in the onDestroy

method.

When using ServiceProxy or ScriptService, it should be added to the list of used services on the CustomComponent: Illustration 3.

"Used services" section

Component input fields In the Input data

section the ids of the component input fields are defined. Ids should not contain spaces. Illustration 4.

"Input data" section Defined input fields can be fed by other application components in the same way as complex components (ComplexComponent) - by mapping the appropriate data in the:

INPUT PARAMETERS section

Illustration 5.

Example of the "Input parameters" section for a CustomComponent added to the application TranslationsDedicated internationalized texts are defined in the Illustration 5..

Component translations section, which is displayed after selecting the button in the left panel

Illustration 6a.

"Component translations" section

1. In this view the key and the default value of the text used on the CustomComponent are defined. Translations of the text into required languages are defined in the standard way on the application where the component was attached. Example of adding a translation key: After clicking the

   

   Add translation button at the bottom of the panel, you should add the translation key and the default value:
2. Illustration 6b.

Adding a new key and translation The added translation key can be used in the CustomComponent's DOM structure:

1. Illustration 6c. Illustration 5. "DOM" section with the example key "kg-final-survey-popup-title" entered

After adding the CustomComponent to the application or to a complex component in the tab, the keys from the CustomComponent will appear. They can also be added manually.

Illustration 6d.

"Translations" tab with keys of the CustomComponent Handling messagesFor the CustomComponent to handle validation messages itself, you must check the option in the parameters section Custom presentation of error message.

. This option allows handling messages via the onMessagesUpdate

method

Illustration 7.The "Custom presentation of error message" option enabledDefining custom events for the component

For each CustomComponent you can define individual actions ( CustomEvents

). They are attached and handled in the same way as standard events defined on the platform. The action definition looks as follows:

Illustration 8. Actions added for the component

Such defined actions can be attached on the application to a given action. For example, the TEST_EVENT_A action is used to open a popup: Illustration 9.Application properties view - "Actions" section with an action defined from the CustomComponent

The event itself can be invoked inside the customComponent's JS script using the method

triggerCustomEvent

, for example: $scope.triggerCustomEvent('TEST_EVENT_A');Component simulation JavaScript, To check the operation of the created CustomComponent you can use the simulation function. To do this, click the Preview button located on the right side of the screen. Clicking it changes the screen to simulation mode. On the left side we will see theCSS

and HTML

panels, and on the right the component parameters (provided that input parameters have been defined). After launching the preview we can feed the component with variables available in the component and observe its behavior without having to embed it in the application and run it in the development environment. Illustration 10.Component view with preview enabled, without filling in input parameters If you want changes in the preview to appear in real time, before filling in the component parameter fields it is worth checking theAuto refresh option. After filling in all fields click the.

Refresh button. Then the fields with entered values are hidden and the component appearance is shown. You can always display the entered parameters by clicking the option with the number of parameters and the label

(show) $scope.triggerCustomEvent('TEST_EVENT_A'); Illustration 11.

Component view with simulation

Clicking the button again will return us to the standard component view with the list of parameters on the left side. Embedding in the application The created CustomComponent is embedded in the application/complex component by adding it from the component palette. To do this, click theAdd component button in the left side panel and in the expanded components panel select the

Custom tab, which is available after clicking the

symbol. A list of CustomComponents available in the repository will be displayed. The top of the panel contains a search field that allows you to quickly find the artifact to be embedded. Adding a component involves dragging it from the palette and dropping it in the appropriate place on the application. Illustration 12. List of components after clicking the Custom tab) After embedding the component in the application, you must populate the component's input fields (defined according to the Input fields section of the component) by clicking in the Basic - by mapping the appropriate data in the:

properties option

Illustration 13.

Window for defining CustomComponent input parameters

• Controlling the activity of the button that navigates to the next page In the JavaScript tab of the edited CustomComponent we can use the methods:

• setInactiveForward()- sets the button that navigates to the next page to locked

setActiveForward () - sets the button that navigates to the next page to active Keep in mind that calling the afterViewInit setInactiveForward

method inside will cause the button to be locked after every change in the component's visibility - so this should be taken into account in the implementation. Controlling the button's activity can be conditioned on the channel in which the application is displayed using the conditional statement if Preview , taking into account the session variables channel

The availability of functionality depends on the license and may not be available in all deployments.

channelDescription

(remember to map them to the component beforehand). Calling the native APIThe $scope object provides the

function($scope) {
    $scope.afterViewInit = function() {
        callNative
    }
}

The availability of functionality depends on the license and may not be available in all deployments.

function, which accepts a function whose parameter is the native API object (signature: callNative(nativeFunction: (api: NativeAppApi) => any): void). The api object has an interface defined by the eximee platform. The function requested on the native object will be called only if that object is available in the context.

$scope.callNative(nativeApi => nativeApi.setTitle('title'));

• Controlling the platform loader

• The window object provides methods to control the platform loader: