<aside> 💡 Context: Widget is associated with PluginExtensionInstance under the reearth.plugins namespace.

</aside>

Structure:

Widget<P = any> = {
  id: string;
  pluginId?: string;
  extensionId?: string;
  property?: P;
  propertyId?: string;
  extended?: {
    horizontally: boolean;
    vertically: boolean;
  };
  layout?: WidgetLayout;
  moveTo?: (options: WidgetLocationOptions) => void;
};

Methods:

id:

Description: This property serves as the unique identifier for the widget, distinguishing it within the ecosystem of plugin extensions. Each widget, whether it is a UI component, a tool, or any interactive element added to the Reearth platform via a plugin, is assigned a unique id. This identifier is essential for referencing, managing, and manipulating the widget programmatically, ensuring that actions, updates, and configurations are accurately applied to the correct widget instance.

The id facilitates interactions such as updating the widget's properties, controlling its visibility, or invoking its methods. It also plays a key role in maintaining the integrity and organization of the system by ensuring that each widget can be uniquely identified and operated upon within a potentially complex system of multiple plugins and extensions.

Type:

id: string;

//The id of a widget is a string that uniquely identifies it within the plugin's scope. 
//This ID is used extensively throughout the plugin framework to target and manage the widget, from updating its state or properties to handling events and interactions specific to that widget.
//The uniqueness of the id is paramount, as it prevents any ambiguity in widget management and operations, especially in environments where multiple widgets and extensions coexist.

pluginId:

Description: This is an optional string that identifies the specific plugin associated with the widget. This property links the widget to the plugin that provides or governs it, establishing a clear connection that enables the widget to utilize functionalities or resources offered by that plugin. The pluginId is fundamental in a plugin-based architecture as it ensures that the widget can interact with the correct plugin, especially in environments where multiple plugins may be active.

By associating a widget with a particular plugin via the pluginId, developers can manage dependencies and interactions more effectively, ensuring that each widget functions as intended within the broader ecosystem of the Reearth platform. This association is crucial for maintaining organized and modular development, allowing widgets to leverage specific capabilities provided by plugins while maintaining a clear separation of concerns.

Type:

pluginId?: string;

//The pluginId is an optional string that acts as the unique identifier for the plugin that either creates, controls, or enhances the widget. 
//If specified, it links the widget to its parent plugin, aligning it with the plugin’s lifecycle and making it part of the plugin’s overall functionality.
//If this property is not set, it suggests that the widget may operate independently or that its functionalities are sufficiently generic and do not require direct association with a specific plugin. 
//This setup provides flexibility in how widgets are used and managed within the Reearth platform, facilitating both tightly integrated and loosely coupled architectural approaches.

extensionId:

Description: This is an optional string that specifically identifies an extension within the plugin associated with the widget. This property is critical for linking the widget to a particular functionality or module provided by the plugin, allowing the widget to access and utilize specialized capabilities that enhance or modify its behavior within the Reearth platform.

The extensionId ensures that the widget is integrated with the correct extension, which can offer a range of functionalities such as additional data processing, unique visualization tools, or interactive controls that are not inherently part of the core plugin. By specifying an extensionId, developers ensure that the widget is precisely configured to leverage the intended features offered by the plugin’s extension, facilitating accurate and effective enhancement of the platform's capabilities.

Type:

extensionId?: string;

//The extensionId is an optional string that serves as the unique identifier for a specific extension within a plugin. 
//If provided, this ID confirms that the widget is associated with and dependent on that particular extension for its operations. 
//This identification is vital for the proper functioning and integration of the widget within the plugin's ecosystem. 
//If this property is not specified, it suggests that the widget either operates independently of any specific extensions or relies on the general functionalities provided by the plugin or the platform itself. 
//This flexibility allows widgets to be effectively used within various projects on the Reearth platform, accommodating both specific and general application needs.

property:

Description: This is an optional generic parameter (P) that stores custom properties specific to that widget. These properties define and influence the behavior, appearance, and functionality of the widget, allowing it to perform its designated tasks within the Reearth platform effectively.

The property field allows developers to customize widgets according to specific requirements or functionalities dictated by the associated plugin or extension. This could include settings such as configuration options, stylistic choices, data specific to the widget's operation, or interactive elements that enhance user engagement. The flexibility of the property parameter ensures that the widget can be tailored to diverse needs, making it a versatile component within the plugin architecture.

Type:

property?: P;
//The property is a generic type that can represent any structure of data, providing significant flexibility in customizing the widget’s behavior and capabilities within the plugin. 
//This might include configurations like display options, interaction rules, or data processing parameters tailored to the plugin's purpose. 
//The specific type P is defined based on what the widget needs to function optimally within the plugin’s ecosystem, ensuring that each widget can effectively use or enhance the plugin’s capabilities.

propertyId:

Description: This is an optional string that serves as a unique identifier linking the widget to a specific set of externally defined properties. This property identifier facilitates the dynamic application and integration of these properties into the widget, enabling it to inherit attributes, configurations, or behaviors defined by these external properties without embedding them directly within the widget's structure. The use of a propertyId is particularly important in modular and scalable plugin architectures where widgets might need to adapt or modify their functionality based on external configurations.

By referencing a propertyId, developers can ensure that the widget is correctly configured and behaves in accordance with a centralized set of properties, which can be managed and updated centrally. This approach not only promotes reusability and consistency across multiple widgets or instances but also simplifies maintenance and updates to widget properties across the platform.

Type:

propertyId?: string;

//The propertyId is an optional string that acts as the unique identifier for an external set of properties. 
//If specified, it ensures that the widget retrieves and uses a specific set of properties defined outside of its immediate structure, enhancing its functionality and adaptability. 
//If this property is not specified, it suggests that the widget either uses locally defined properties or defaults, or it does not require external property configurations for its operations.

extended:

Description: This is an object that specifies whether the widget can extend or stretch beyond its initial dimensions either horizontally, vertically, or both. This property provides control over the widget's resizing behavior, allowing it to adapt its size dynamically based on the content it displays or the space available in the user interface.

The extended object contains two boolean parameters:

• horizontally: This parameter determines whether the widget is allowed to stretch or expand its width beyond the preset dimensions to accommodate more content or to fill available horizontal space within its container.
• vertically: This parameter controls whether the widget can increase its height to display additional content or to match the vertical space offered by its container.

This flexibility is particularly useful in responsive design contexts where the widget needs to adapt to various screen sizes or layout changes, ensuring that it remains functional and visually appropriate across different viewing conditions.

Type:

extended?: {
  horizontally: boolean;
  vertically: boolean;
};

horizontally: //Indicates if the widget can expand horizontally.
vertically: //Indicates if the widget can expand vertically.

//If this property is specified, it allows the widget to dynamically adjust its size according to the layout requirements and user interactions, enhancing usability and visual coherence in diverse application scenarios. 
//If not specified, the widget typically adheres to its default size settings, maintaining fixed dimensions regardless of the surrounding space or content needs. 
//This property thus plays a crucial role in making widgets versatile and adaptable components within the Reearth platform.

layout:

Description: This is an optional attribute that defines the spatial arrangement and alignment of the widget within the user interface of the Reearth platform. This property ensures that the widget is positioned and aligned correctly according to the design and functional requirements of the application.

The layout property encapsulates:

• location: Specifies where the widget should be placed within the designated zone and section of the interface.
• align: Determines the alignment of the widget within its assigned location, controlling how it is positioned relative to other elements or the boundaries of its container.

Structure:

layout?: WidgetLayout;

WidgetLayout = {
  location: WidgetLocation;
  align: WidgetAlignment;
}

location: WidgetLocation //Defines the precise positioning of the widget within the interface.
	WidgetLocation = { //Defines the precise positioning of the widget within the interface.
		zone: "inner" | "outer" // Indicates whether the widget is placed inside (inner) or outside (outer) the main content area. The inner zone typically refers to areas within the main content boundaries, while outer could refer to more peripheral areas of the UI.
		section: "left" | "center" | "right"  //Specifies the horizontal section of the zone where the widget should be located. These options allow the widget to be aligned to the left, centered, or right within the chosen zone.
		area: "top" | "middle" | "bottom" //Determines the vertical area within the section where the widget will appear, providing options for top, middle, or bottom placement.
}

align: WidgetAlignment  //Controls how the widget is aligned within its designated location.
WidgetAlignment: "start" | "centered" | "end" //These options specify the widget's alignment relative to its container or specified area. "start" typically means aligned towards the beginning of the container (top or left), "centered" means it is centered within the space, and "end" indicates alignment towards the end (bottom or right).

moveto:

Description: This is an optional method that provides the functionality to programmatically change the position of the widget within the user interface. This method accepts a parameter of type WidgetLocationOptions, which specifies the new location for the widget along with an optional method for how the widget should be integrated into its new position. This capability is crucial for dynamic user interface management, allowing developers to adapt the layout of widgets in response to user interactions or changes in the application state.

Structure:

moveTo?: (options: WidgetLocationOptions) => void;

WidgetLocationOptions = WidgetLocation & {
  method?: "insert" | "append";
};

WidgetLocation = { //Specifies the target location where the widget should be moved. It includes:
  zone: "inner" | "outer"; //Determines whether the widget is placed within the inner (main content area) or outer (peripheral areas) of the layout.
  section: "left" | "center" | "right"; //Defines the horizontal section within the selected zone.
  area: "top" | "middle" | "bottom" //Specifies the vertical placement within the section.
};

method?: "insert" | "append" //An optional method that defines how the widget should be positioned within its new location:
"insert" //The widget is inserted at the specified position, potentially displacing other elements.
"append" //The widget is added to the end of the specified area, following any existing elements.

Example Usage:

// Suppose we have an array of PluginExtensionInstance objects, including widget extensions
const pluginInstances = [
    {
        id: "pluginInstance1",
        pluginId: "plugin1",
        name: "Interactive Dashboard",
        extensionId: "widget1",
        extensionType: "widget",
        runTimes: undefined
    }
];

// A hypothetical function to update a widget's properties or move it based on certain conditions
function updateWidgetProperties(widgetId) {
    // Find the widget by ID from the plugin instances
    const widgetInstance = pluginInstances.find(instance => 
        instance.extensionType === "widget" && instance.id === widgetId);

    // Assume we have access to functions that update widget properties or move it
    if (widgetInstance) {
        // For demonstration, let's assume you can update the widget's property
        console.log(`Updating properties for widget ID: ${widgetInstance.id}`);
        // This might involve API calls or local state updates, for example:
        // reearth.api.updateWidgetProperty(widgetInstance.id, { newProperty: 'newValue' });

        // Additionally, let's assume you can move the widget to a new location
        console.log(`Moving widget ID: ${widgetInstance.id} to a new location`);
        // Placeholder for the move action:
        widget.moveTo({ zone: 'outer', section: 'right', area: 'top' });

        console.log("Properties updated and widget moved for:", widgetInstance.id);
    } else {
        console.log("Widget not found with ID:", widgetId);
    }
}

// Function call to update properties of a specific widget
updateWidgetProperties("pluginInstance1");

Example Without Comments

(plugin?.extensionType === "widget"
                  ? widget?.()?.id
                  : plugin?.extensionType === "block"
                  ? block?.()?.id
                  : "") ?? "",
                  
 --------------------------------------------------------
 
  if (area?.widgets) {
      area?.widgets.forEach(widget => {
      instances.push({
      id: widget.id,
      pluginId: widget.pluginId ?? "",
      name: getExtensionInstanceName(widget.pluginId ?? ""),
      extensionId: widget.extensionId ?? "",
      extensionType: "widget",
      get runTimes() {
      return runTimesCacheHandler.get(widget.id);
           },
          });
        });
       }