Skip to main content

Point your add-on’s tour at your own Show Settings tab

Free Intermediate

An add-on tab in a show’s settings is declared in PHP and filled by your own component, but Benecaster draws the tab button itself, so your code never sees it. The button carries a data-tour anchor made from your page id plus -nav, which is what a tour’s first step needs. Declare the tab as usual:

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' => 'benecaster-addon-my-addon',
    ];
    return $pages;
}, 10, 2 );

The tab button then renders with data-tour="my-addon-nav", and the tour in the example targets it.

  • There is nothing to declare. Every add-on tab gets the anchor automatically, so a
    tour cannot be broken by a declaration that left out a field. Without the anchor, a step aimed at the tab would wait two seconds and then show its tip attached to nothing.
  • Use screen: 'show-settings:{page id}'. Benecaster fills in the current show when
    the tour starts, so this step and an episode-references step in the same tour visit the same show.
  • Never write a raw /shows/{id}/settings/{page id} path. A show ID baked in when the
    tour is built can differ from the current show, so a two-screen tour visits two shows. A path with no usable ID lands on Invalid show ID in URL, and the step waits there for a target that never renders. A bare 'my-addon' resolves to a route that does not exist.
  • The step is left out, not navigated to, when there is no current show, when your
    add-on is switched off for it, or when that lookup fails. If every step of a tour is left out, the tour does not start.
  • The page id is the contract. It names the anchor and the screen, and is also the
    tab’s URL segment, so renaming it changes all three. It must be one path segment: letters, digits, - and _.
  • Benecaster’s own tabs work as screens too (show-settings:feeds, show-settings:emails).
  • Benecaster’s own tabs do not carry this anchor, so do not target details-nav or
    similar. Neither does the site-wide Settings navigation.
  • If your tab only appears in some states, give the step a condition as well. See
    Gate a tour step on what the screen actually renders.

Code

window.BenecasterExtensions = window.BenecasterExtensions || {};
window.BenecasterExtensions.tours = window.BenecasterExtensions.tours || [];

window.BenecasterExtensions.tours.push( {
    id:    'my-addon',
    label: 'My Add-on',
    steps: [
        {
            id:      'my-addon-entry',
            target:  '[data-tour="my-addon-nav"]',
            // Your page's `id`. The current show is filled in when the tour starts,
            // and the step is left out where the add-on is off for that show.
            screen:  'show-settings:my-addon',
            title:   'Your add-on lives here',
            content: 'Everything this add-on does for a show is on this tab.',
        },
        {
            id:      'my-addon-reference-control',
            target:  '[data-tour="my-reference-control"]',
            screen:  'episode-references',   // the same show as the step above
            title:   'Then use it on an episode',
            content: 'Explain the control here.',
        },
    ],
} );

View on GitHub →

Hooks Used

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