Skip to main content

benecaster_admin_screens

Filter Free

Adds a screen of your add-on’s own to the Benecaster admin: an item in the left menu, after Benecaster’s own, and a route at #/{path} and every path under it. Benecaster draws nothing of the screen itself; its body is the SlotFill slot BenecasterAddonScreen_{id}, which your add-on fills with registerFill.

The fill receives { showId, path, navigate, setDirty }. path is what followed #/{path}/ (empty on the screen itself); navigate( 'sub/path' ) moves between your own sub-screens, because React Router isn’t shared with add-ons; setDirty( true ) makes every way out of the screen ask first, until you call setDirty( false ).

Parameters

Name Type Default Description
$screens array — Screen declarations, each with `id` (required; letters, numbers, `-` and `_`), `label` (required; translate it), and optionally `path` (one route segment; defaults to `id`), `icon`, `add_on` (your entitlement slug) and `sub_screens` (`[ 'tour-screen-id' => 'sub/path' ]`)

Returns: array

Example

add_filter( 'benecaster_admin_screens', function ( array $screens ): array {
    $screens[] = [
        'id'          => 'my-addon',
        'label'       => __( 'My Add-on', 'my-addon' ),
        'icon'        => 'puzzle',
        'add_on'      => 'benecaster-addon-my-addon',
        'sub_screens' => [ 'my-addon-settings' => 'settings' ],
    ];
    return $screens;
} );

Notes

add_on gates per show. The menu item appears while the add-on is switched on for at least one published show, and your fill runs only when the selected show is one of them; on any other show Benecaster says the add-on isn't switched on for it. Leave add_on out only for a free add-on — without it the screen shows on every show.

Worked out at page load, so switching an add-on on or off reaches the menu on the next load.

Claims are first come, first served. An id or path that is one of Benecaster's own screens (analytics, episodes, settings, dashboard, addons and the rest) is ignored, and so is a second claim on an id, path or sub-screen id another add-on already took.

icon is one of bar-chart, book-open, calendar, file-text, gift, mail, megaphone, message-square, mic, puzzle, settings, star or users; anything else draws a puzzle piece. The menu item carries data-tour="{id}-nav".

Tours can name the screen's id or any sub_screens id as a step's screen.

Problems are contained. A screen with no fill registered says the add-on did not load, and a fill that throws is caught and shown as a short message naming the add-on, with the rest of the admin intact.

Not for the Analytics screen, which is Benecaster's own; the Analytics Dashboard takes it over through the BenecasterAnalyticsScreen slot. Full walkthrough: Add a screen of your own to the Benecaster admin.

Affects

  • Benecaster admin menu

Related Recipes

Need this built rather than just documented? See our services →