Custom component - CustomComponent
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.
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 going to the Library module and selecting the Custom components tab, we click the Add custom component button and in the opened window we set the name and location of the artifact being created (More information about the editor itself: Custom component editor)

JavaScript script
Each CustomComponent consists of one main function to which the Scope of the component:
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 the component's 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() - gets the current value of the component
setValue(value) - sets the current value of the component
querySelector(query) - returns a DOM structure element of the component that has been matched to 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 requirements of the ID attribute in HTML) 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 navigating to the next page to disabled (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 on whether there are validation errors on the page
Component interfaces
Example component function
In the example above, a component was defined that displays a Popup on the application with information about a positive credit decision:

In line 6, a system function was defined afterViewInit initializing the buttons X and NEXT, as well as controlling the visibility of the window. In line 2, a function was defined that is executed when one of the two buttons is clicked.
Popup DOM structure:
In the component template definition, you can refer to the defined translations using the convention _{TRANSLATION_KEY} - example in line 5.
Calling scripts or ServiceProxy
From the CustomComponent you can call ServiceProxy and ScriptService services using the methods callServiceProxy and callServiceProxyAsync. Both methods return Observable with a response in the following format:
To obtain 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 may be called in the onDestroy.
When using ServiceProxy or ScriptService, it should be added to the list of used services on the CustomComponent:

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

The defined input fields can be supplied by other application components in the same way as composite components (ComplexComponent) - by mapping the appropriate data in the INPUT PARAMETERS:

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

In this view, the key and the default value of the text handled on 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:
After clicking the button at the bottom of the panel Add translation you need to add a translation key and a default value:

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

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

Taking over messages
To have the CustomComponent handle validation messages itself, select the option in the parameters section Custom error message presentation. This option enables handling messages through the onMessagesUpdate.

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

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

The event itself can be triggered inside the customComponent JS script using the method triggerCustomEvent, for example:
Component simulation
To check the operation of the created CustomComponent, you can use the simulation function. To do this, click the button located on the right side of the screen Preview. Clicking it changes the screen to simulation mode. On the left, we will see windows JavaScript, CSS and HTML, and on the right the component parameters (provided that input parameters have been defined). After starting the preview, we can supply the component with variables retrieved in the component and observe its operation without embedding it in the application and running it in a development environment.

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

After clicking the button again Preview we will 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/composite component by adding it from the component palette. To do this, in the left sidebar click the Add component button and in the sliding component panel choose 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 allows you to find the artifact to embed more quickly. Adding a component involves dragging it from the palette and dropping it in the appropriate place in the application.

After embedding the component in the application, fill in the component's input fields (defined according to the Input fields a componentsection) by clicking in the Basic properties option 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
Remember that calling the method setInactiveForward inside afterViewInit will disable the button after each change in component visibility - therefore this should be taken into account in the implementation.
You can make the activity of the button depend on the channel in which the application is displayed using the conditional statement if , taking into account the session variables channel and channelDescritpion (remember to map them to the component beforehand).
Availability of functionality 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 the native API object (signature: callNative(nativeFunction: (api: NativeAppApi) => any): void). The api object has an interface defined by the eximee platform. The requested function on the native object will be called only if this object is available in the context.
Availability of functionality depends on the license and may not be available in all deployments.
Controlling the platform spinner
The window object provides methods for controlling the platform spinner:
startSpinner() - turns the loader on
stopSpinner() - turns the loader off
Last updated
Was this helpful?
