`benecaster_episodes_pagination_output`

Filter Free Since v1.0.0

Replaces the pagination navigation strip rendered by [benecaster_episodes paged="true"]. The filter fires once per shortcode render when paged="true" is set — even on single-page results, so you can inject a custom strip regardless of whether multiple pages exist.

The default strip markup is a <nav class="benecaster-episodes__pagination" aria-label="Episode pagination"> element containing Previous and Next links (BEM classes: __pagination-link--prev, __pagination-link--next) and a status span (__pagination-status — “Page N of M”). The Previous link on page 2 points to the bare base URL with no ?ep_page parameter (not ?ep_page=1).

Return any string to replace the default. Return an empty string "" to suppress the strip entirely. Return $html unchanged to use the default.

Parameters

Name	Type	Default	Description
`$html`	`string`	—	The fully-rendered default pagination strip HTML.
`$query`	`WP_Query`	—	The resolved WP_Query for this shortcode render. Use `$query->max_num_pages` for the total page count and `$query->query_vars['paged']` for the current page.
`$atts`	`array`	—	The resolved shortcode attribute array after defaults are applied (same shape as the `[benecaster_episodes]` parameter list).

Returns: string

Examples

Replace pagination with a simple load-more button

add_filter( 'benecaster_episodes_pagination_output', function ( string $html, \WP_Query $query, array $atts ): string {
    $current = (int) ( $query->query_vars['paged'] ?? 1 );
    $max     = (int) $query->max_num_pages;

    if ( $current >= $max ) {
        return ''; // no more pages
    }

    $next_url = add_query_arg( 'ep_page', $current + 1 );
    return sprintf(
        '<div class="my-load-more"><a href="%s" class="my-load-more__btn">%s</a></div>',
        esc_url( $next_url ),
        esc_html__( 'Load more episodes', 'my-theme' )
    );
}, 10, 3 );

Notes

The filter fires on every render of a paged="true" shortcode, including page 1 when there is only one page. Check $query->max_num_pages before building navigation to avoid rendering arrows that point nowhere. The query var read by the shortcode defaults to ep_page but can be overridden per shortcode with benecaster_ep_page_query_var — use get_query_var() with the overridden var name if you need the current page inside this filter.