Module contributions to the interface

← To the “Modules” section

An installed and enabled module can declaratively add a menu item, header action, dashboard widget, notification-bell entries and results to the control panel global search. All contributions belong to admin_extension to module.php:

'admin_extension' => array(
    'url' => '/notes',
    'icon' => 'ti ti-notes',
    'feature' => 'Личные заметки',
    'menu' => array(array(
        'code' => 'modules_example', 'label' => 'Пример', 'url' => '/example',
        'permission' => 'view_example', 'parent' => 'modules',
    )),
    'header' => array(/* действие в шапке */),
    'dashboard' => array(/* виджет главной */),
    'notifications' => array(/* строки колокольчика */),
    'search' => array(
        'provider' => array(GlobalSearchProvider::class, 'search'),
        'permission' => 'view_example',
        'priority' => 60,
        'limit' => 8,
    ),
),

Detailed Guides

Contribution	Guide
Dashboard	Widget development
Hat	Button, dropdown and modal action
Bell	Notification Provider
Left menu	Descriptor `module.php`
Global search	Section below

Global search results

The search($query, $limit) provider connects module entities to the Ctrl+K palette. It returns a list:

return array(array(
    'type' => 'example',
    'group' => 'Examples',
    'title' => 'Record #15',
    'subtitle' => 'Additional information',
    'url' => '/example/15/edit',
    'icon' => 'ti ti-box',
    'score' => 100,
));

title and a local url are required. Start the URL with / and omit the physical control-panel directory; AVE.cms adds it automatically. group collects related rows, subtitle distinguishes similar records, icon accepts a Tabler Icons class, and score raises exact matches inside one provider.

Search runs while a user types, so query an index or execute one bounded SQL query with a strict LIMIT. Permission is checked before the provider runs. A disabled or removed module contributes nothing. Failure of one module does not break the rest of the palette.

General description of the contribution

header, dashboard and notifications accept one description or list descriptions. General properties:

Key	Destination
`code`	Stable contribution code inside the module. Particularly important for widget order.
`provider`	Data provider: callable with no arguments, returning an array.
`data`	Static array instead of data provider.
`permission`	A right without which the contribution and provider are not fulfilled.
`visible`	An optional callable with no arguments for additional visibility.
`sort_order`	Initial order; the smaller value comes first.
`label`, `description`, `icon`	Presentation of contributions in interface settings.

The provider is called only after checking the right and visible. His exception is not breaks the control panel, but the contribution will receive empty data. Don't consider this how to handle errors: handle expected failures in provider and log without secrets.

Availability and management

An uninstalled or disabled module does not add UI contributions.
permission is checked for the current system user.
On the System → Modules page, the administrator can separately disable module action in the header and its widget.
In Basic Settings → Interface you can change the order and visibility dashboard elements.
Notifications are shown only if count is positive; separate general There is no placement switch for them.

Assets

The CSS/JS for the header and dashboard should be registered in the module descriptor: these elements appear outside the module's own route.

'assets' => array(
    'styles' => array(
        array('url' => ADMINX_BASE . '/modules/Notes/assets/notes.css', 'priority' => 46),
    ),
    'scripts' => array(
        array('url' => ADMINX_BASE . '/modules/Notes/assets/notes.js', 'priority' => 46),
    ),
),

Styles remain in assets/<module>.less, JavaScript - in the module file under space Adminx.<Module>. Common primitives (btn, dropdown, section-header, icon-tile, Adminx.Ajax, Adminx.Toast, Adminx.Confirm) reuse from UI kit without creating parallel components.

4.4 KiB Raw Blame History