Skip to main content

Put a tile on the Podcast Workflow Workbench, and say where it stands for each episode

Premium Advanced Podcast Workflow

The tile contract. Benecaster’s own Chapters tile and the partner add-ons (Sponsor Manager, Transcription, Guest Manager) build against these two filter names and both payloads; they change only with deprecation.

The Workbench is Podcast Workflow’s screen beside the episode editor: one episode’s tiles in four stage columns, each tile Not started, In progress or Done with an inline panel. There are two filters because what a tile is does not depend on an episode (a show’s Workflow settings tab lists tiles with no episode in hand) and where it stands does.

benecaster_workbench_tiles is a filter, ( array $tiles, int $show_id ): array. Add an entry keyed by the tile’s id (lowercase letters, digits, - and _, as sanitize_key() leaves them):

  • label (string, required): translated.
  • stage (string, required): pre-production, recording, post-production or publish.
  • priority (int, default 10): order within the stage, lowest first; ties by id.
  • default_on (bool, default false): whether the tile is drawn on a show that has not chosen for itself. Only true counts. It is only a default: a show’s choice in its Workflow settings tab overrides it (see Read or change which Workbench tiles a show draws, and run code when a show saves its choice).
  • add_on (string, default ''): your entitlement slug, when the tile shows your add-on’s data (see When a partner add-on is off below).
  • description (string, default ''): one line for the Workflow settings tab.

An entry with no label or an unknown stage is dropped, never drawn broken.

Add with $tiles + [ … ] (or check isset()), never $tiles[ $id ] = …. A filter cannot stop a later callback overwriting a key, so between add-ons an id stays first-come only while each adds this way. Podcast Workflow’s own eight tile ids (title, outline, recording-complete, show-notes, audio-video, artwork-metadata, availability, episode-status) are put back at the last priority, so they can never be replaced. They are declared at priority 5, so a callback at the default 10 sees them.

benecaster_workbench_tile_state is a filter, ( ?array $state, string $tile_id, int $episode_id, int $show_id ): ?array, called once per drawn tile per episode, starting from null. Every callback sees every tile: return $state untouched unless $tile_id is yours. $show_id is the episode’s own show (its post_parent), never the one picked in the show switcher. For your tile, return:

  • status: not_started, in_progress or done; anything else reads as not_started.
  • summary (string, default ''): one short plain-text line; past 120 characters it is cut.
  • count (int or null, default null): a number the panel shows.
  • action_url and action_label (strings, default ''): the panel’s one button, an admin-app route starting #/ (for example #/episodes/12?tab=chapters) or an http or https URL. There is no button unless both are set; anything else (javascript:, a bare word) is dropped.

A tile nobody answers for is Not started, with no summary and no button.

When a partner add-on is off. When add_on names an add-on that is off for the episode’s show, the state filter is not called for that tile: it is drawn Not started, with partner_active false and a line saying the add-on it reads from is off for this show. Whether the tile is drawn at all is the show’s tile choice, so default_on false keeps a partner tile hidden until the podcaster switches it on.

A tile that has something to show while its partner is off draws that itself. Podcast Workflow’s own partner tiles (Guest preparation, Subscriber notification, Sponsor confirmation and Transcription) declare no add_on, so they are asked for their state while the partner is off, and draw their own freeform form: a box and notes. See Read or save an episode’s Guest preparation, and run code when it is saved.

Code

<?php
add_filter( 'benecaster_workbench_tiles', function ( array $tiles, int $show_id ): array {
    return $tiles + [
        'chapter-markers' => [
            'label'      => __( 'Chapter markers', 'my-plugin' ),
            'stage'      => 'post-production',
            'priority'   => 40,
            'default_on' => false,
        ],
    ];
}, 10, 2 );

add_filter( 'benecaster_workbench_tile_state', function ( ?array $state, string $tile_id, int $episode_id, int $show_id ): ?array {
    if ( 'chapter-markers' !== $tile_id ) {
        return $state;
    }
    $count = count( my_plugin_chapters( $episode_id ) );
    return [
        'status'       => $count > 0 ? 'done' : 'not_started',
        /* translators: %d: number of chapters */
        'summary'      => sprintf( _n( '%d chapter', '%d chapters', $count, 'my-plugin' ), $count ),
        'count'        => $count,
        'action_url'   => '#/episodes/' . $episode_id . '?tab=chapters',
        'action_label' => __( 'Edit chapters', 'my-plugin' ),
    ];
}, 10, 4 );

View on GitHub →

Hooks Used

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