reearth.extension

The reearth.extension namespace provides access to the functionalities and properties of an active plugin extension. It includes methods for communication between different components, such as widgets, blocks, or other extension instances within the reearth environment.

Properties

block

The block property provides access to a plugin’s story block or infobox block. A block can include metadata, plugin details, properties, and, in the case of an infobox block, an associated layer. This property is useful for interacting with content blocks in the reearth environment.

Caution

This is available only when executed in a extension in type of storyBlock or infoboxBlock.

Syntax

reearth.extension.block?: PluginStoryBlock | (PluginInfoboxBlock & { layer?: Layer });

Return Value

Type PluginStoryBlock | (PluginInfoboxBlock & { layer?: Layer });

A plugin block object that includes metadata, plugin details, properties, and, in the case of an infobox block, an associated layer.

PluginStoryBlock: Represents a story block, which is a content block specifically designed for creating narratives or sequences within the plugin.

Note

For more information on the options included in PluginStoryBlock, please refer to PluginStoryBlock section.

PluginInfoboxBlock: Represents an infobox block, which may include an associated layer.

Note

For more information on the options included in PluginInfoboxBlock, please refer to PluginInfoboxBlock section.

layer?: Layer: Represents a layer associated with the infobox block, including metadata, data source details, and display settings.

Note

For more information on the options included in Layer, please refer to Layer section.

Example

// Example 1: Get the details of a story block
const block = reearth.extension.block;

if (block && block.extensionType === "storyBlock") {
  console.log("Story Block ID:", block.id);
  console.log("Plugin ID:", block.pluginId);
  console.log("Block Name:", block.name);
}

// Example 2: Access a layer associated with an infobox block
const block = reearth.extension.block;

if (block && block.extensionType === "infoboxBlock" && block.layer) {
  const layer = block.layer;
  console.log(`Layer ID: ${layer.id}`);
  console.log(`Layer Title: ${layer.title}`);
  console.log(`Layer Type: ${layer.type}`);
}

widget

The widget property provides access to information about a plugin’s widget, including its ID, layout, and display settings. Widgets are UI components that can be positioned and styled dynamically within the reearth environment.

Caution

This is available only when executed in a extension in type of widget.

Syntax

reearth.extension.widget?: Widget;

Return Value

Type Widget

Note

For more information about Widget, please refer to Widget section.

Example

// Check and log widget details
const widget = reearth.extension.widget;

if (widget) {
  console.log("Widget ID:", widget.id);
  console.log("Plugin ID:", widget.pluginId);
  console.log("Extension ID:", widget.extensionId);
  console.log("Property ID:", widget.propertyId);
  console.log("Extended Horizontally:", widget.extended?.horizontally);
  console.log("Extended Vertically:", widget.extended?.vertically);
}

list

This property provides access to an array of all plugin extension instances, including widgets, blocks, and other supported types. Each instance contains metadata about its plugin and extension, along with usage statistics.

Syntax

reearth.extension.list: PluginExtensionInstance[];

Return Value

Type PluginExtensionInstance[];

Each entry in the list array represents an instance of a plugin extension.

Note

For more information on the options included in PluginExtensionInstance, please refer to PluginExtensionInstance section.

Example

// Example 1: Log all extension instances and their metadata
const extensionInstances = reearth.extension.list;

extensionInstances.forEach((instance) => {
  console.log("Extension Instance ID:", instance.id);
  console.log("Plugin ID:", instance.pluginId);
  console.log("Name:", instance.name);
  console.log("Extension ID:", instance.extensionId);
  console.log("Type:", instance.extensionType);
  console.log("Run Times:", instance.runTimes ?? "Not Available");
});

// Example 2: Filter and log only widget extensions
const widgets = reearth.extension.list.filter(
  (instance) => instance.extensionType === "widget"
);

console.log("Widget Extensions:");
widgets.forEach((widget) => {
  console.log(`- ${widget.name} (ID: ${widget.id})`);
});

Methods

postMessage

This method allows the plugin extension to send a message to a specific widget, block, or other extension instance by specifying its unique ID. This functionality is useful for enabling inter-component communication within the plugin.

Syntax

reearth.extension.postMessage(id: string, message: any) => void;

Parameters

id

Type: string

The extension ID of the target instance to which the message will be sent.

message

Type: any

The message to be sent.

Return Value:

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

Example

// Send a message to a widget with name "my-widget-name"
const extensionInstances = reearth.extension.list;

const targetWidgetId = extensionInstances.find(
  (extension) => extension.name === "my-widget-name"
)?.id;

if (targetWidgetId) {
  reearth.extension.postMessage(targetWidgetId, {
    action: "update",
    data: { key: "value" },
  });
}

Events

message

The message event triggers whenever a generic message is sent to the extension. This event is used to listen for messages from current extension’s UI (or modal, or popup).

Syntax

reearth.extension.on("message", (message: unknown)  => void): void;

Example

reearth.extension.on("message", (message) => {
  console.log("Received message:", message);
});

extensionMessage

The extensionMessage event triggers when a message is sent specifically from another extension instance. It provides additional context, including the data payload and the sender’s ID.

Syntax

reearth.extension.on("extensionMessage", (props: ExtensionMessage)  => void): void;

Example

reearth.extension.on("extensionMessage", (props) => {
  console.log("Message from:", props.sender);
  console.log("Message data:", props.data);
});

References

PluginStoryBlock

type PluginStoryBlock = Omit<
  StoryBlock,
  "propertyForPluginAPI" | "propertyItemsForPluginBlock"
>;

type StoryBlock = {
  id: string;
  name?: string | null;
  pluginId: string;
  extensionId: string;
  extensionType?: "storyBlock";
  propertyId?: string;
  property?: any;
  propertyForPluginAPI?: any;
  propertyItemsForPluginBlock?: Item[];
};

id: string;: A unique identifier for the story block. This is essential for distinguishing one block from another, especially when working with multiple blocks.

name?: string | null;: The name of the story block. This is optional and can be null if not provided.

pluginId: string;: The unique ID of the plugin to which the story block belongs. This helps associate the block with its parent plugin.

extensionId: string;: The unique ID of the plugin extension that created this block. Useful for tracing the source of the block within the plugin.

extensionType?: "storyBlock";: Specifies the type of extension as “storyBlock”. This property helps differentiate it from other block types, like infoboxBlock.

propertyId?: string;: An optional property ID that links to the block’s configuration or metadata stored elsewhere.

property?: any;: Custom properties associated with the block.

PluginInfoboxBlock

type PluginInfoboxBlock = Omit<
  InfoboxBlock,
  "propertyForPluginAPI" | "propertyItemsForPluginBlock"
>;

type InfoboxBlock<P = any> = {
  id: string;
  name?: string;
  pluginId?: string;
  extensionId?: string;
  extensionType?: "infoboxBlock";
  propertyId?: string;
  property?: P;
  propertyForPluginAPI?: any;
  propertyItemsForPluginBlock?: Item[];
};

id: string;: A unique identifier for the infobox block. This ensures each block is easily identifiable.

name?: string;: An optional name for the infobox block. This might represent a label or title for the infobox.

pluginId?: string;: The unique ID of the plugin to which this infobox block belongs. This is optional and may not always be present.

extensionId: string;: The unique ID of the plugin extension that created this infobox block. This helps identify its origin.

extensionType?: "infoboxBlock";: Specifies the type of extension as “infoboxBlock”. This property is crucial for determining the type of block being handled.

propertyId?: string;: An optional property ID linked to the block’s configuration or metadata. Similar to PluginStoryBlock, this allows dynamic property management.

property?: P;: The property field represents custom properties associated with the block. Its type is determined by the generic parameter P, allowing it to adapt dynamically to the plugin’s specific needs.

Layer

type Layer = {
  id: string; // A unique identifier for the layer.
  title?: string;
  visible?: boolean; // Flag indicating whether the layer is visible by default. Default is true
  infobox?: Infobox<IBP>; // An infobox that can display additional interactive or informational content
  type: "simple";
  data?: {
    type:
      | "geojson"
      | "3dtiles"
      | "osm-buildings"
      | "google-photorealistic"
      | "czml"
      | "csv"
      | "wms"
      | "mvt"
      | "kml"
      | "gpx"
      | "shapefile"
      | "gtfs"
      | "gml"
      | "georss"
      | "gltf"
      | "tiles"
      | "tms"
      | "heatMap";
    url?: string; // URL of data source
    value?: any;
    layers?: string | string[];
    jsonProperties?: string[];
    isSketchLayer?: boolean;
    updateInterval?: number; // milliseconds
    parameters?: Record<string, any>;
    idProperty?: string;
    time?: {
      property?: string;
      interval?: number; // milliseconds
      updateClockOnLoad?: boolean;
    };
    csv?: {
      idColumn?: string | number;
      latColumn?: string | number;
      lngColumn?: string | number;
      heightColumn?: string | number;
      noHeader?: boolean;
      disableTypeConversion?: boolean;
    };
    geojson?: {
      useAsResource?: boolean;
    };
  };
  properties?: any;
  defines?: Record<string, string>;
  events?: Events;
  layerStyleId?: string;
  marker?: MarkerAppearance;
  polyline?: PolylineAppearance;
  polygon?: PolygonAppearance;
  model?: ModelAppearance;
  "3dtiles"?: Cesium3DTilesAppearance;
};

Widget

type Widget = {
  readonly id: string;
  readonly pluginId?: string;
  readonly extensionId?: string;
  readonly property?: unknown;
  readonly propertyId?: string;
  readonly extended?: {
    horizontally: boolean;
    vertically: boolean;
  };
  readonly layout?: WidgetLayout;
};

id: string;: A unique identifier for the widget.

pluginId?: string;: (Optional) The ID of the plugin that owns this widget. Useful for identifying which plugin the widget belongs to.

extensionId?: string;: (Optional) The ID of the plugin extension that created the widget. This can help distinguish widgets created by different extensions of the same plugin.

property?: unknown;: (Optional) Custom properties associated with the widget. The exact structure of these properties depends on the specific plugin’s implementation.

propertyId?: string;: (Optional) The unique identifier for the widget’s configuration or metadata. It allows linking to external settings or stored properties.

extended?: { horizontally: boolean; vertically: boolean };: (Optional) Indicates whether the widget is extended in specific directions. This property is useful for determining the widget’s layout and behavior.

• horizontally: boolean: true if the widget is extended horizontally, otherwise false.
• vertically: boolean: true if the widget is extended vertically, otherwise false.

This property is optional and may not always be present. If omitted, the widget is not extended in either direction.

layout?: WidgetLayout;: (Optional) Specifies the widget’s position and alignment within the Reearth UI. See the definition of WidgetLayout below.

WidgetLayout

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

The WidgetLayout type defines how a widget is positioned within the Reearth interface.

location: WidgetLocation;: Specifies the exact location of the widget within the interface. See WidgetLocation for more details.

align?: WidgetAlignment;: (Optional) Determines how the widget is aligned within its area. Defaults to no alignment if not provided. See WidgetAlignment for details.

WidgetLocation

type WidgetLocation = {
  zone: "inner" | "outer";
  section: "left" | "center" | "right";
  area: "top" | "middle" | "bottom";
};

The WidgetLocation type defines the hierarchical position of the widget in the reearth interface. It describes where the widget is placed relative to the user interface zones.

zone: "inner" | "outer";: Specifies the UI zone where the widget is located:

• "inner": Indicates the widget is inside the main content area.
• "outer": Indicates the widget is in the peripheral UI (e.g., sidebars, headers).

section: "left" | "center" | "right";: Describes the section within the zone:

• "left": The left section.
• "center": The central section.
• "right": The right section.

area: "top" | "middle" | "bottom";: Defines the vertical area within the section:

• "top": The top of the section.
• "middle": The middle of the section.
• "bottom": The bottom of the section.

WidgetAlignment

type WidgetAlignment = "start" | "centered" | "end";

The WidgetAlignment type specifies how a widget is aligned within its area.

"start";: Aligns the widget to the start of its area (e.g., top-left corner).

"centered";: Centers the widget within its area.

"end";: Aligns the widget to the end of its area (e.g., bottom-right corner).

PluginExtensionInstance

type PluginExtensionInstance = {
  readonly id: string;
  readonly pluginId: string;
  readonly name: string;
  readonly extensionId: string;
  readonly extensionType: "widget" | "block" | "infoboxBlock" | "storyBlock";
};

id: string;: A unique identifier for the extension instance. This ID is used to reference the instance within the reearth environment.

pluginId: string;: The unique ID of the plugin to which the extension instance belongs. This links the instance to its parent plugin.

name: string;: The name of the extension instance. This is typically a human-readable name to identify the instance.

extensionId: string;: The unique ID of the plugin extension that created the instance. This helps distinguish between extensions within the same plugin.

extensionType: "widget" | "block" | "infoboxBlock" | "storyBlock";: The type of extension represented by the instance. Possible values include:

• "widget": A widget extension.
• "infoboxBlock": An infobox block extension.
• "storyBlock": A story block extension.