[benecaster_episodes]
Renders an episode list or grid for a show. By default shows all published episodes accessible to the current user’s tier. Locked episodes can be displayed with a teaser state (controlled by show_locked). Supports both static pagination (limit + offset) and query-string pagination (paged=“true”).
On single-show installs (exactly one published, non-archived show), show_id is optional — the shortcode auto-resolves the show via benecaster_get_sole_show_id(). On zero-show and multi-show installs without an explicit show_id, renders the HTML comment !-- benecaster: show_id required when running multiple shows -- and short-circuits.
Parameters
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
show_id |
int |
— | No | ID of the show whose episodes to list. Optional on single-show installs — auto-resolved. Required on multi-show installs. |
limit |
int |
10
|
No | Number of episodes per page. When paged="true", this is the page size; offset is ignored. |
offset |
int |
0
|
No | Static offset (number of episodes to skip). Ignored when paged="true". |
tier |
string |
current user tier
|
No | Filter to episodes accessible at a specific tier slug. Defaults to the current subscriber's tier. |
style |
string |
list
|
No | Layout style. Options: list, grid. |
show_locked |
bool |
true
|
No | Whether to show locked episodes with a teaser state. Set to false to hide inaccessible episodes entirely. |
orderby |
string |
date
|
No | Sort field. Options: date, episode_number. |
order |
string |
DESC
|
No | Sort direction. Options: ASC, DESC. |
paged |
bool |
false
|
No | When true, enables query-string pagination. The shortcode reads the current page from the `?ep_page=N` query variable (override the var name with the `benecaster_ep_page_query_var` filter) and renders a Previous / "Page N of M" / Next navigation strip below the list. The strip markup uses BEM classes: `benecaster-episodes__pagination`, `__pagination-link`, `__pagination-link--prev`, `__pagination-link--next`, `__pagination-status`. Replace the strip entirely with the `benecaster_episodes_pagination_output` filter. When paged="true", the `offset` attribute is ignored. Multiple paged shortcodes on the same page share the `?ep_page` query var by default — use `benecaster_ep_page_query_var` per shortcode to disambiguate. |
Example
<!-- List the 5 most recent episodes in grid layout -->
[benecaster_episodes show_id="3" limit="5" style="grid"]
<!-- All episodes, oldest first, hide locked -->
[benecaster_episodes show_id="3" order="ASC" show_locked="false"]
<!-- Paginated list, 10 per page -->
[benecaster_episodes show_id="3" paged="true" limit="10"]