Skip to main content

Inject a synthetic reference group from an add-on

Free Intermediate

Reference groups organise show-notes links into labelled sections. Groups normally come from the show’s own configuration, but an add-on can append one that exists only at render time — useful when the links are derived rather than stored: sponsor links pulled from a campaign, affiliate URLs, or transcript downloads generated per episode. The Outlinks add-on injects its “Tracked Links” group exactly this way.

A synthetic group is not persisted. It appears wherever references render and disappears when the add-on is deactivated, which is usually the behaviour you want — deactivating an add-on should not leave orphaned groups in the show’s configuration.

Use id: 0 for a synthetic group. The id column on benecaster_reference_groups is an auto-incrementing bigint, so real rows always have a positive integer id and 0 is the one value that can never collide with one. Do not use a namespaced string such as my-addon-sponsors — the field is matched against integer group ids and a string will not resolve.

The template buckets reference entries by group_id; entries with group_id = null or an unrecognised id fall under a configurable fallback heading. Control placement with display_order — negative to sort above the show’s own groups, high positive to sort below.

Code

<?php
add_filter( 'benecaster_reference_groups', function ( array $groups, int $show_id ): array {
    if ( ! my_addon_is_active_for_show( $show_id ) ) {
        return $groups;
    }

    array_unshift( $groups, [
        'id'            => 0,
        'name'          => __( 'Tracked Links', 'my-addon' ),
        'display_order' => -1,
    ] );

    return $groups;
}, 10, 2 );

View on GitHub →

Hooks Used

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

Powered by