Skip to main content

benecaster_show_settings_pages

Filter Free

Adds a tab to one show’s settings navigation, below Templates. Use it for anything whose data belongs to a single show: a per-show API key, a per-show import, per-show mappings. The tab is deep-linkable at #/shows/{id}/settings/{page-id}.

A declared tab is a nav entry and an empty slot. Benecaster renders no fields for it: fill the tab’s BenecasterShowSettingsPage_{id} slot with a React component to give it content. The fill receives { showId }.

The filter takes two arguments. Register it with 10, 2. A callback that declares $show_id without the 2 raises an ArgumentCountError, and one that declares only $pages never sees the show.

The add_on key is the per-show visibility gate. Purchase is license-wide but activation is per show, so a Multi-Show customer can own your add-on and switch it off for one show. Name your entitlement slug in add_on and Benecaster hides the tab on every show where the add-on is not active. Omit the key and the tab appears on every show, which is right for a free add-on and wrong for a paid one. The check runs on the server; the fill does not need to repeat it.

Your callback must also handle $show_id of 0. GET /admin/extensions is fetched without a show by every screen other than a show’s settings, and in that form the list comes back unfiltered. Returning the page unconditionally is the right default: the declaration says the page exists, and add_on says on which shows.

For an install-wide page with no show in scope, use benecaster_settings_pages. As there, an icon key is accepted but not rendered; every add-on tab gets the same puzzle-piece icon.

The tab button carries data-tour="{id}-nav", so an add-on tour can point at it. Benecaster adds it to every add-on tab; there is no key to set. Benecaster’s own tabs do not carry it.

Parameters

Name Type Default Description
$pages array — Array of page declaration arrays, each with keys: id (slot suffix and URL segment), label, and optionally add_on
$show_id int — The show whose settings are being built, or 0 when the payload is fetched without a show

Returns: array

Example

add_filter( 'benecaster_show_settings_pages', function ( array $pages, int $show_id ): array {
    $pages[] = [
        'id'     => 'my-addon',
        'label'  => __( 'My Add-on', 'my-addon' ),
        'add_on' => 'my-addon',
    ];
    return $pages;
}, 10, 2 );

Notes

The id value is the SlotFill slot suffix, the URL segment and the tab's tour anchor, so renaming it changes all three. Without a fill the tab opens empty.

Affects

  • Show settings navigation

Related Recipes

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