WordPress как на ладони
wordpress jino

Иерархия файлов темы (шаблона)

В этом посте речь пойдет о том, какие бывают названия у файлов темы WordPress и за показ какой страницы на сайте отвечает каждый из них. Это очень важные, нужные, и в тоже время очень простые, для понимания, знания. Ими должен обладать каждый, кто работает с WordPress. Ниже полностью расписана структура файлов темы WordPress и порядок их подключения (иерархия).

Об иерархии файлов темы я упоминал в статье «Условные теги в WordPress». А ниже тоже самое, только подробнее и понятнее.

Подключения файлов темы (теория)

Иерархия в данном случае - последовательная проверка, говорит о том, что для вывода одной страницы на сайте, подходят несколько названий файлов. Проверка какой файл будет использован идет поочередно. Т.е. есть список файлов, каждый из них по очереди проверяется на физическое существование, как только найден существующий файл проверка прекращается и найденный файл используется в качестве шаблона.

Например, мы заходим на страницу рубрики «Плагины» с ярлыком plugins и id 25 - http://site.ru/category/plugins. Тогда для генерации кода этой страницы WordPress будет по очереди проверять наличие следующих файлов (проверка прервется на первом существующем файле):

  • category-plugins.php
  • category-25.php
  • category.php
  • archive.php
  • index.php

Полная схема для всех видов страниц и их файлов выглядит так:

template-hierarchy

Еще одна схема, возможно она понятнее (старая):

Иерархия фалов темы WordPress

Типы страниц и названия файлов

Ниже список страниц и отвечающие за них файлы темы. В этом разделе расписана картинка иерархии файлов темы, которая немного выше.

Ниже указана страница сайта и соответствующий ей список PHP файлов. Такие файлы должны находится в корневой папке темы.

Записи

Страница (запись page)

  • {любое_название}.php (когда используется шаблон страницы)
  • page-{ярлык_записи}.php
  • page-{ID_записи}.php
  • page.php
  • singular.php
  • index.php

Запись (запись post)

  • single-post-{ярлык_записи}.php
  • single-post.php
  • single.php
  • singular.php
  • index.php

Произвольный тип записи

  • {любое_название}.php (для древовидного типа с поддержкой шаблонов. С WP 4.7)
  • single-{post_type}-{ярлык_записи}.php
  • single-{post_type}.php
  • single.php
  • singular.php
  • index.php

Вложение

  • {начало_MIME_типа}.php
  • {конец_MIME_типа}.php
  • {начало_MIME_типа}-{конец_MIME_типа}.php
  • attachment.php
  • single.php
  • singular.php
  • index.php

Под началом и концом MIME типа, имеется виду первая и последняя часть MIME типа, разделенная /. Например, MIME-тип текстового файла: 'text/plain' и значит будет проверяться наличие файл text.php, затем plain.php, затем text-plain.php.

Полный список MIME типов смотрите в описании get_allowed_mime_types().

Архивы

Рубрика

  • category-{ярлык}.php
  • category-{id}.php
  • category.php
  • archive.php
  • paged.php (если страница пагинации)
  • index.php

Метка

  • tag-{ярлык}.php
  • tag-{id}.php
  • tag.php
  • archive.php
  • paged.php (если страница пагинации)
  • index.php

Таксономия

  • taxonomy-{ярлык_таксономии}-{ярлык_элемента}.php
  • taxonomy-{ярлык_таксономии}.php
  • taxonomy.php
  • archive.php
  • paged.php (если страница пагинации)
  • index.php

Страница архива типа записи

  • archive-{ярлык_типа_записи}.php
  • archive.php
  • paged.php (если страница пагинации)
  • index.php

Страница автора

  • author-{nickname}.php
  • author-{id}.php
  • author.php
  • archive.php
  • paged.php (если страница пагинации)
  • index.php

Страница архива по дате (день, месяц, год)

  • date.php
  • archive.php
  • paged.php (если страница пагинации)
  • index.php

404 страница

  • 404.php
  • index.php

Страница поиска

  • search.php
  • index.php

Главная страница

  • front-page.php
  • (логика постоянных страниц, если для главной выбрана страница)
  • home.php
  • index.php

Страница блога

Страница блога появляется, когда для главной выбрана постоянная страница

  • home.php
  • index.php

Встраивания (embeds)

Шаблоны встраивания используются когда запрашивается запись через REST API. Встраивания появились в версии 4.5 и позволяют встраивать ваши записи в чужие сайты. См. get_post_embed_url()

  • embed-{post-type}-{post_format}.php
  • embed-{post-type}.php
  • embed.php

Чтобы сразу изменить только контент встраивания можно в теме создать файл embed-content.php и описать там HTML. Оригинальный HTML находится в файле движка /wp-includes/theme-compat/embed-content.php

Как это работает

За всю логику: какой файл подключать, отвечает файл ядра wp-includes/template-loader.php. Если разобраться, в нем все описано. Но, это занятие не особо интересное, поэтому я его распишу.

Прежде всего. template-loader.php подключается после того как загрузится вся среда WordPress. После того, как отработает файл wp-load.php и обработается основной запрос - функция wp(). Т.е. template-loader.php подключается в самом-самом конце PHP скрипта...

Сначала срабатывает хук template_redirect. В этом хуке можно произвести какие-то проверки и если надо перенаправить на другой URL. В нем нужно обрывать работу скрипта через die(). Т.е. если этот хук что-то меняет, то на этом работа файла template-loader.php заканчивается и мы «улетаем» на какую-то другую страницу.

Дальше срабатывает никому не интересный хук exit_on_http_head. Он позволяет сделать так, чтобы при HTTP HEAD запросе что-либо выводилось на экран...

Дальше идут проверки по всем условным тегам где выясняется какой файл шаблона подходит под текущий запрос. Проверяется условный тег, затем еще один и еще... Как только один из условных тегов сработал, вызывается соответствующая функция, которая находит подходящий файл шаблона и возвращает путь до него. Все такие функции описаны в get_query_template().

Дальше - путь до файла темы определен! Теперь он прогоняется через фильтр template_include. Который позволяет нам изменить файл шаблона для текущего запроса.

Дальше, файл подключается в PHP и запускается визуальная часть генерации страницы.

Фильтры

Иерархию файлов можно изменить через динамические фильтры:

  • (type)_template_hierarchy - фильтрует массив названий файлов иерархии, по которому будет идти поиск нужного файла. С WP 4.7.

  • (type)_template - фильтрует путь до уже определившегося файла шаблона.

Все варианты параметра type смотрите в одноименном параметр $type функции get_query_template(). Вот они:

  • index
  • 404
  • archive
  • post_type_archive
  • author
  • category
  • tag
  • taxonomy
  • date
  • home
  • front_page
  • page
  • paged
  • search
  • single
  • singular
  • attachment
  • comments_popup

Пример использования такого фильтра смотрите в ответе на этот вопрос.

Иерархия файлов темы (шаблона) 4 комментария
  • Алексей @

    Здравствуйте! Подскажите пожалуйста какой нужно создать файл чтобы сделать страницу вывода всех названий статей на сайте?

    • Kama4662

      Создай постоянную страницу, допустим с ярлыком, allposts. Далее создай файл в шаблоне page-allposts.php и в нем, кроме шапок и подвалов, получи все записи через get_posts() и выведи их названия через цикл...

      1

Здравствуйте, !

Ваш комментарий