Namespace: reearth.ui
The UI type encompasses a broad set of functionalities to manage the user interface elements of reearth.
Description: This method displays an iframe or widget with specified HTML content and options. 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.
<aside> 💡 How the UI is displayed depends on the type of extension when visible field is true in the options: in the case of widgets, it will be displayed in the place where it is placed on the screen, in the case of blocks, it will be displayed in the infobox field, but in the case of primitives, it will never actually be displayed.
</aside>
<aside>
💡 The iframe will be automatically resized according to the size of its contents. If show is called again when an iframe has been already shown, the previous iframe will be destroyed and then a new iframe will be recreated with the new html and options.
</aside>
Syntax: reearth.ui.show(html, options) => void
Parameters:
html: string,
options?: {
// If true, display a iframe. Otherwise, hide the iframe and plugin works like headless mdoe. Default value is true. */
visible?: boolean;
// 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. */
width?: 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. */
height?: number | string;
// Override whether the iframe is extended. This option is only available for widgets on an extendable area on the widget align system. */
extended?: boolean;
}
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Display the HTML UI only
reearth.ui.show(`<h1 style="color:red;background:black">Hello world</h1>`);
// Display an iframe with specified HTML content, making it visible and auto-sized
reearth.ui.show(`<p style="color:red;background:white">Hello, Reearth!</p>`, { visible: true });
// Display the HTML UI without making it visible
reearth.ui.show(html, { visible: false });
// Display an iframe with specified dimensions and hide it (headless mode)
reearth.ui.show(`<div>Widget content here</div>`, { visible: false, width: '100%', height: 200 });
// 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 });
Description: This allows for communication between the UI and the plugin. Sent data will be automatically encoded as JSON and restored in the iframe's window. So any object that cannot be serialized to JSON will be ignored. It accepts one parameter: message.
Syntax: reearth.ui.postMessage: (message: any) => void
Parameters:
// Accepts a parameter named message, which can be of any type.
(message: any) => void
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Send a message to Re:Earth
reearth.ui.postMessage("Hello, Re:Earth!")
// Send an object message
reearth.ui.postMessage({ type: "greeting", text: "Hello, World!" });
// Send the first layer's information to the embedded UI
reearth.ui.postMessage(reearth.layers.layers?.[0]);
Description: 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).
<aside> 💡 If plugins try to resize the iframe by specifying size in the iframe's internal HTML, for example, in the body style, or by updating the CSS, iframe will not actually be resized. In that case, plugins need to call this method explicitly to resize the iframe.
</aside>
Syntax: reearth.ui.resize: (width, height, extended) => void
Parameters:
// Width of the iframe of the widget. This field is only available for widgets that are not horizontally extended. */
width: string | number | undefined,
// Height of the iframe of the widget. This field is only available for widgets that are not vertically extended. */
height: string | number | undefined,
// Optional parameter. It overrides whether the iframe is extended. This option is only available for widgets on an extendable area on the widget align system. */
extended?: boolean | undefined,
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// To auto-resize both width and height
reearth.ui.resize(undefined, undefined);
// To set specific width and height
reearth.ui.resize("300px", "200px");
// To auto-resize width, set specific height, and explicitly extend the iframe
reearth.ui.resize(undefined, "100%", true);
Description: This method is used to close or dismiss the current widget, plugin, iframe, or UI component. It provides a way to programmatically trigger the close operation, akin to a user closing it manually. 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 Usage:
// Close the currently component
reearth.ui.close();