04 Ноя
В разработке плагинов для WordPress одна из ключевых задач — предоставить пользователю возможность кастомизировать внешний вид вывода данных. Лучший пример — WooCommerce, где вы можете просто скопировать шаблон из папки плагина в папку своей темы и изменить верстку под свои нужды. Сегодня разберем, как реализовать аналогичную систему шаблонов в собственном плагине WordPress.
Зачем нужна система шаблонов в плагине
Когда вы создаете плагин с собственными типами записей (Custom Post Types), например property или agent, вам нужно вывести их на фронтенде — в виде архивных страниц и отдельных карточек.
Обычно для этого используются файлы:
archive-{post_type}.php— архив записей;single-{post_type}.php— страница отдельной записи.
Но если шаблон прописан жестко внутри плагина, пользователь не сможет его изменить, не правя сам плагин (что плохо и непрактично).
Решение — система переопределяемых шаблонов: WordPress будет искать шаблон в теме (или дочерней теме), и только если не найдет — использовать дефолтный файл из плагина.
Как работает переопределение шаблонов
Алгоритм очень простой:
- WordPress сначала проверяет, есть ли файл шаблона в дочерней теме (
child theme). - Если его нет — смотрит в родительской теме (
theme). - Если и там не найден — использует шаблон из самого плагина.
Эта логика позволяет разработчику сделать плагин максимально гибким и совместимым с любыми темами.
Структура каталогов плагина
Для начала в корне вашего плагина создайте папку:
/templates/
В ней будут лежать все шаблоны по умолчанию. Например:
/templates/archive-property.php
/templates/single-property.php
/templates/archive-agent.php
/templates/single-agent.php
Эти файлы будут использоваться, если пользователь не создаст свои версии шаблонов в теме.
Подключение класса Template Loader
Для реализации системы переопределения удобно использовать отдельный класс — Template Loader.
Он будет отвечать за поиск нужных шаблонов и подключение их в нужный момент.
Создайте в плагине файл:
inc/class-template-loader.php
И добавьте туда логику:
class MyPlugin_Template_Loader {
protected $plugin_dir;
protected $plugin_templates_dir = 'templates';
protected $theme_templates_dir = 'myplugin';
public function __construct() {
$this->plugin_dir = plugin_dir_path(__FILE__);
add_filter('template_include', [$this, 'load_template']);
}
public function load_template($template) {
if (is_post_type_archive('property')) {
return $this->locate_template('archive-property.php', $template);
}
if (is_singular('property')) {
return $this->locate_template('single-property.php', $template);
}
if (is_post_type_archive('agent')) {
return $this->locate_template('archive-agent.php', $template);
}
if (is_singular('agent')) {
return $this->locate_template('single-agent.php', $template);
}
return $template;
}
protected function locate_template($filename, $default) {
$child_theme_path = get_stylesheet_directory() . '/' . $this->theme_templates_dir . '/' . $filename;
$parent_theme_path = get_template_directory() . '/' . $this->theme_templates_dir . '/' . $filename;
$plugin_path = $this->plugin_dir . $this->plugin_templates_dir . '/' . $filename;
if (file_exists($child_theme_path)) return $child_theme_path;
if (file_exists($parent_theme_path)) return $parent_theme_path;
if (file_exists($plugin_path)) return $plugin_path;
return $default;
}
}
Подключаем класс в основном файле плагина
В главном файле плагина (например, myplugin.php) добавьте:
require_once plugin_dir_path(__FILE__) . 'inc/class-template-loader.php';
new MyPlugin_Template_Loader();
Теперь при загрузке страницы WordPress будет проверять наличие нужного шаблона в теме, а при его отсутствии — брать стандартный из плагина.
Как переопределить шаблон в теме
Если пользователь хочет изменить верстку, он может просто:
- Создать в папке темы (или дочерней темы) каталог
myplugin. - Скопировать туда нужный шаблон, например:
wp-content/themes/my-theme/myplugin/archive-property.php - Отредактировать этот файл по своему усмотрению.
После этого WordPress будет использовать именно этот шаблон, не трогая оригинал в плагине.
Проверка работы
- Перейдите на архивную страницу вашего кастомного типа, например:
/property/ - Если в теме нет переопределений — загрузится шаблон из плагина.
- Добавьте файл
archive-property.phpв тему и обновите страницу — теперь подтянется именно он. - Удалите — WordPress снова возьмет шаблон из плагина.
Типичные ошибки и их решение
- 404 на страницах архива:
Проверьте, что включены «ЧПУ-ссылки» (Permalinks) → “Название записи”. - Шаблон не применяется:
Убедитесь, что slug шаблона совпадает с post type (archive-property.phpдляproperty). - Путь до шаблонов указан неверно:
Используйтеplugin_dir_path(__FILE__)— это гарантирует корректный путь даже при разных структурах каталогов.
Заключение
Создание собственной системы шаблонов в плагине WordPress — обязательный шаг, если вы хотите, чтобы ваш продукт был гибким, как WooCommerce.
Такой подход:
- дает пользователям свободу редактирования;
- предотвращает потерю изменений при обновлениях;
- делает плагин более профессиональным и масштабируемым.
Теперь ваш плагин может динамически загружать шаблоны из темы или из собственного каталога — в зависимости от того, где они доступны.
