Namespace: reearth.popup
The Modal type defines the structure and capabilities of modal dialog components within reearth. The Re-Earth plugin system supports the usage of popups through the reearth.popup.
Description: This method is used to display a popup within reearth and it offers a flexible way to present content in a small focused window. The method is designed for temporary messages, notifications or contents that capture a user’s attention without taking them away from the main interface. It accepts two parameters: The HTML content to be displayed, and the options object which contains optional settings to control the styling and placement of the popup.
Syntax: reearth.popup.show: (html, options) => void
Parameters:
// The HTML content to be displayed inside the popup
html: string,
options?: {
// Specifies the width of the popup. If a number is provided, it is interpreted as pixels. A string value can specify other CSS units (e.g., "200px", "50%").
width?: number | string;
// Specifies the height of the popup. Similar to width, a numeric value signifies pixels, while a string can represent other CSS units.
height?: number | string;
// Specifies the popup's position relative to a reference point or an element. It ensures the popup appears in an appropriate location.
position?: PopupPosition;
// Defines additional spacing or offset for the popup from its positioned location. This can be used to fine-tune the popup's placement, preventing overlap with other UI elements or bordering the edge of the viewport.
offset?: PopupOffset;
},
The PopupPosition function has the following options:
PopupPosition =
| "top"
| "top-start"
| "top-end"
| "right"
| "right-start"
| "right-end"
| "bottom"
| "bottom-start"
| "bottom-end"
| "left"
| "left-start"
| "left-end";
The popupOffset function has the following options:
// It can either be a single number, affecting the main axis, or it can be represented as an object specifying mainAxis, crossAxis, and alignmentAxis offsets
PopupOffset =
| number
| {
mainAxis?: number;
crossAxis?: number;
alignmentAxis?: number | null;
};
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Display a simple notification popup
reearth.popup.show('You have successfully updated your profile.', {
// Set the popup width to 300 pixels
width: 300,
// Set the popup height to 100 pixels
height: 100,
// Position the popup at the bottom-end of the reference element or viewport
position: 'bottom-end',
// Adjust the popup's position with specific offsets from the main and cross axis.
offset: { mainAxis: 10, crossAxis: 20 }
});
// Display a popup with an HTML content
reearth.popup.show('<h1>Welcome!</h1><p>Start your journey with us.</p>', {
// Set the popup width to 50% of the reference element or viewport width
width: '50%',
// Allow the popup height to automatically adjust based on the content
height: 'auto',
// Position the popup at the start (top) of the right side relative to the reference element or viewport
position: 'right-start',
// Adjust the popup's main axis position with a specific offset.
offset: 15
});
Description: This method facilitates the action of sending messages between the popup window and other components within reearth. It is designed to enable communication in scenarios where a popup needs to relay information back to the application, trigger actions in other components, or respond to user interactions within the popup content. The method accepts one parameter: message, which can be of any data type.
Syntax: reearth.popup.postMessage: (message: any) => void
Parameters:
// The message to be sent from the popup. The any type indicated that this parameter can accept data of various types.
(message: any)
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Sending a simple string message from the popup
reearth.popup.postMessage("Popup completed its task")
// Sending an object message from the popup
reearth.popup.postMessage({ message: "greeting" });
Description: This method allows for the modification of an existing popup’s properties on reearth. This functionality is important for adapting the popup’s appearance and positioning in response to changes in the application’s state or user interactions.
By offering options to update dimensions, position, and offset, this method ensures that popups can be reconfigured without having to close or recreate them, thereby enhancing the user experience with seamless transitions and updates. It accepts one parameter: options, which is an object containing properties to be updated for the popup. Each of these properties are optional.
Syntax: reearth.popup.update:(options) => void
Parameters:
options: {
// Defines the new width of the popup. Numeric values specify the width in pixels, while string values can indicate other CSS units (e.g., "100%", "400px").
width?: number | string;
// Sets the new height of the popup. Like width, it accepts numeric values for pixel measurements and string values for other units
height?: number | string;
// Determines the popup's new position relative to a reference point or an element. It ensures the popup appears in an appropriate location.
position?: PopupPosition;
// Adjusts the spacing or offset of the popup from its positioned location.
offset?: PopupOffset;
}
<aside>
💡 Kindly refer to the show method above for the options included in the PopupPosition and PopupOffset functions.
</aside>
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Update of the popup to adapt to new requirements or user interactions
reearth.popup.update({
width: "300px", // Setting a new fixed width
height: "150px", // Setting a new fixed height
position: "right-end", // Repositioning the popup to the end of the right side of the reference element or viewport
offset: {
mainAxis: 20, // Moving the popup 20 pixels away from the main axis
crossAxis: 5 // Shifting the popup 5 pixels away from the cross axis
}
});
// Adjusting the popup's offset to better accommodate new content or UI layout changes
reearth.popup.update({
offset: { mainAxis: 15, crossAxis: 10 } // Adjusting both main and cross axis offsets
// Width, height, and position are not updated; only the offset changes
});
Description: Provides a simple way to programmatically close an open popup. Users can dismiss the popup based on task completion, logical conditions or other user actions. It does not require any parameters.
Syntax: reearth.popup.close: () => void
Parameters: None
Return Value: None (void). The method performs its operation without returning a value.
Example Usage:
// Close the currently open popup
reearth.popup.close();
Questions