Skip to main content

Register a custom Episode Page block from an add-on

Free Intermediate

Use benecaster_episode_page_block_types to add a block type that appears in a show’s Episode Page Blocks panel alongside the built-in ones. Register it from your add-on’s boot code.

Pass your add-on’s entitlement slug as requires (the slug benecaster_addon_is_active() takes). On a show where your add-on is not active, the episode page leaves the block out, and the panel shows the row faded with your add-on’s name and a link to Settings → Add-ons or your shop page. The podcaster’s on/off choice is kept, so switching your add-on back on for that show brings the block back. You don’t need to check activation in your renderer.

Return '' from the renderer when there is nothing to show for an episode, and the block leaves no trace on the page.

Theme and site developers can then override or suppress your block’s HTML without touching your add-on, through the per-block filter benecaster_episode_page_block_{slug}, here benecaster_episode_page_block_my_sponsors:

add_filter(
    'benecaster_episode_page_block_my_sponsors',
    function ( string $html, int $episode_id, int $show_id, array $config ): string {
        return '' === $html ? '' : '<div class="my-theme-sponsors">' . $html . '</div>';
    },
    10,
    4
);

Code

<?php
add_filter( 'benecaster_episode_page_block_types', function ( array $types ): array {
    $types['my_sponsors'] = [
        'label'    => __( 'Sponsors of this episode', 'my-addon' ),
        'default'  => true,
        'position' => 'after',
        'requires' => 'benecaster-addon-my-addon',
        'renderer' => static function ( int $episode_id, int $show_id, array $config ): string {
            $sponsors = my_addon_get_sponsors( $episode_id );
            if ( empty( $sponsors ) ) {
                return '';
            }
            $items = implode( '', array_map(
                static fn( $sponsor ) => '<li>' . esc_html( $sponsor->name ) . '</li>',
                $sponsors
            ) );
            return '<ul class="my-addon-sponsors">' . $items . '</ul>';
        },
        'settings' => static fn( array $config ): string => '', // not read; see the notes
    ];
    return $types;
} );

View on GitHub →

Hooks Used

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