reearth.ui

The reearth.ui namespace encompasses a broad set of functionalities to manage the user interface elements of the plugin extension (widget or block).

Methods

show

This method displays custom HTML content in reearth as a plugin extension (widget or block based on plugin configuration). It allows for dynamic control over the visibility and size of the iframe, including support for an operation where the iframe is not visually displayed. It accepts two parameters: The HTML content to be displayed, and the options object which is optional.

Syntax

reearth.ui.show: (
  html: string,
  options?: Options
) => void;

Parameters

html

Type: string

A string of HTML content to be rendered.

options

Optional

Type:

type Options = {
  visible?: boolean;
  width?: number | string;
  height?: number | string;
  extended?: boolean;
};

• visible?: boolean: If true, display an iframe. Otherwise, hide the iframe and plugin works like headless mode. Default value is true.
• width?: number | string;: Initial iframe width of the widget. If not specified, the iframe will be automatically resized. If a number is specified, it will be treated as pixels. This option is only available for widgets that are not horizontally extended.
• height?: number | string;: Initial iframe height of the widget. If not specified, the iframe will be automatically resized. If a number is specified, it will be treated as pixels. This option is only available for widgets that are not vertically extended.
• extended?: boolean;: Indicates whether the iframe should occupy a larger area. When true, the iframe will expand to fill the available space in its container. This option is only available for widgets on an extendable area on the widget align system.

Return Value:

None (void). The method performs its operation without returning a value.

Example

const html = `
  <h1 style="color:red;background:white">
    Hello world
  </h1>
`;

// Display the HTML UI only
reearth.ui.show(html);

// Display the HTML UI without making it visible
reearth.ui.show(html, { visible: false });

// Display the HTML UI with a specified width and height
reearth.ui.show(html, { width: 400, height: 200 });

// Extend the iframe in an extendable area
reearth.ui.show(`<div>Extended widget content</div>`, { extended: true });

postMessage

This method sends a message to the UI component (iframe) of the plugin.

Syntax

reearth.ui.postMessage: (message: any) => void;

Parameters

message

Type: any

message can be any structured-cloneable type.

Return Value:

None (void). The method performs its operation without returning a value.

Example

//Example 1: Send a message to UI iframe
reearth.ui.postMessage("Hello, Re:Earth!");

//Example 2: Send an object message
reearth.ui.postMessage({ type: "greeting", text: "Hello, World!" });

resize

Adjusts the size of an iframe used by the plugin. If width or height is undefined, it will be auto-resized. If a number is specified, it will be treated as pixels. It takes three parameters: width, height and extended (which is optional).

Please note that the UI iframe will automatically resize base on the content size. This method is useful when you want to manually set the size of the iframe.

Syntax

reearth.ui.resize(
  width: string | number | undefined,
  height: string | number | undefined,
  extended?: boolean | undefined
) => void;

Parameters

width

Type: string | number | undefined

Width of the iframe of the widget. This field is only available for widgets that are not horizontally extended.

height

Type: string | number | undefined

Height of the iframe of the widget. This field is only available for widgets that are not vertically extended.

extended?

Optional

Type: boolean | undefined

Optional parameter. A boolean indicating whether to extend the iframe. This option is only available for widgets on an extendable area on the widget align system.

• true: The UI element is extended.
• false: The UI element is not extended.
• undefined: Leaves the extended state unchanged.

Example

// Example 1: Resize the UI to 400px by 300px
reearth.ui.resize(400, 300);

// Example 2: Extend the UI element without changing its size
reearth.ui.resize(undefined, undefined, true);

// Example 3: Change only the height to 500px and leave other properties unchanged
reearth.ui.resize(undefined, 500);

close

This method is used to close or dismiss the current UI widget. It provides a way to programmatically trigger the close operation. It takes no parameters.

Syntax

reearth.ui.close: () => void

Parameters

None

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Close the currently ui widget
reearth.ui.close();

Events

Note

For more information about common event methods (on, off), refer to the Events page.

update

The update event is triggered whenever the state or content of the UI changes. This can be useful for tracking changes to the UI state or refreshing content based on the latest data.

Syntax

reearth.ui.on("update", () => void): void;

Example

reearth.ui.on("update", () => {
  console.log("UI updated!");
});

close

The close event is triggered when the UI is closed. This event can be used to perform clean-up actions, save data, or notify other components that the UI is no longer active.

Syntax

reearth.ui.on("close", () => void): void;

Example

reearth.ui.on("close", () => {
  console.log("The UI was closed.");
});