reearth.modal

The reearth.modal namespace defines the structure and capabilities of modal dialog components within reearth.

Methods

show

This method displays a modal window with customizable HTML content in reearth. Developers can define the modal’s size, background, and behavior when clicking outside the modal.

Syntax

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

Parameters

html

Type: string

A string of HTML content to be displayed in the modal.

options

Optional

An object to customize the modal’s appearance and behavior:

Type:

type Options = {
  width?: number | string;
  height?: number | string;
  background?: string;
  clickBgToClose?: boolean;
};

• width?: number | string;: Specifies the width of the modal. If not specified, a default width may be used.
• height?: number | string;: Specifies the height of the modal. The absence of this parameter may result in a default height.
• background?: string;: The background color or CSS value for the modal (e.g., “#fff”, “rgba(0, 0, 0, 0.5)”).
• clickBgToClose?: boolean;: Determines whether clicking on the modal background will close the modal. Set to true to enable this feature, otherwise, it defaults to false.

Return Value:

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

Example

// Example 1: Display a modal with custom HTML content
reearth.modal.show("<p>Welcome to Reearth!</p>", {
  width: 400,
  height: 300,
  background: "rgba(0, 0, 0, 0.5)",
  clickBgToClose: true,
});

// Example 2: Display a modal with a larger, fixed-size and solid background
reearth.modal.show(
  "<h1>Important Information</h1><p>Details about the project...</p>",
  {
    width: 600,
    height: 400,
    background: "#f8f8f8",
    clickBgToClose: false,
  }
);

postMessage

This enables communication between a modal window and other parts of reearth , or between components within the modal itself. It can be utilized for a variety of purposes, such as notifying reearth about user interactions within the modal or requesting data or actions from other components.

Syntax

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

Parameters

message

Type: any

The message to be sent to the modal.

Return Value:

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

Example

// Example 1: Send a simple text message
reearth.modal.postMessage("Hello, Re:Earth!");

// Example 2: Send a simple string message to the Reearth application
reearth.modal.postMessage("User clicked the button!");

// Example 3: Send an object message
reearth.modal.postMessage({ message: "greeting" });

// Example 4: Sending an object containing user data
reearth.modal.postMessage({
  eventType: "userAction",
  details: {
    action: "submit",
    userId: 12345,
  },
});

update

This method modifies the appearance and behavior of the currently open modal in reearth. It allows developers to dynamically adjust properties like the modal’s size, background color, and click-to-close behavior.

Syntax

reearth.modal.update: (options: Options) => void;

Parameters

options

An object that contains properties to update the modal’s appearance and behavior.

Type:

type Options = {
  width?: number | string;
  height?: number | string;
  background?: string;
  clickBgToClose?: boolean;
};

• width?: number | string;: Sets the modal’s new width.
• height?: number | string;: Sets the modal’s new height.
• background?: string;: Sets a new background for the modal.
• clickBgToClose?: boolean;: Determines whether clicking outside the modal will close it. true allows the modal to close when the user clicks the background. false prevents the modal from closing on background clicks.

Return Value:

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

Example

// Example 1: Resize the modal to 300px width and 400px height with a light blue background
reearth.modal.update({
  width: 300,
  height: 400,
  background: "#ADD8E6",
  clickBgToClose: true,
});

// Example 2: Update the modal with a a custom background color, larger size, and disable click-to-close
reearth.modal.update({
  width: 600,
  height: 450,
  background: "rgba(0, 128, 128, 0.8)",
  clickBgToClose: false, // Prevent closing the modal by clicking the background
});

// Example 3: Allow the modal to close when clicking the background
reearth.modal.update({
  clickBgToClose: true,
});

// Example 4: Change only the modal's width to 300px, keeping other properties unchanged
reearth.modal.update({
  width: 300,
});

close

This method is used to close an open modal. Users can dismiss the modal based on task completion, logical conditions or other user actions. It does not require any parameters.

Syntax

reearth.modal.close: () => void

Parameters

None

Return Value:

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

Example

// Close the currently open modal
reearth.modal.close();

Events

close

The close event is triggered when the modal in reearth is closed. This event allows you to perform actions in response to the modal’s closure, such as cleaning up resources, saving data, or updating the UI. You can configure the listener to execute once or multiple times, based on the provided options.

Syntax

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

Example

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