ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

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/except to 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_content and iframe_url must be provided; otherwise the page will be blank.


Two Injection Modes

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 token parameter is automatically appended to the URL for authentication.


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

  1. 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
  2. Defensive Programming — Wrap view registration in try/except, since the Dashboard module may not be installed or loaded
  3. Resource Cleanup — Call unregister_view() in on_unload to remove registered views
  4. ID Uniqueness — The id parameter must be unique across the entire Dashboard; using the module name directly is recommended
  5. SVG Icons — icon_svg should be a complete <svg> tag, with a recommended size of viewBox="0 0 24 24"; use stroke="currentColor" to inherit the Dashboard theme color
  6. JS Function Naming — Function names in js_content should be unique (e.g., loadWeatherView) to avoid conflicts with other modules
  7. 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