Skip to main content

benecaster_register_template_directory()

Template Free 
benecaster_register_template_directory( string $path ): bool

Registers a directory that Benecaster will look in when resolving template parts, so an add-on can ship its own parts and override Benecaster’s defaults. Call it from a benecaster_boot callback.

The reading half of the template layer already existed — benecaster_get_template_part(), benecaster_locate_template() and benecaster_get_template_path(). This is the registration half: until it shipped, the loader searched a hardcoded three-element list with no filter on it, so an add-on had no way at all to add template parts.

The directory mirrors the plugin’s templates/ structure — a file at {$path}/episode/title.php answers the template name episode/title. Benecaster does not need a template of that name for it to work: an add-on can ship parts Benecaster has never heard of and load them with benecaster_get_template_part() like any other.

Parameters

Name Type Default Required Description
$path string — Yes Absolute filesystem path, with or without a trailing slash. It does not have to exist at registration time — a missing directory simply never matches.

Return Value

Type: bool

True when the directory was added; false when the path was empty or that directory was already registered.

Example

add_action( 'benecaster_boot', function (): void {
    benecaster_register_template_directory(
        plugin_dir_path( __FILE__ ) . 'templates'
    );
} );

Notes

The full search order is now four locations:

child theme → parent theme → registered add-on dirs → plugin defaults

A theme still wins over everything, and an add-on overrides only Benecaster's own defaults. That is the promise the template system has always made to customer themes and this addition does not weaken it. An add-on that could outrank a child theme would silently undo work a site owner did by hand, with nothing in the UI to explain where their override went.

Among add-ons the order is registration order, which is add-on boot order — and nobody controls that. Two add-ons registering the same template name is not a supported arrangement. If you need to be sure yours wins, ship a distinct name.

benecaster_locate_template() does not see these directories, deliberately. It answers one question — "has the theme overridden this part?" — and an add-on directory is not a theme override. Use benecaster_get_template_path() for "what would actually load?".

Registering the same directory twice is a no-op rather than an error, so a double registration from an add-on that boots twice is harmless.

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