Custom component - CustomComponent

Feature availability 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 language JavaScript.

A CustomComponent consists of eight elements:

• JavaScript script,
• Component CSS styles,
• Component HTML template,
• Component input parameter mappings,
• 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 going 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 artifact being created (More information about the editor itself: Custom components editor)

Figure 1. Editing view of the newly created component

JavaScript script

Each CustomComponent consists of one main function, to which the Scope of the component is passed:

function($scope) {
  
}

Using the scope, the creator can, among other things, retrieve component data, input data, and react to certain events from the component lifecycle. 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 model (e.g. value) of the component or the input data value changes,
• onDestroy - executed when the component is removed from the application's DOM structure.

Additionally, the component scope provides several useful elements:

• fields:

  • domId - component ID in the application's DOM structure
  • componentId - component ID
  • componentMid - component MID
  • visible - variable controlling component visibility
  • translations - translation map defined at the component creation stage
  • componentId - map of component input parameters
  • componentData - map of internal component data (allows the component state to be preserved)
  • componentInput - map of component input data (keys are defined in the Inputs section, separated by commas)
• methods:

  • getValue() - retrieves the current value of the component
  • setValue(value) - sets the current value of the component
  • querySelector(query) - returns the DOM element of the component that matched the selector.
  • putData(key, value) - sets the specified value (value) under the key (key) in the component data map - browser client side only
  • saveData(key, value) - sets the specified value (value) under the key (key) in the component data map - also on the server side
  • getData(key) - retrieves the value specified under the key (key) in the component data map
  • translate(key) - returns a translation from the translation map
  • clean() - clears 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 passed 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 navigating to the next page to inactive (Feature availability depends on the license and may not be available in all deployments.)
  • setActiveForward() - sets the button navigating to the next page to active (Feature availability depends on the license and may not be available in all deployments.)
  • triggerCustomEvent(eventName) - allows triggering a CustomEvent previously defined for a 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 - do not override them
    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 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 was defined that displays a Popup on the application with information about a positive credit decision:

Figure 2. Popup designed using a CustomComponent

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

Popup DOM structure:

<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 a CustomComponent, you can call ServiceProxy and ScriptService services using the methods callServiceProxy and callServiceProxyAsync. Both methods return Observable with response in the following format:

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

To get the response you need to call the .subscribe() method known from RxJS. As in RxJS, it is also worth calling unsubscribe() at the appropriate time on the returned object. For example, unsubscribe can be called in the onDestroy.

When using ServiceProxy or ScriptService, you need to add it to the list of used services on the CustomComponent:

Figure 3. Section "Used services"

Component input fields

In the Input data section, the IDs of the component input fields are defined. IDs should not contain spaces.

Figure 4. Section "Input data"

The 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:

Figure 5. Example of the "Input parameters" section for a CustomComponent added to the application

Translations

Dedicated internationalized texts are defined in the Component translationssection, which appears after selecting the Translations.

Figure 6a. Section "Component translations"

In this view, the key and default value of the text handled in the CustomComponent are defined. Text translations in the required languages are defined in the standard way on the application to which the component has been attached.

Example of adding a translation key:

1. After clicking the Add translation button at the bottom of the panel, add a translation key and a default value:

   

   Figure 6b. Adding a new key and translation
2. The added translation key can be used in the CustomComponent DOM structure:

Figure 6c. Section "DOM" with the example key "kg-final-survey-popup-title" entered

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

Figure 6d. "Translations" tab with CustomComponent keys

Handling messages

To make the CustomComponent handle validation messages itself, select the option in the parameters section Custom error message display. This option allows message handling via the method onMessagesUpdate.

Figure 7. Enabled "Custom error message display" option

Defining custom events for the component

For each CustomComponent, individual actions can be defined (CustomEvents). They are attached and handled in the same way as standard events defined in the platform. The action definition looks as follows:

Figure 8. Actions added for the component

Actions defined in this way can be attached on the application to a given action. For example, the TEST_EVENT_A action is used to open the popup:

Figure 9. Application properties view - "Actions" section with the action defined from the CustomComponent

The event itself can be invoked inside the CustomComponent's JS script using the triggerCustomEventmethod, for example:

$scope.triggerCustomEvent('TEST_EVENT_A');

Component simulation

To check the operation of the created CustomComponent, you can use the simulation function. To do this, click the Previewbutton located on the right side of the screen. Clicking it changes the screen to simulation mode. On the left side you will see the JavaScript, CSS and HTMLwindows, and on the right the component parameters (provided that input parameters have been defined). After starting the preview, we can feed the component with variables retrieved in the component and observe its behavior without having to embed it in the application and run it in the development environment.

Figure 10. Component view with preview enabled, without filling in input parameters

If we want changes in the preview to be shown live, before filling in the component parameter field values it is worth selecting the option Automatic refresh. After filling in all fields, click the Refreshbutton. The fields with entered values will then hide, and the component view will appear. You can always show the filled-in parameters by clicking the option with the number of parameters and the label (show).

Figure 11. Component view with simulation

After clicking the Preview button again, we return 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/in a complex component by adding it from the component palette. To do this, click the Add component button in the left sidebar and in the slid-out component panel select the Customtab, which is available after clicking the symbol . A list of CustomComponents available in the repository will be displayed. At the top of the panel there is a search field that makes it easier to find the artifact to embed. Adding the component consists of dragging it from the palette and dropping it in the appropriate place on the application.

Figure 12. List of components after clicking the Custom tab

After embedding the component in the application, you need to feed the component input fields (defined according to the Input fields of the componentsection) by clicking in the Basic properties option INPUT PARAMETERS:

Figure 13. Window for defining CustomComponent input parameters

Controlling the activity of the button navigating to the next page

In the JavaScript tab of the edited CustomComponent, we can use the methods:

• setInactiveForward() - sets the button navigating to the next page to disabled
• setActiveForward() - sets the button navigating to the next page to active

It should be remembered that calling the method setInactiveForward inside afterViewInit will disable the button after every change in component visibility - therefore this should be taken into account in the implementation.

The button's activity can be made dependent on the channel in which the request is displayed using a conditional statement if , taking session variables into account channel and channelDescription (remember to map them to the component beforehand).

Feature availability depends on the license and may not be available in all deployments.

Calling the native API

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

function($scope) {
    $scope.afterViewInit = function() {
        $scope.callNative(nativeApi => nativeApi.setTitle('title'));
    }
}

Feature availability depends on the license and may not be available in all deployments.

Controlling the platform loader

On the window object, methods are available that allow controlling the platform loader:

• startSpinner() - turns on the loader
• stopSpinner() - turns off the loader