Switch on, restyle or extend the public guest directory
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,combinedorper_show), never the option. The box writes it throughPUT, PATCH /wp-json/benecaster-guest-manager/v1/settingswith{ directory_mode: 'off' | 'combined' | 'per_show' }(anything else is400 benecaster_guest_manager_invalid_settingwithdata.fielddirectory_mode). The older{ directory: bool }still works (true/false,1/0,"1"/"0"or"true"/"false"; anything else is the same 400 withdata.fielddirectory):trueturns an off directory to combined and leaves per show alone,falseturns it off; sent together,directory_modewins.GET /settingsanswers{ directory, directory_mode, directory_url, show_directories, portal }:directoryis whether/guests/is on,directory_urlits address,show_directorieseach show with Guest Manager on, A–Z, as{ show_id, name, url }with its own directory’s address, all given whatever the setting (portalis 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_optionsthrough benecaster_rest_permission_admin(), with theX-WP-Nonceheader), 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 varguest_searchnarrows 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 (showwhen 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", classbenecaster-guest-directory__show): All shows, then each show A–Z, with its slug as the value. The query varguest_shownarrows the list and the search to that show; page links and Show all guests keep it (/guests/page/2/?guest_show={show}&guest_search=…). Aguest_shownaming 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=1is 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 theguest/directory-list.phppart, which draws the list, the search (with the Show select on/guests/) and the page links. It readsGuestDirectory::data( get_query_var( 'guest_search' ), get_query_var( 'guests_page' ), null, $options ),$optionsbeing[ '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 withGuestDirectory::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 ofdirectory-list.phpdraws no select. Markup:benecaster-guest-directory(__heading,__search,__show,__count,__empty,__list,__guest,__photo,__text,__namelinking 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’sshow;0for every show,-1for 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_lineis Title, Organization or whichever is set,photo_urlthe thumbnail or'',urlthe guest page),previous_urlandnext_url(''at either end) andform({ 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;
} );
Hooks Used
Need this built rather than just documented? See our services →