Skip to main content

Switch on, restyle or extend the public guest directory

Premium Intermediate Guest Manager

Guest Manager can list guests A–Z on a public page at /guests/ (/?benecaster_guest_directory=1 under plain permalinks), and give each show with Guest Manager on a directory of its own at /{show prefix}/{show}/guests/. Both are off by default; the podcaster chooses with the Public guest directory box on Benecaster → Guests: Off, One combined directory or Combined, plus one for each show.

  • The setting is the site option benecaster_guest_manager_directory: '1' one combined directory, 'per_show' combined plus one for each show, anything else or missing off. Read it with benecaster_guest_manager_get_directory_mode() (off, combined or per_show), never the option. The box writes it through PUT, PATCH /wp-json/benecaster-guest-manager/v1/settings with { directory_mode: 'off' | 'combined' | 'per_show' } (anything else is 400 benecaster_guest_manager_invalid_setting with data.field directory_mode). The older { directory: bool } still works (true/false, 1/0, "1"/"0" or "true"/"false"; anything else is the same 400 with data.field directory): true turns an off directory to combined and leaves per show alone, false turns it off; sent together, directory_mode wins. GET /settings answers { directory, directory_mode, directory_url, show_directories, portal }: directory is whether /guests/ is on, directory_url its address, show_directories each show with Guest Manager on, A–Z, as { show_id, name, url } with its own directory’s address, all given whatever the setting (portal is the Guest portal switch, see Invite a guest to the Guest portal, or stop their link, from code, and change the invitation email). Admin only (manage_options through benecaster_rest_permission_admin(), with the X-WP-Nonce header), and no show: the directory is the site’s.
  • benecaster_guest_manager_before_save_settings ( array $changes ) fires with the keys sent, cleaned; benecaster_guest_manager_after_save_settings ( array $changes, array $settings ) fires once they are saved, with every setting as stored.
  • Who is listed: every published guest linked to at least one published episode on a show where Guest Manager is on, each once, A–Z by name, 30 to a page (/guests/page/{n}/, or &guests_page={n}; a page past the last shows the last). The query var guest_search narrows the list to guests whose name or organization contains the text, ignoring case. The public search never matches a guest’s email.
  • A show’s directory (per show only): /{show prefix}/{show}/guests/ and …/guests/page/{n}/, or /?benecaster_guest_directory=1&benecaster_guest_directory_show={show} under plain permalinks. {show} is the show’s slug, as in its own address; {show prefix} is Benecaster’s show prefix (show when unset). It lists and searches as /guests/ does, but only guests linked to a published episode of that show, under the heading and document title Guests on {show name}. A show that is unknown, unpublished or has Guest Manager off, or any show while the setting is not per show, is a 404.
  • /guests/‘s Show filter. While Guest Manager is on for more than one show, the search form on /guests/ draws a select labelled Show (name="guest_show", class benecaster-guest-directory__show): All shows, then each show A–Z, with its slug as the value. The query var guest_show narrows the list and the search to that show; page links and Show all guests keep it (/guests/page/2/?guest_show={show}&guest_search=…). A guest_show naming an unknown show, or one with Guest Manager off, is ignored and every show is listed. A show’s own directory draws no filter.
  • While on, the directory takes /guests/, even from a WordPress page of the site’s own at that address. While off, /guests/ is whatever the site has there without Guest Manager, and ?benecaster_guest_directory=1 is a 404. The page’s document title is Guests (or Guests matching “…”).
  • Template guest/directory.php (override it as {theme}/benecaster/guest/directory.php) draws the theme’s header and footer around the guest/directory-list.php part, which draws the list, the search (with the Show select on /guests/) and the page links. It reads GuestDirectory::data( get_query_var( 'guest_search' ), get_query_var( 'guests_page' ), null, $options ), $options being [ 'show_id' => GuestDirectory::show_id() ] on a show’s directory and [ 'show_id' => GuestDirectory::filter_show_id(), 'show_filter' => true ] on /guests/, and heads the page with GuestDirectory::heading( $show_id ). A theme’s copy from before per-show directories still lists only that show’s guests on a show’s directory, under the heading Guests, and offers no filter; an older copy of directory-list.php draws no select. Markup: benecaster-guest-directory (__heading, __search, __show, __count, __empty, __list, __guest, __photo, __text, __name linking to the guest page, __title, __pages, __previous, __position, __next).
  • benecaster_guest_manager_guest_directory_data ( array $directory ) filters what is drawn: show_id (the show whose guests are listed: a show’s directory, /guests/‘s filter or the shortcode’s show; 0 for every show, -1 for nobody), show_filter (the Show select’s choices, each { show_id, name, slug, selected }; [] elsewhere and with fewer than two shows on), search, page, pages, total, guests (this page’s, each { guest_id, name, title_line, photo_url, url }: title_line is Title, Organization or whichever is set, photo_url the thumbnail or '', url the guest page), previous_url and next_url ('' at either end) and form ({ action, hidden }, the search form’s address and the fields plain permalinks need). Values are raw; the template escapes them. Keys a callback leaves out keep their values.
  • benecaster_guest_manager_before_guest_directory and benecaster_guest_manager_after_guest_directory ( array $directory ) fire after the theme header and before the theme footer.

To put the same list on a page of your own, whether or not /guests/ is on, use benecaster_guests.

Code

<?php
// Switch the directory on from code, e.g. in a site-setup script.
$request = new WP_REST_Request( 'PATCH', '/benecaster-guest-manager/v1/settings' );
$request->set_body_params( [ 'directory' => true ] );
rest_do_request( $request );

// Or give each show with Guest Manager on a directory of its own as well.
$request->set_body_params( [ 'directory_mode' => 'per_show' ] );
rest_do_request( $request );

// Put guests with a photo first on each page, keeping A–Z within each group.
add_filter( 'benecaster_guest_manager_guest_directory_data', static function ( array $directory ): array {
    usort( $directory['guests'], static fn( array $a, array $b ): int => ( '' === $a['photo_url'] ) <=> ( '' === $b['photo_url'] ) ?: strcasecmp( $a['name'], $b['name'] ) );
    return $directory;
} );

View on GitHub →

Hooks Used

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