Script

Learn about custom scripts needed for custom components.

Every custom component requires a custom script. Specify the script file in the action property of the component's UI configuration.

Important: Custom script is executed inside the sandbox and does not have access to the DOM tree of the UI client, local storage, or any other parameters directly. However, there is a way to communicate with the UI client and execute different actions. To do this, you must use global object UI in your custom script and call async methods on this object.

General

The following example shows the API path and UI configuration of a custom component. The linked script (iframe.js) uses this configuration to render a B2B integration view and call alerts on the UI client.


{
  "id": "bbChartView",
  "component": "CustomActionView",
  "caption": "B2B Integration",
  "url": "https://cgraph-dev.reltio.com/custom-graph/bbChart?entityUri=",
  "height": 200,
  "action": {
    "files": [
      "https://dl.dropboxusercontent.com/u/465285497/iframe.js"
    ]
  }
}

UI Object methods

The global UI object provides methods that enable custom scripts to communicate with the UI client. The following table describes the available methods, their syntax, parameters, and usage.


Method	Syntax	Description	Parameters	Notes/Example
`log`	`UI.log(message)`	Logs a message for debugging.	message (String \| Object): Message or object to log.	—
`setEnabled`	`UI.setEnabled(value)`	Changes the enabled state of a control. Use only with custom buttons.	value (Boolean): Specifies whether the control is enabled.	—
`setVisibility`	`UI.setVisibility(value)`	Changes the visibility state of a control.	value (String): `visible`, `hidden`, or `excluded`.	—
`setHtml`	`UI.setHtml(html)`	Sets the widget's internal HTML. Use only with custom views.	html (String): HTML content.	—
`setChildHtml`	`UI.setChildHtml(id, html)`	Sets the internal HTML of a child widget. Use only with custom views.	id (String): Child widget ID.html (String): HTML content.	—
`setHeight`	`UI.setHeight(height)`	Sets the widget height. Use only with custom buttons and custom views.	height (Number): Height in pixels.	—
`setWidth`	`UI.setWidth(width)`	Sets the widget width. Use only with custom buttons and custom views.	width (Number): Width in pixels.	Correct parameter name from the current topic.
`setToolTip`	`UI.setToolTip(toolTip)`	Sets the widget tooltip.	toolTip (String): Tooltip text.	—
`onAction`	`UI.onAction(function(){...})`	Entry point that runs after all scripts are loaded.	None	Deprecated. Use `UI.onEvent()` and listen for the `"execute"` event instead.
`onEvent`	`UI.onEvent(function(type, data){...})`	Registers an event handler that runs when an event occurs.	type (String): Event type.data (String \| Object): Event-specific data.	Supported events: `execute`, `updateEntity`, `changeSearchQuery`, `changeVisibility`, `uiAction`.
`getEntityUri`	`UI.getEntityUri()`	Retrieves the current entity URI.	None	Returns a Promise.
`getEntity`	`UI.getEntity()`	Retrieves the current entity.	None	Returns a Promise.
`getApiPath`	`UI.getApiPath()`	Retrieves the current API path.	None	Returns a Promise.
`getSearchQuery`	`UI.getSearchQuery()`	Retrieves the current search query.	None	Returns a Promise.
`getTenant`	`UI.getTenant()`	Retrieves the current tenant name.	None	Returns a Promise.
`getPerspective`	`UI.getPerspective()`	Retrieves the current perspective ID.	None	Returns a Promise.
`setPerspective`	`UI.setPerspective(perspective)`	Sets the current perspective.	perspective (String): Perspective ID.	Returns a Promise.
`setEntityUri`	`UI.setEntityUri(entityUri)`	Sets the current entity URI.	entityUri (String): Entity URI.	Returns a Promise.
`api`	`UI.api(url, method, tenant, headers, data)`	Sends an API request or an external request.	url (String): Request URL.method (String): `GET`, `POST`, `PUT`, or `DELETE`.tenant (String): Tenant name.headers (Object): Request headers.data (Object \| String): Request body.	Example: `UI.api('https://test.reltio.com/nui/version', 'GET')`
`alert`	`UI.alert(text)`	Displays an alert dialog.	text (String): Alert message.	Returns a Promise.
`confirm`	`UI.confirm(text)`	Displays a confirmation dialog.	text (String): Confirmation message.	Returns a Promise that resolves with the user's response.
`prompt`	`UI.prompt(text, defaultText)`	Displays a prompt dialog.	text (String): Prompt message.defaultText (String): Default value.	Returns a Promise that resolves with the user's input.
`getConfiguration`	`UI.getConfiguration()`	Retrieves the metadata configuration.	None	Returns a Promise.
`getUiConfiguration`	`UI.getUiConfiguration()`	Retrieves the UI configuration of the current custom component.	None	Returns a Promise.
`openSearch`	`UI.openSearch(searchState)`	Opens the search screen with the specified state.	searchState (Object): Search state JSON.	Returns a Promise.

Supported event types

The onEvent() method supports the following event types:


Event	Description
`execute`	Triggered when a custom button or menu item is selected. The `data` parameter is `null`.
`updateEntity`	Triggered when a new entity is loaded. The `data` parameter contains the entity JSON.
`changeSearchQuery`	Triggered when the search criteria change. The `data` parameter contains the search query string.
`changeVisibility`	Triggered when the visibility of a custom component changes. The `data` parameter is `true` or `false`.
`uiAction`	Triggered when a specified UI action occurs on a DOM element in a custom view. The `data` parameter contains the action type, element ID, and event object.

Unify and manage your data

Script

General

UI Object methods

Supported event types

Footer