[benecaster_episodes]
Renders an episode list or grid for a show. By default it shows each visitor what they can hear: every episode is checked with benecaster_user_can_access_episode(), so an episode the logged-in listener holds through a buy-up or a standalone grant is playable, just as it is in their podcast app. Locked episodes can be displayed with a teaser state (controlled by show_locked).
tier="…" asks a different question. With tier, the list shows what that tier carries plus your public episodes, the same list for every visitor: a catalogue of the tier, not a view of what this visitor can hear. Paging counts that list. Whether each listed episode plays still depends on the visitor. One they can’t hear (a logged-out visitor, or someone not on that tier) shows as Subscriber only with no player, so listing a paid tier never publishes its audio. show_locked has no effect with tier: the catalogue is never trimmed to what the visitor can play.
Long lists on slow hosts. Without tier, access is decided per episode, so a very long list costs more to render than it would with tier, which is answered in a single query. Keep limit modest or turn on paged if a large archive renders slowly. Supports both static pagination (limit + offset) and query-string pagination (paged=“true”).
What each item plays. An item the visitor can hear plays its audio. A video-only episode (a video URL and no audio URL) plays as video instead, in <video class="benecaster-episodes__video" controls playsinline preload="none">, its URL passed through benecaster_episode_video_url. An episode with both files always lists the audio: unlike [benecaster_player], this shortcode has no media attribute. Locked items show the Subscriber only badge with no player and no file URL on the page; the list plays no preview clips.
show_id is optional. Without it, the shortcode uses the show whose page it is on (a show page, or an episode page’s show), and anywhere else the site’s only show. On a multi-show site, on a page that is neither, it 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: with no show_id, a show page lists that show, an episode page lists its show, and anywhere else a single-show site uses its only show. Needed only on a multi-show site, on a page that is neither a show nor an episode page. |
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 |
— | No | List what this tier slug carries, plus your public episodes, the same list for every visitor. Each item still plays only for a visitor who can hear it; the rest show as locked. Omit to show each visitor their own access, buy-ups and grants included. |
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 episodes the visitor can't hear. Has no effect with tier=, which always lists the tier's whole catalogue and shows the episodes this visitor can't play as locked. |
orderby |
string |
date
|
No | What the list is sorted by. Options: `date` (publish date) and `episode_number`. Episode numbers sort numerically, so episode 10 comes after episode 2. An episode with no number set is still listed: it comes last when `order` is DESC and first when it is ASC. Any other value is treated as `date`. |
order |
string |
DESC
|
No | Sort direction for `orderby`. Options: ASC (oldest or lowest first), DESC (newest or highest first). |
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"]