Skip to main content

benecaster_setup_wizard_steps

Filter Free

Filters the ordered array of step definitions passed to the Setup Wizard before the wizard shell is rendered. Add-ons use this filter to inject custom configuration steps, reorder existing steps, or conditionally remove steps based on site state.

Each step definition requires four keys: id (a unique slug used in completion tracking), component (the registered React component name), required (whether the step can be skipped), and condition (an optional state flag that must be true for the step to appear). Unrecognised condition strings default to false, so steps are safely hidden until their flag-setting logic is deployed. Benecaster step IDs for positioning: show-name, description, artwork, category, subscription, tiers, migration, import, all-done.

The component must name a function on window.BenecasterExtensions. That object also carries Benecaster’s React runtime (React, ReactDOM, ReactDOMClient, ReactJSXRuntime, i18n, extensionRuntimeVersion), and the wizard renders a step only when the named value is callable, so do not name a component after one of those keys.

A step component may use React hooks when its bundle maps Benecaster’s runtime as externals, as described in Inject a React component into a named slot. Enqueue the step’s script with benecaster-wizard as a dependency, not benecaster-admin. The wizard does not publish ReactQuery or queryClient, so do not externalise @tanstack/react-query in a wizard bundle; fetch with window.fetch.

Parameters

Name Type Default Description
$steps array — Ordered array of step definition arrays

Returns: array

Examples

Inject step after RSS step

add_filter( 'benecaster_setup_wizard_steps', function( $steps ) {
    // Inject a custom "Analytics" step after the "RSS" step.
    $position = array_search( 'rss', array_column( $steps, 'id' ), true );
    $new_step = [ 'id' => 'analytics', 'label' => 'Analytics Setup', 'add_on' => 'my-analytics-addon' ];
    array_splice( $steps, $position !== false ? $position + 1 : count( $steps ), 0, [ $new_step ] );
    return $steps;
} );

Inject bridge-conditional step

add_filter( 'benecaster_setup_wizard_steps', function ( array $steps ): array {
    $insert_after = array_search( 'subscription', array_column( $steps, 'id' ), true );

    if ( false !== $insert_after ) {
        array_splice( $steps, $insert_after + 1, 0, [[
            'id'        => 'my-addon-config',
            'component' => 'MyAddonWizardStep',
            'required'  => false,
            'condition' => 'bridge_connected',
        ]] );
    }

    return $steps;
} );

Notes

Use array_search on array_column( $steps, 'id' ) to find the insertion point, then array_splice to insert. Always return the modified array. Unrecognised condition strings default to false — it is safe to deploy a step before its flag-setting logic exists. Three bridge condition flags are set when the user continues from the Subscription step: bridge_connected (any option chosen, Built-in membership included), builtin_chosen (Built-in membership chosen) and external_bridge_connected (any other membership plugin chosen). Use external_bridge_connected for a step that reads an external plugin's levels.

Affects

  • Setup Wizard

Related Recipes

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