Topbar Actions

Plugins can register icon buttons in the sticky admin topbar by adding TopbarAction entries to the GlobalRegistry. Buttons appear on the right-hand side of the topbar, sorted by position (lower = leftmost).

Registration

Call GlobalRegistry.extend_globals('topbar_actions', items=[...]) inside your plugin's on_load_complete hook:

from fastpluggy.core.global_registry import GlobalRegistry
from fastpluggy.core.topbar import TopbarAction

class MyPlugin(FastPluggyBaseModule):
    def on_load_complete(self, fast_pluggy):
        GlobalRegistry.extend_globals('topbar_actions', items=[
            TopbarAction(
                id='my-plugin-topbar',
                icon='ti ti-star',
                tooltip='My Plugin',
                position=20,
                module_name=self.module_name,
                # … choose one interaction mode (see below)
            )
        ])

Interaction modes

Three mutually exclusive modes, evaluated in priority order:

Priority	Field	Behaviour
1	`modal_widgets`	Widget list pre-rendered server-side into a Bootstrap modal. Button uses `data-bs-toggle="modal"` — no JS required.
2	`js_onclick`	Arbitrary JS expression placed in `onclick="…"`.
3	`url`	Plain `<a>` navigation link.

modal_widgets is a list of widget entry dicts in the same format as inject_widgets:

{'widget': WidgetClass, 'kwargs': {…}}

At request time the framework calls ViewBuilder.build_widget_entries, which:

Instantiates each widget via call_with_injection (full DI support).
Respects is_visible() — invisible widgets are silently skipped.
Calls _process_widget (injects request, db, runs .process()).

Each action with modal_widgets gets its own pre-rendered modal in the page HTML:

<div class="modal modal-blur fade" id="fp-modal-{action.id}" …>

The button is rendered as:

<button class="fp-icon-btn" id="my-plugin-topbar" type="button"
        title="My Plugin"
        data-bs-toggle="modal" data-bs-target="#fp-modal-my-plugin-topbar">
    <i class="ti ti-star"></i>
</button>

Example — navigation menu modal:

from fastpluggy.core.widgets.categories.input.button_list import ButtonListWidget
from fastpluggy.core.widgets.categories.input.button import AutoLinkWidget

TopbarAction(
    id='my-plugin-topbar',
    icon='ti ti-star',
    tooltip='My Plugin',
    position=20,
    modal_widgets=[
        {
            'widget': ButtonListWidget,
            'kwargs': {
                'title': 'My Plugin',
                'buttons': [
                    AutoLinkWidget(route_name='my_index', label='Home'),
                    AutoLinkWidget(route_name='my_settings', label='Settings'),
                ],
            },
        },
    ],
    module_name='my_plugin',
)

Tip

debug_tools uses this pattern: its bug-icon button opens a DebugPanelWidget inside a modal. example_plugin uses a ButtonListWidget for quick navigation.

JS action

TopbarAction(
    id='my-action',
    icon='ti ti-player-play',
    tooltip='Run task',
    position=30,
    js_onclick='myRunTask()',
    module_name='my_plugin',
)

The JS function must be available on the page. Deliver it via extra_js_files:

class MyPlugin(FastPluggyBaseModule):
    extra_js_files: list = ['/plugin-pkg/my_plugin/static/js/actions.js']

Link action

TopbarAction(
    id='open-docs',
    icon='ti ti-book',
    tooltip='Documentation',
    position=80,
    url='/docs',
)

Renders as <a class="fp-icon-btn …" href="/docs"> — semantic and bookmarkable.

Field reference

Field	Type	Default	Description
`id`	`str`	required	Unique HTML `id` for the button/anchor element.
`icon`	`str`	required	CSS icon classes, e.g. `"ti ti-bug"` or `"fas fa-wrench"`.
`tooltip`	`str`	`""`	`title` attribute shown on hover.
`position`	`int`	`50`	Sort order — lower values appear further left.
`modal_widgets`	`list`	`[]`	Widget entry dicts — pre-rendered into a server-side modal. Takes priority over `js_onclick` and `url`.
`js_onclick`	`str \\| None`	`None`	JS expression placed verbatim in `onclick="…"`. Takes priority over `url`.
`url`	`str \\| None`	`None`	Navigation URL (renders as `<a>`).
`extra_classes`	`str`	`""`	Additional CSS classes on the button/anchor.
`module_name`	`str`	`""`	Your plugin's `module_name` — links the action to the plugin admin overview.

Admin overview

The module overview page (/base_module/{name}/overview) shows a Topbar Actions card when the plugin has registered at least one action. Each row displays the icon preview, id, tooltip, position, and the active mode (modal widget class names, JS expression, or URL).

Position conventions

Range	Intended use
1–19	Reserved for FastPluggy core
20–49	Primary plugin actions
50–79	Secondary / utility actions
80+	External links (docs, dashboards)