Skip to main content

Register an add-on CPT with the custom field system

Premium Intermediate

Benecaster registers benecaster_episode with the field system automatically. Add-ons that introduce their own CPTs (e.g. Guest Manager’s benecaster_guest, Sponsor Manager’s benecaster_sponsor) call benecaster_register_field_cpt() so the CPT appears in the Field Group editor’s “Attached CPT” dropdown. Call it on init, from the callback you pass to benecaster_register_addon(). Also shows reading and saving the values in your own editor with the useFieldValues and useSaveFieldValues hooks Benecaster publishes on window.BenecasterExtensions.

When to Use This

  • Your add-on introduces a custom post type with its own editor screen

  • You want podcasters to be able to create Field Groups and attach them to that CPT via Benecaster → Fields

  • You want to show and save those field groups’ values in your own editor screen

  • You want field values to be stored and retrieved through the standard benecaster_get_field() / benecaster_get_fields() API

Benecaster auto-registers benecaster_episode. Everything else must be registered explicitly by its add-on.

How It Works

There are two halves — a one-line PHP registration and a React panel in your editor.

PHP — register the CPT from your add-on’s gated boot. Call benecaster_register_field_cpt() on init, hooked from the callback you pass to benecaster_register_addon(), passing your CPT slug and a human-readable label. The label is what podcasters see in the “Attached CPT” dropdown of the Field Group editor.

Not straight from benecaster_boot. That fires whether or not your add-on is switched on for any show, so the Fields screen would offer your post type on a site where it is not registered. The gated callback runs only while the add-on does, alongside the post type itself. init because the label is translated, and WordPress 6.7 and later warn about translations loaded earlier; Benecaster reads the list only when the Fields screen asks, so that is never too late.

React — fetch and save values in your editor. Benecaster publishes two hooks on window.BenecasterExtensions for this, and both accept any registered CPT slug:

  • useFieldValues( cpt, objectId ) answers { groups }. Each group has id, name and fields; each field has id, field_label, field_key, field_type, options, required and its current value. Pass null for a record not saved yet to get the groups with empty values.
  • useSaveFieldValues() returns a mutation. Call mutate( { cpt, objectId, values } ) with values as { field_id, value } pairs; it saves through POST /benecaster/v1/field-values/{cpt}/{id} and refreshes that record’s values. The endpoint accepts every registered CPT, so there is nothing further to wire up on the server side.

Call them only inside a component Benecaster renders: a fill registered into a slot, or the body of your own admin screen (declared with benecaster_admin_screens). They run on Benecaster’s own query client, so in a React root of your own they throw. Map react to window.BenecasterExtensions.React in your bundler so your component shares Benecaster’s React — see inject-react-component-into-slot.

Draw the inputs yourself. The field UI on the episode editor’s More tab is not published for add-ons, so render each field from its field_type. The example below handles text fields only; hold edits in local state and send them on save.

function GuestFieldsPanel( { guestId }: { guestId: number | null } ) {
    const { useFieldValues, useSaveFieldValues } = window.BenecasterExtensions;
    const { data, isLoading } = useFieldValues( 'benecaster_guest', guestId );
    const save = useSaveFieldValues();
    const [ edits, setEdits ] = React.useState<Record<number, unknown>>( {} );

    if ( isLoading ) return null;

    return (
        <div>
            { ( data?.groups ?? [] ).map( ( group ) => (
                <fieldset key={ group.id }>
                    <legend>{ group.name }</legend>
                    { group.fields.map( ( field ) => (
                        <label key={ field.id }>
                            { field.field_label }
                            <input
                                value={ String( edits[ field.id ] ?? field.value ?? '' ) }
                                onChange={ ( e ) => setEdits( ( prev ) => ( { ...prev, [ field.id ]: e.target.value } ) ) }
                            />
                        </label>
                    ) ) }
                </fieldset>
            ) ) }
            <button
                type="button"
                disabled={ ! guestId || save.isPending }
                onClick={ () => save.mutate( {
                    cpt: 'benecaster_guest',
                    objectId: guestId!,
                    values: Object.entries( edits ).map( ( [ id, value ] ) => ( { field_id: Number( id ), value } ) ),
                } ) }
            >
                Save fields
            </button>
        </div>
    );
}

Notes

Registration lives for the request. benecaster_register_field_cpt() writes to an in-memory registry inside FieldRegistry, so it runs on every request your add-on is active for. An add-on switched off for every show registers nothing and drops out of the list; its field groups stay until it is back.

Values go with the post. Permanently deleting one of your posts removes its stored field values, so you need no clean-up of your own. Read a value you still need on your post type’s own deletion action at priority 10 or earlier.

The benecaster_field_groups filter works for your CPT automatically. After registration, the filter fires with your CPT slug whenever the field editor loads. Add-ons can inject synthetic groups for your CPT using the same pattern as for episodes — see Inject a Dynamically Generated Field Group.

benecaster_get_field() and benecaster_get_fields() work for your CPT without any extra configuration. The REST endpoint and public functions respect CPT context because every stored field value carries the CPT slug it belongs to — field values are scoped per CPT automatically.

The same hooks serve episodes. The episode editor calls useFieldValues( 'benecaster_episode', episodeId ); your add-on calls it with its own slug.

Related

Code

<?php
// PHP — register the CPT from the gated boot, on init
add_action( 'benecaster_boot', function ( \Benecaster\Container $container ) {
    benecaster_register_addon(
        'benecaster-addon-guest-manager',
        static function ( \Benecaster\Container $container ): void {
            // Runs only while the add-on is switched on for at least one show.
            add_action( 'init', static function (): void {
                benecaster_register_field_cpt( 'benecaster_guest', __( 'Guest', 'benecaster-guest-manager' ) );
            } );
        }
    );
} );

// React — fetch and save field values in your own editor: see the TSX example above, which
// uses window.BenecasterExtensions.useFieldValues and useSaveFieldValues inside a fill.

View on GitHub →

Hooks Used

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