You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/core-concepts/plugin-system.mdx
+102
Original file line number
Diff line number
Diff line change
@@ -4,3 +4,105 @@ description: Plugin System
4
4
sidebar:
5
5
order: 3
6
6
---
7
+
8
+
Re:Earth Visualizer features a robust plugin system, enabling users to develop custom UI components and logics.
9
+
10
+
A plugin can include one or more `Extension`, which are collections of UI components and logic. Extensions come in three types:
11
+
12
+
-**Widget:** This type of extension can be placed in the main view of the Visualizer. Users can arrange its position using the Widget Align System.
13
+
14
+
-**InfoboxBlock:** This extension can be added to the infobox of a layer and is displayed when a feature of that layer is selected. It is typically used to enhance the presentation of additional information about the feature.
15
+
16
+
-**StoryBlock:** This extension can be added to a story page to enrich the content, such as by including custom charts or other visual elements to provide more detailed information about the story.
17
+
18
+
## How plugins work
19
+
20
+
It is never easy to make plug-ins work on a web browser, and there are various technical issues that need to be resolved before they can be developed. Therefore, plug-in developers need to accept the unique constraints that are different from the usual HTML and JavaScript implementations before developing plug-ins.
21
+
22
+
The plugin can be implemented in JavaScript, but it is divided into two parts: the part that works on WebAssembly and the part that works on iframe.
23
+
24
+
Both of them can safely execute third-party JavaScript code, but they have their advantages and disadvantages, so Re:Earth Visualizer uses a hybrid method.
25
+
26
+
WebAssembly can run code synchronously and fast, and can access Re:Earth Visualizer data, but it cannot use the APIs and UIs supported by web browsers. iframe can use all the APIs supported by web browsers, and can display UIs in HTML. But it cannot access Re:Earth Visualizer data directly and runs asynchronously.
27
+
28
+
The WebAssembly part and the iframe can exchange messages through [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). This allows you to send only the necessary data from Re:Earth Visualizer to the iframe, rewrite HTML in the iframe, and retrieve server information. You can also pass the retrieved information to the WebAssembly part.
29
+
30
+
### WebAssembly side
31
+
32
+
This is the entry point that is executed when the plugin is first loaded, and runs synchronously in the same thread as Re:Earth Visualizer.
33
+
34
+
#### Capabilities:
35
+
36
+
-**Execute JavaScript code:** JavaScript execution is powered by QuickJS, ensuring compatibility with `ECMAScript 2020`, independent of browser support.
37
+
-**Call Re:Earth Visualizer plugin API:**
38
+
- Access the current scene data.
39
+
- Partially modify the Re:Earth Visualizer scene.
40
+
- Subscribe to events.
41
+
- Facilitate data exchange between the plugin and the IFrame.
42
+
43
+
#### Limitations:
44
+
45
+
-**UI Rendering:** Directly rendering HTML or other UI elements is not supported and must be handled on the IFrame side.
46
+
-**Browser APIs:** Most browser-provided APIs are unavailable, except for a few, such as `console.log`.
47
+
-**External Communication:** HTTP communication with external servers is not permitted.
48
+
49
+
### IFrame side
50
+
51
+
#### Capabilities
52
+
53
+
-**HTML Rendering:** Render HTML as you would on a standard web page.
54
+
-**Browser APIs:** Utilize any API provided by web browsers, including window and DOM APIs.
55
+
-**External Server Communication:** Send HTTP requests via fetch or XHRRequest to external servers, provided the server's response includes a properly configured CORS header (Access-Control-Allow-Origin: \*).
56
+
-**Interprocess Communication:** Exchange messages with the WebAssembly side using `parent.postMessage` and `window.addEventListener("message", () => {})`.
57
+
58
+
#### Limitations
59
+
60
+
The following actions are restricted:
61
+
62
+
-**Restricted Server Communication:** Communication with external servers that do not include the Access-Control-Allow-Origin: \* header is prohibited due to the sandboxed nature of the iframe (its origin is set to null).
63
+
-**Direct Back-End Communication:** Direct interaction with the Re:Earth Visualizer back-end is not allowed.
64
+
-**Re:Earth Visualizer Data Access:** You cannot directly access or modify Re:Earth Visualizer data. This requires communication via postMessage with the WebAssembly side.
65
+
-**Local Storage:** Access to local storage is unavailable because the iframe is sandboxed with a null origin. (However, Re:Earth Plugin API provides a storage API to store data)
| Access to Re:Earth Visualizer plugin API | ✅ | ❌ |
75
+
| Render HTML | ❌ | ✅ |
76
+
| Use web API (DOM API, Canvas API, AJAX... without local storage) | ❌ | ✅ |
77
+
| Communicate with the other side via "postMessage" | ✅ | ✅ |
78
+
79
+
## Limitations
80
+
81
+
**postMessage Limitations:** Objects that cannot be serialized as JSON, such as ArrayBuffer and Blob, cannot be sent. To send binaries, encode them with base64 or similar methods. Expanding supported object types is under consideration for future updates.
82
+
83
+
**Plugin Size Restriction:** Installable plugins are limited to zip files of 10MB or less.
84
+
85
+
**Static Asset Handling:** Non-JavaScript files (e.g., images) cannot be packaged as plugins. Static assets like HTML, images, or CSS must either be embedded in JavaScript as strings or hosted on a publicly accessible server and referenced via URLs.
Make sure Docker is properly installed and running on your machine.
28
33
29
-
From your cloned directory, navigate to the server folder and set up the database:
34
+
<Steps>
35
+
36
+
1. From your cloned directory, navigate to the server folder and set up the database:
37
+
38
+
```bash
39
+
cd server
40
+
make run-db
41
+
```
42
+
43
+
2. Create and configure the `.env` file in the server directory to use mock authentication.
44
+
45
+
```bash
46
+
touch .env
47
+
echo"REEARTH_MOCKAUTH=true">> .env
48
+
```
49
+
50
+
3. Start the backend server.
51
+
52
+
```bash
53
+
make run-app
54
+
```
30
55
31
-
```bash
32
-
cd server
33
-
make run-db
34
-
```
56
+
4. Register a new mockuser.
35
57
36
-
Create and configure the `.env` file in the server directory to use mock authentication.
58
+
```bash
59
+
make mockuser
60
+
```
37
61
38
-
```bash
39
-
touch .env
40
-
echo"REEARTH_MOCKAUTH=true">> .env
41
-
```
62
+
:::note
63
+
Re:Earth Visualizer supports multiple authentication providers. For more information, refer to the [Authentication](/docs/core-concepts/authentication) documentation.
64
+
:::
42
65
43
-
Start the backend server.
66
+
</Steps>
44
67
45
-
```bash
46
-
make run-app
47
-
```
68
+
### Setup Web
48
69
49
-
Register a new mockuser.
70
+
<Steps>
50
71
51
-
```bash
52
-
make mockuser
53
-
```
72
+
1. Navigate to the web directory of your visualizer project and set up local .env file.
54
73
55
-
## Setup Web
74
+
```bash
75
+
cd web
76
+
touch .env
77
+
```
56
78
57
-
Navigate to the web directory of your visualizer project and set up local .env file.
79
+
2. Add the following environment variables to the `.env` file:
Add the following environment variables to the `.env` file:
89
+
:::note
90
+
Please follow <ahref="https://cesium.com/learn/ion/cesium-ion-access-tokens/"target="_blank">this document</a> to create your own Cesium Ion Access Token.
3. Install dependencies and start the frontend server.
72
94
73
-
:::note
74
-
Please follow <ahref="https://cesium.com/learn/ion/cesium-ion-access-tokens/"target="_blank">this document</a> to create your own Cesium Ion Access Token.
75
-
:::
95
+
```bash
96
+
yarn && yarn start
97
+
```
76
98
77
-
Install dependencies and start the frontend server.
99
+
</Steps>
78
100
79
-
```bash
80
-
yarn && yarn start
81
-
```
101
+
### Done!
82
102
83
-
You should now be able to access the Re:Earth Visualizer locally at `http://localhost:3000/`.
103
+
You should now be able to access the Re:Earth Visualizer locally at <ahref="http://localhost:3000"target="_blank">`http://localhost:3000`</a>.
The Re:Earth Visualizer Plugin API is a collection of APIs designed for plugin extensions to interact seamlessly with the Re:Earth Visualizer. It provides access to Visualizer data and offers methods to manage various components such as the layers, viewer, camera, timeline, ui, and extensions etc..
11
+
12
+
## Plugin API
13
+
14
+
Re:Earth Visualizer Plugin API is wrapped in `reearth` object, which is available globally in the plugin [WebAssembly side](/core-concepts/plugin-system/#webassembly-side). The API is divided into several modules, each of which provides a set of properties and methods to interact with the Visualizer.
15
+
16
+
### System related
17
+
18
+
**reearth.version: `string`:** The version of the Re:Earth Visualizer.
19
+
20
+
**reearth.apiVersion: `string`:** The version of the Re:Earth Visualizer Plugin API.
21
+
22
+
**reearth.engine: `string`:** Current in-use engine of the Re:Earth Visualizer.
0 commit comments