RUAL Library

Custom Components have the ability to request specific JavaScript functions from the RUAL library. This page is dedicated to documenting the functions that are directly accessible, along with scenarios in which they might prove beneficial.

How to Use

Accessing RUAL Library functions is straightforward using window.RUAL. You can then spread the functions from the Library into your component. See the example provided below for guidance.

rual-lib.jsx

const { runBlueprintFunction } = window.RUAL;

export default function CustomButtonComponent ({  onclick }) {
  function triggerFunction () {
    runBlueprintFunction(onclick, {
      'value': 'custom-value'
    });
  }

  return (
    <button
      onClick={ triggerFunction }
    >Click me</button>
  );
}

List of Functions

Below is a list of functions available from the RUAL library for use within any Custom Component:

Call	Params	Description
`globalState`	Class	This function exposes the `globalState` along with its functions. Below is a list of functions related to `globalState`.
`globalState.set`	`key`, `newValue`	Sets a new value for the specified global key, updating the backend and refreshing the relevant pins and components.
`useGlobalState`	`defaultValue`, `globalKey`, `uid`	Enables the use of a global state key within your Custom Component. The return value functions similarly to React's `useState`.
`translate`	`key`	Attempts to translate the specified key using the currently active language.
`fetchJS`	`uid`, `hash`	Retrieves fresh JavaScript data from the backend using the supplied `hash`. This function is typically used internally.
`ws`	Class	Exposes the WebSocket and its functions. Below is a list of functions related to `ws`.
`ws.request`	`method`, `uri`, `options` as `{ body, query }`	Performs the specified request to the backend, enabling API execution within the Custom Component. Returns a `Promise`.
`settings`	Object	Provides globally available RUAL settings, such as timezone and other relevant rendering information.
`fetchComponent`	`componentFile`	Returns a valid cached React Component for use, given a path to the static custom component. This is mainly used in iterative contexts like Advanced Datatables.
`utils.getDeepvalue`	`data`, `key`, `defaultValue`	Accesses the specified `key` within an object and returns the `defaultValue` if it is not found.

Frequently asked

How do I call RUAL functions from a custom React component?

Through window.RUAL. You spread the functions from the RUAL library into your component and call them directly, for example translate, useGlobalState or fetchComponent.

How do I make an API request from a RUAL custom component?

Use ws.request with the method, the uri and an options object holding body and query. It performs the request to the backend from inside the custom component and returns a Promise.

How do I use a global state key inside a RUAL custom component?

Call useGlobalState with a default value, the global key and a uid. The return value works like React's useState, and globalState.set writes a new value that updates the backend and refreshes the relevant pins and components.