ErisPulse-Dashboard
Tip
When to read this: Read this when you want to manage your bot through a web-based visual interface (start/stop modules, edit configurations, view logs, monitor event streams), or when you want to register a Dashboard management page for your own module. Skip it if you don't need these.
ErisPulse-Dashboard is a Web management panel module maintained directly by ErisDev, providing ErisPulse with a visual runtime management interface: module start/stop, configuration editing, log viewing, event stream monitoring, and more.
Important
Dashboard is not a built-in feature of the ErisPulse framework and requires separate installation:
epsdk install Dashboard
Dashboard also supports other ErisPulse modules registering custom management pages to the sidebar. Once registered, users can switch directly to the module's dedicated view page within the Dashboard, without needing to develop a standalone frontend interface.
Note
View registration is an optional feature.
- If the Dashboard module is not installed or not loaded, calling
sdk.Dashboard.register_view()will raise an exception - Be sure to wrap the registration code in
try/exceptto ensure that other functionality of the module itself is not affected - It is recommended to check whether Dashboard is available before registering:
hasattr(sdk, 'Dashboard') and sdk.Dashboard
How It Works
Module on_load()
→ Calls sdk.Dashboard.register_view(...)
→ Dashboard backend stores view information
→ WebSocket notifies the frontend
→ Frontend dynamically creates sidebar navigation item + page container
→ User clicks to view the module view
Registration API
sdk.Dashboard.register_view(
id="MyModule", # Required, unique identifier
title="My Module", # Chinese name
title_en="My Module", # English name
icon_svg='<svg>...</svg>', # Sidebar icon SVG
html_content='<div>...</div>', # Page HTML content
js_content='function xxx() {}', # Page JavaScript logic
css_content='.my-style {}', # Optional custom CSS
iframe_url='', # iframe mode URL (choose either this or html_content)
loader="loadMyModuleView", # JS function name called when switching to this page
group="group_extensions", # Sidebar group
group_title="", # Custom group name in Chinese
group_title_en="", # Custom group name in English
)
Parameter Descriptions
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
str |
Yes | Unique identifier of the view; module name recommended |
title |
str |
No | Chinese display name, defaults to id |
title_en |
str |
No | English display name, defaults to title |
icon_svg |
str |
No | Complete SVG string for the sidebar icon |
html_content |
str |
No* | Page HTML content in injection mode |
js_content |
str |
No | Page JavaScript code |
css_content |
str |
No | Page custom CSS styles |
iframe_url |
str |
No* | URL in iframe mode; html_content is ignored when set |
loader |
str |
No | JS function name automatically called when the page is activated |
group |
str |
No | Sidebar group identifier, defaults to group_extensions |
group_title |
str |
No | Chinese title of the custom group |
group_title_en |
str |
No | English title of the custom group |
*At least one of
html_contentandiframe_urlmust be provided; otherwise the page will be blank.
Two Injection Modes
Mode 1: HTML/JS Injection (Recommended)
Provide HTML, JS, and CSS strings directly, and Dashboard will inject the content into the page. This mode is fully consistent with the Dashboard's styling; it is recommended to use the CSS class names provided by Dashboard.
sdk.Dashboard.register_view(
id="HelloPage",
title="Hello Page", title_en="Hello",
icon_svg='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/></svg>',
html_content='<h1 class="page-title">Hello World</h1><div class="card"><div class="card-body">This is a sample page</div></div>',
group="group_tools",
)
For a complete weather module example (including API routes, JS interactions, etc.), see Complete Module Example below.
Mode 2: iframe Embedding
The module provides its own HTML page URL (routes must be registered by the module itself), and Dashboard embeds it via an iframe. Suitable for scenarios that require a completely independent UI or complex interactions.
sdk.Dashboard.register_view(
id="MyVisualizer",
title="Data Visualization", title_en="Data Visualizer",
iframe_url="/MyVisualizer/view",
group="group_tools",
)
In iframe mode, a
tokenparameter is automatically appended to the URL for authentication.
Sidebar Groups
Modules can specify the sidebar group in which the view is placed. Dashboard includes the following built-in groups:
| Group Identifier | Chinese Name | Position |
|---|---|---|
group_overview |
Overview | Group 1 |
group_events |
Events | Group 2 |
group_extensions |
Extensions | Group 3 (Default) |
group_system |
System | Group 4 |
group_tools |
Tools | Group 5 |
Specifying a built-in group name will append the module view to the end of that group:
group="group_tools" # Appended to the "Tools" group
You can also use a custom group name (not starting with group_), and Dashboard will automatically create a new group:
group="my_group",
group_title="My Group",
group_title_en="My Group",
Common CSS Class Names
When the module view uses HTML injection mode, you can directly use Dashboard's existing CSS class names to maintain visual consistency:
| Class Name | Purpose |
|---|---|
page-title |
Page title, e.g., <h1 class="page-title">Title</h1> |
card |
Card container |
card-header |
Card header bar |
card-body |
Card content area |
grid-2 |
Two-column grid layout |
grid-3 |
Three-column grid layout |
btn |
Basic button |
btn-primary |
Primary button (blue) |
btn-secondary |
Secondary button |
btn-icon |
Icon button |
btn-danger |
Danger action button |
Dashboard uses CSS variables to control theme colors, which you can reference directly in your module view:
| CSS Variable | Purpose |
|---|---|
var(--bg-p) |
Primary background color |
var(--bg-s) |
Secondary background color |
var(--bg-t) |
Tertiary background color (cards, etc.) |
var(--tx-p) |
Primary text color |
var(--tx-s) |
Secondary text color |
var(--tx-t) |
Auxiliary text color |
var(--bd) |
Border color |
var(--accent) |
Accent color |
var(--ok-c) |
Success color |
var(--er-c) |
Error color |
These variables switch automatically according to Dashboard's light/dark theme, so modules do not require additional handling.
Authentication and API Calls
When calling your module's own API from the JS in a module view, you need to carry the Dashboard Token for authentication:
var token = localStorage.getItem('__ep_tk__');
var resp = await fetch('/YourModule/api/data', {
headers: { 'Authorization': 'Bearer ' + token }
});
var data = await resp.json();
The module's API endpoint can decide on its own whether to verify the Token. If verification is needed, it can be extracted from the request headers:
async def _api_data(self, request):
token = request.headers.get("Authorization", "").replace("Bearer ", "")
if not token:
return {"error": "Unauthorized"}, 401
return {"data": "hello"}
Complete Module Example
Below is a complete weather module example demonstrating how to register a view, provide API data, and clean up resources on unload:
from ErisPulse import sdk
from ErisPulse.Core.Bases import BaseModule
from ErisPulse.Core.Event import command
class Main(BaseModule):
def __init__(self):
self.sdk = sdk
self.logger = sdk.logger.get_child("Weather")
self.config = self._load_config()
@staticmethod
def get_load_strategy():
from ErisPulse.loaders import ModuleLoadStrategy
return ModuleLoadStrategy(lazy_load=False, priority=50)
async def on_load(self, event):
self._register_routes()
self._register_dashboard_view()
self.logger.info("Weather module loaded")
async def on_unload(self, event):
self._unregister_routes()
if hasattr(self.sdk, 'Dashboard') and self.sdk.Dashboard:
self.sdk.Dashboard.unregister_view("Weather")
self.logger.info("Weather module unloaded")
def _load_config(self):
config = self.sdk.config.getConfig("Weather")
if not config:
default = {"city": "Beijing", "api_key": ""}
self.sdk.config.setConfig("Weather", default)
return default
return config
def _register_routes(self):
r = self.sdk.router
r.register_http_route("Weather", "/api/current",
handler=self._api_current, methods=["GET"])
def _unregister_routes(self):
r = self.sdk.router
try:
r.unregister_http_route("Weather", "/api/current")
except Exception:
pass
async def _api_current(self, request):
return {
"city": self.config.get("city", "Beijing"),
"temp": 25,
"humidity": 60,
}
def _register_dashboard_view(self):
try:
dashboard = self.sdk.Dashboard
dashboard.register_view(
id="Weather",
title="Weather", title_en="Weather",
icon_svg='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>',
html_content='''
<h1 class="page-title">Weather Query</h1>
<p style="color:var(--tx-s);margin-bottom:16px">View current weather information</p>
<div class="grid-2">
<div class="card">
<div class="card-header">Current Weather</div>
<div class="card-body">
<div id="weather-info" style="font-size:14px;color:var(--tx-s)">Click refresh to load</div>
</div>
</div>
<div class="card">
<div class="card-header">Actions</div>
<div class="card-body">
<button class="btn btn-primary" onclick="refreshWeather()">Refresh</button>
</div>
</div>
</div>
''',
js_content='''
async function loadWeatherView() { await refreshWeather(); }
async function refreshWeather() {
var el = document.getElementById('weather-info');
if (!el) return;
el.textContent = 'Loading...';
try {
var resp = await fetch('/Weather/api/current', {
headers: { 'Authorization': 'Bearer ' + localStorage.getItem('__ep_tk__') }
});
var data = await resp.json();
el.innerHTML = '<p>City: ' + (data.city || '--') + '</p>' +
'<p>Temperature: ' + (data.temp || '--') + '°C</p>' +
'<p>Humidity: ' + (data.humidity || '--') + '%</p>';
} catch (e) {
el.textContent = 'Load failed: ' + e.message;
}
}
''',
loader="loadWeatherView",
group="group_tools",
)
except Exception as e:
self.logger.warning(f"Failed to register Dashboard view: {e}")
Unregistering a View
When a module is unloaded, it should call unregister_view() to clean up registered views:
async def on_unload(self, event):
if hasattr(self.sdk, 'Dashboard') and self.sdk.Dashboard:
self.sdk.Dashboard.unregister_view("Weather")
After unregistration, the Dashboard frontend will remove the sidebar navigation item and page content in real time via WebSocket, with no user refresh required.
Notes
- Loading Order — Dashboard's load priority is
99999(high priority); your module's priority should be lower than this value (e.g.,50) to ensure Dashboard is fully loaded first - Defensive Programming — Wrap view registration in
try/except, since the Dashboard module may not be installed or loaded - Resource Cleanup — Call
unregister_view()inon_unloadto remove registered views - ID Uniqueness — The
idparameter must be unique across the entire Dashboard; using the module name directly is recommended - SVG Icons —
icon_svgshould be a complete<svg>tag, with a recommended size ofviewBox="0 0 24 24"; usestroke="currentColor"to inherit the Dashboard theme color - JS Function Naming — Function names in
js_contentshould be unique (e.g.,loadWeatherView) to avoid conflicts with other modules - Dynamic Updates — After a module registers/unregisters a view, the Dashboard frontend updates the sidebar in real time via WebSocket, with no page refresh needed
Next Steps
- Manage your bot from your phone without turning on your computer: ErisPulse-App (official multi-platform client, shares the same API set with Dashboard; module views work there as well)
- Provide backend data APIs for views: register HTTP routes with the Router Manager; see Core Modules API - Router for a quick method reference
- View real-time logs / event streams in views: Log Subscription (Push Mode) and Lifecycle Management