Руководство по получению пути и имени шаблона в Cotonti

Оглавление

• Введение
• Глава 1. Архитектура шаблонов Cotonti
  • 1.1. Функция cot_tplfile()
  • 1.2. Класс XTemplate и его роль
  • 1.3. Базовый URL сайта $sys['abs_url']
• Глава 2. Метод 1: Функция cot_tpl_url() – получение URL шаблона по имени
  • 2.1. Назначение и принцип работы
  • 2.2. Параметры функции
  • 2.3. Примеры вызова в шаблонах
  • 2.4. Когда использовать
  • 2.5. Ограничения и особенности
• Глава 3. Метод 2: Функция cot_debug_tpl_url() – автоматическое определение текущего шаблона
  • 3.1. Назначение
  • 3.2. Как это работает: debug_backtrace() и Reflection API
  • 3.3. Примеры использования
  • 3.4. Когда использовать
  • 3.5. Ограничения и рекомендации
• Глава 4. Метод 3: Присваивание пути в тег шаблона через $t->assign()
  • 4.1. Назначение
  • 4.2. Пример реализации в PHP-коде
  • 4.3. Вывод в шаблоне
  • 4.4. Когда использовать
  • 4.5. Преимущества и недостатки
• Глава 5. Сравнение методов
• Глава 6. Практические сценарии и рекомендации
  • 6.1. Отладка вёрстки
  • 6.2. Подключение ресурсов шаблона
  • 6.3. Создание документации
  • 6.4. Разработка расширений
• Глава 7. Размещение функций в system/functions.custom.php
  • 7.1. Что такое functions.custom.php
  • 7.2. Подключение файла
  • 7.3. Рекомендации по организации
• Заключение
• Приложение A. Полный листинг функций
  • A.1. cot_tpl_url()
  • A.2. cot_debug_tpl_url()
• Приложение B. Примеры использования в разных модулях
• Приложение C. Код для размещения в functions.custom.php

Введение

Cotonti — это гибкая система управления контентом, в которой шаблоны играют ключевую роль в формировании внешнего вида сайта. Разработчики и верстальщики часто сталкиваются с необходимостью определить, какой именно файл шаблона используется для отображения той или иной страницы или её части. Знание пути к шаблону помогает быстро вносить правки, отлаживать вёрстку, подключать дополнительные ресурсы и создавать инструменты для разработки.

В этом руководстве подробно рассматриваются три практических способа получения пути и имени файла шаблона:

1. Функция cot_tpl_url() — формирует абсолютный URL к файлу шаблона по его имени, переданному вручную.
2. Функция cot_debug_tpl_url() — автоматически определяет текущий шаблон, анализируя стек вызовов PHP.
3. Присваивание пути через $t->assign() — передача пути из PHP-кода расширения в шаблон через механизм XTemplate.

Каждый метод имеет свои особенности, преимущества и ограничения. Руководство поможет выбрать подходящий вариант для конкретной задачи, а также объяснит, как правильно разместить пользовательские функции в файле system/functions.custom.php, чтобы они были доступны во всей системе.

Важно: В примерах мы будем показывать путь к шаблону в виде текста, а не как кликабельную ссылку. Файл .tpl не предназначен для открытия в браузере напрямую: он содержит HTML-разметку с тегами XTemplate, которая требует обработки движком. Поэтому ссылка на такой файл бесполезна и вводит в заблуждение. Путь следует выводить для информации, например, при отладке или документировании.

Глава 1. Архитектура шаблонов Cotonti

Прежде чем перейти к методам получения пути, необходимо понимать базовые принципы работы с шаблонами в Cotonti.

1.1. Функция cot_tplfile()

Центральной функцией для определения пути к файлу шаблона является cot_tplfile(). Она объявлена в файле system/functions.php и имеет следующую сигнатуру:

function cot_tplfile($base, $type = 'module', $admin = null)

Параметры:

• $base – строка или массив, задающая имя шаблона. Если строка содержит точку, она разбивается на части. Например, 'forums.editpost' превратится в массив ['forums', 'editpost'].
• $type – тип расширения: 'plug' (плагин), 'module' (модуль) или 'core' (ядро). По умолчанию 'module'.
• $admin – флаг, указывающий, нужно ли искать шаблон в админ-теме. Если null (по умолчанию), Cotonti автоматически определяет, является ли шаблон административным (по наличию admin в имени).

Что делает функция:

1. Нормализует переданное имя шаблона в массив частей.
2. Определяет код расширения (первый элемент массива) и остальные части.
3. В зависимости от типа расширения и флага $admin строит список директорий для поиска:
   • Текущая тема пользователя (может быть переопределена).
   • Админ-тема (для админ-шаблонов).
   • Папка модуля/плагина (fallback).
4. Проходит по списку директорий и ищет файл, имя которого образуется из частей $base, соединённых точками, с добавлением расширения .tpl. Например, для ['forums', 'editpost'] будет искаться forums.editpost.tpl.
5. Возвращает относительный путь к найденному файлу (например, themes/mytheme/modules/forums/editpost.tpl) или null, если файл не найден.

Примеры вызовов:

$tpl = cot_tplfile('index');                     // -> themes/.../index.tpl
$tpl = cot_tplfile('page.add');                  // -> themes/.../page.add.tpl
$tpl = cot_tplfile(['users', 'edit', '5'], 'module');
$tpl = cot_tplfile('myplugin.admin', 'plug', true);

Обратите внимание: функция возвращает путь относительно корня сайта, без ведущего слэша и без базового URL. Для использования в HTML (например, в атрибуте href или src) требуется преобразовать его в абсолютный URL.

1.2. Класс XTemplate и его роль

После определения пути к файлу шаблона создаётся объект класса XTemplate, который отвечает за парсинг и отображение шаблона:

$t = new XTemplate($tpl_file);

Класс XTemplate (расширение Cotonti) хранит внутри себя путь к файлу шаблона. Именно это используется во втором методе (cot_debug_tpl_url) для получения текущего шаблона. В разных версиях свойство, хранящее путь, может называться по-разному: filename, file, tpl_name и т.д. Поэтому в функции cot_debug_tpl_url() предусмотрен перебор возможных имён через Reflection API.

1.3. Базовый URL сайта $sys['abs_url']

Глобальная переменная $sys['abs_url'] содержит базовый URL сайта, например, https://example.com/. Обычно он заканчивается слэшем. Для корректного формирования абсолютного URL нужно объединить базовый URL и относительный путь, избегая дублирования слэшей. В наших функциях мы используем rtrim($absUrl, '/') и ltrim($filePath, '/').

Глава 2. Метод 1: Функция cot_tpl_url() – получение URL шаблона по имени

2.1. Назначение и принцип работы

Функция cot_tpl_url() является удобной обёрткой над cot_tplfile(). Она принимает те же аргументы, что и cot_tplfile(), но возвращает не относительный путь, а полный абсолютный URL к файлу шаблона. Это полезно, когда разработчик точно знает, какой шаблон ему нужен, и хочет получить его адрес для отображения в тексте, сохранения в конфигурации или использования в качестве пути к ресурсам.

Функция:

1. Вызывает cot_tplfile($base, $type, $admin) для поиска файла.
2. Если файл не найден, возвращает null.
3. Получает базовый URL из $sys['abs_url'] (или вычисляет его из $_SERVER, если переменная не задана).
4. Объединяет базовый URL и путь, убирая лишние слэши.
5. Возвращает готовую строку вида https://example.com/themes/mytheme/modules/page/page.news.tpl.

2.2. Параметры функции

function cot_tpl_url($base, $type = 'module', $admin = null)

• $base — имя шаблона (строка с точками или массив частей). Например, 'page.news' или ['page', 'news'].
• $type — тип расширения: 'plug', 'module', 'core'.
• $admin — если true, будет искать в админ-теме; если null, автоопределение по имени.

2.3. Примеры вызова в шаблонах

Внутри любого .tpl-файла можно вызвать функцию через тег {PHP|...} и вывести результат текстом:

<!-- Показать URL шаблона страницы -->
<p>Шаблон страницы: {PHP|cot_tpl_url('page')}</p>

<!-- Показать URL шаблона конкретной категории -->
<p>Шаблон категории "Новости": {PHP|cot_tpl_url(['page', 'news'])}</p>

<!-- Для плагина -->
<p>Шаблон плагина recentitems: {PHP|cot_tpl_url('recentitems', 'plug')}</p>

Также функцию можно вызывать в PHP-коде расширения:

$url = cot_tpl_url('forums.editpost');
echo "Путь к шаблону: " . $url;

Не рекомендуется делать ссылку вида <a href="{PHP|cot_tpl_url('page')}">Открыть</a>, потому что браузер не сможет корректно открыть .tpl-файл. Вместо этого используйте вывод пути в текстовом виде или в атрибуте title/data-* для хранения.

Правильный синтаксис:

   Вызов функции (через pipe, — знак вертикальной черты | )): {PHP|имя_функции(аргументы)}
   Пример вызова в шаблоне: {PHP|cot_debug_tpl_url()}

   Доступ к глобальной переменной PHP (через точку): {PHP.имя_переменной}
   Пример получения в шаблоне: {PHP.sys.abs_url} (для $sys['abs_url'])

   Переменная шаблона: {ИМЯ_ПЕРЕМЕННОЙ}
   Пример записи в шаблоне: {TPL_DIR}

2.4. Когда использовать

Этот метод идеально подходит, когда:

• Имя шаблона известно заранее и не зависит от текущего контекста.
• Нужно получить URL конкретного файла для подключения ресурсов (например, CSS-файла, лежащего рядом с шаблоном).
• Создаётся панель администратора, где нужно показать путь к шаблону для редактирования (например, скопировать путь и открыть файл в FTP или файловом менеджере).

Пример: В админ-панели Cotonti можно вывести список файлов шаблонов с их абсолютными путями, чтобы администратор мог легко найти нужный файл на сервере.

2.5. Ограничения и особенности

• Требует ручного указания имени шаблона. Если имя неизвестно или определяется динамически, придётся вычислять его самостоятельно.
• Не определяет текущий шаблон автоматически. Если вам нужно узнать, какой шаблон используется для текущей страницы, этот метод не подойдёт.
• Зависит от корректности поиска cot_tplfile(). Если файл не найден (например, из-за опечатки), функция вернёт null.

Глава 3. Метод 2: Функция cot_debug_tpl_url() – автоматическое определение текущего шаблона

3.1. Назначение

Функция cot_debug_tpl_url() решает задачу определения текущего шаблона, в котором она вызывается. Это особенно полезно при отладке: вы вставляете вызов функции в любое место .tpl-файла (например, в футер) и видите полный URL этого файла, не зная заранее его имя.

Такой подход не требует правки ядра и не зависит от конкретного модуля или плагина.

3.2. Как это работает: debug_backtrace() и Reflection API

Функция использует две важные возможности PHP:

1. debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT) – возвращает стек вызовов в виде массива. Благодаря флагу DEBUG_BACKTRACE_PROVIDE_OBJECT, каждый кадр содержит ключ object, если вызов произошёл внутри метода какого-либо объекта. В нашем случае, когда функция cot_debug_tpl_url() вызывается внутри шаблона, она выполняется в контексте метода класса XTemplate (например, parse() или text()). Поэтому в стеке обязательно будет кадр с объектом XTemplate.
2. Reflection API – позволяет получить доступ к защищённым и приватным свойствам объекта. Путь к файлу шаблона хранится в приватном свойстве объекта XTemplate. Через ReflectionObject мы перебираем возможные имена свойств (filename, file, tpl_name, template) и извлекаем значение.

Алгоритм:

• Получаем базовый URL.
• Получаем стек вызовов.
• Ищем в стеке кадр с объектом XTemplate.
• Извлекаем из этого объекта путь к файлу шаблона (с помощью Reflection).
• Формируем абсолютный URL и возвращаем его.

3.3. Примеры использования

В любом .tpl-файле:

<!-- Вывод текущего шаблона текстом -->
<div>Текущий шаблон: {PHP|cot_debug_tpl_url()}</div>

<!-- Использовать в атрибуте data-* для JavaScript -->
<body data-tpl="{PHP|cot_debug_tpl_url()}">

Для отладки часто вставляют этот вызов в footer.tpl или header.tpl, чтобы на каждой странице видеть, какой шаблон загружен. Не делайте из этого ссылку – это просто текст.

3.4. Когда использовать

• При разработке и отладке – когда нужно быстро понять, какой файл шаблона отвечает за текущий блок страницы.
• При создании инструментов для разработчиков – например, панели, которая подсвечивает имя шаблона.
• Когда имя шаблона неизвестно или определяется динамически (например, в зависимости от категории или пользователя).

3.5. Ограничения и рекомендации

• Производительность. Функция использует debug_backtrace(), что может замедлить выполнение при частых вызовах. Не рекомендуется вызывать её в цикле на боевом сайте. Используйте только для отладки или в админ-режиме.
• Зависимость от внутренней структуры XTemplate. Если в будущем свойство, хранящее путь, переименуют, функция может перестать работать. Поэтому в ней предусмотрен резервный перебор всех свойств с подстроками file или tpl.
• Точность. Функция возвращает последний найденный в стеке объект XTemplate, который обычно соответствует текущему обрабатываемому шаблону. Однако в некоторых случаях (например, вложенные шаблоны) может вернуть не тот, что ожидается. Для большинства задач отладки этого достаточно.

Глава 4. Метод 3: Присваивание пути в тег шаблона через $t->assign()

4.1. Назначение

Этот метод используется разработчиками расширений (модулей, плагинов), когда путь к шаблону уже получен в PHP-коде для создания объекта XTemplate. Вместо того чтобы в шаблоне вызывать какие-либо функции, мы передаём путь как обычную переменную шаблона. Это самый явный и контролируемый способ.

4.2. Пример реализации в PHP-коде

Рассмотрим фрагмент из реального модуля market:

// 1. Определяем составные части имени шаблона
$tpl_ExtCode = 'market';          // код модуля
$tpl_PartExt = 'edit';            // часть шаблона (действие)
$tpl_PartExtSecond = Cot::$structure['market'][$item['fieldmrkt_cat']]['tpl']; // доп. часть из структуры

// 2. Получаем путь к файлу шаблона
$extTplFile = cot_tplfile(
    [
        $tpl_ExtCode,
        $tpl_PartExt,
        $tpl_PartExtSecond
    ],
    'module',
    true
);

// 3. Проверяем, найден ли файл
if (empty($extTplFile)) {
    cot_error('Шаблон не найден');
}

// 4. Сохраняем путь в переменную
$tpl_Path = $extTplFile;

// 5. Создаём объект XTemplate
$t = new XTemplate($extTplFile);

// ... дальнейшая обработка ...

// 6. Передаём путь в шаблон
$t->assign('TPL_PATH', $tpl_Path);

В результате в шаблоне появляется переменная {TPL_PATH}, содержащая относительный путь к файлу шаблона.

4.3. Вывод в шаблоне

В соответствующем .tpl-файле (например, market.edit.tpl) можно вывести путь:

<!-- Просто вывести путь -->
<p>Путь к шаблону: {TPL_PATH}</p>

<!-- Использовать в атрибуте data-* -->
<div class="debug-info" data-tpl="{TPL_PATH}">

Обратите внимание: {TPL_PATH} содержит относительный путь (без базового URL). Для получения абсолютного URL можно либо в PHP-коде сразу сформировать полный URL, либо в шаблоне использовать комбинацию {PHP$sys.abs_url}/{TPL_PATH}.

4.4. Когда использовать

• Внутри расширений, когда вы уже работаете с объектом XTemplate и хотите передать дополнительную информацию в шаблон.
• Для создания служебных шаблонов (например, админ-панели), где нужно выводить информацию о самом шаблоне.
• Когда требуется максимальный контроль над тем, что именно передаётся в шаблон, без дополнительных вычислений в шаблоне.

4.5. Преимущества и недостатки

Преимущества:

• Полная явность: вы сами определяете переменную и её значение.
• Не требует Reflection или backtrace, работает быстро.
• Можно передать не только путь, но и любые другие метаданные (имя, части и т.д.).
• Совместимо со всеми версиями PHP и Cotonti.

Недостатки:

• Требует изменения PHP-кода расширения для каждого шаблона, где это нужно.
• Не универсально: если вы хотите вставить информацию о шаблоне в общий footer.tpl, придётся в каждом PHP-контроллере передавать путь в соответствующий объект XTemplate.

Глава 5. Сравнение методов

Рекомендации:

• Если вы разрабатываете расширение и хотите показать путь к шаблону внутри него – используйте Метод 3 (assign).
• Если вам нужно быстро отладить текущую страницу и узнать, какой шаблон используется – используйте Метод 2 (cot_debug_tpl_url).
• Если вам нужно получить URL конкретного шаблона по имени (например, для отображения в документации или передачи в конфигурацию) – используйте Метод 1 (cot_tpl_url).

Глава 6. Практические сценарии и рекомендации

6.1. Отладка вёрстки

Задача: Верстальщик правит тему и хочет видеть, какой .tpl-файл отвечает за определённый блок страницы.

Решение: Вставьте в footer.tpl (или header.tpl) следующий код:

<div class="debug-tpl">
    Текущий шаблон: {PHP|cot_debug_tpl_url()}
</div>

Это позволит на любой странице сайта видеть путь к текущему шаблону. Не забудьте удалить или скрыть этот блок после завершения работ.

6.2. Подключение ресурсов шаблона

Задача: В шаблоне плагина recentitems.tpl нужно подключить CSS-файл, лежащий рядом с шаблоном в папке темы.

Решение с Методом 3 (предпочтительно): В PHP-коде получите URL папки с шаблоном и передайте в шаблон.

$tpl_dir = dirname(cot_tplfile('recentitems', 'plug'));
$t->assign('TPL_DIR', $tpl_dir);

В шаблоне:

<link rel="stylesheet" href="{PHP.sys.abs_url}/{TPL_DIR}/css/recentitems.css">

Использование cot_tpl_url() для таких целей менее надёжно, так как путь может быть динамическим.

Альтернативный вариант, при котором полный URL формируется в PHP-коде:

$tpl_dir = dirname(cot_tplfile('recentitems', 'plug'));
$t->assign('RECENTITEMS_CSS_URL', $sys['abs_url'] . $tpl_dir . '/css/recentitems.css');

В шаблоне:

<link rel="stylesheet" href="{RECENTITEMS_CSS_URL}">

6.3. Создание документации

Задача: На служебной странице нужно вывести список всех используемых шаблонов с их абсолютными путями (для копирования).

Решение: Используйте cot_tpl_url() для каждого известного шаблона:

$templates = [
    'index', 'page', 'page.list', 'forums.topics', 'users.profile'
];
foreach ($templates as $tpl_name) {
    $url = cot_tpl_url($tpl_name);
    echo "Шаблон $tpl_name: $url<br>";
}

6.4. Разработка расширений

Задача: В модуле market нужно в админ-части показывать путь к текущему редактируемому шаблону.

Решение: Используйте Метод 3, как показано в примере выше. В PHP-коде получаете путь через cot_tplfile(), сохраняете в переменную и передаёте в шаблон через $t->assign().

Дополнительный совет: Если вы хотите, чтобы переменная была доступна во всех шаблонах модуля, можно назначить её в начале контроллера и использовать в каждом подшаблоне.

Глава 7. Размещение функций в system/functions.custom.php

7.1. Что такое functions.custom.php

Cotonti предусматривает возможность добавления пользовательских функций без изменения ядра. Для этого используется файл system/functions.custom.php. Если такой файл существует, Cotonti автоматически загружает его при инициализации. Это позволяет разработчикам добавлять собственные функции, которые будут доступны во всей системе, включая шаблоны.

7.2. Подключение файла

Чтобы добавить функции cot_tpl_url() и cot_debug_tpl_url(), выполните следующие шаги:

1. Создайте файл system/functions.custom.php, если его ещё нет.
2. Откройте файл и добавьте в него код функций (приведён в Приложении A или C).
3. Сохраните файл.

Cotonti автоматически обнаружит этот файл и подключит его при запуске. Никаких дополнительных действий для подключения не требуется.

Важно: Не редактируйте файл system/functions.php напрямую, так как он будет перезаписан при обновлении Cotonti. Все пользовательские функции размещайте в functions.custom.php.

7.3. Рекомендации по организации

• Храните все пользовательские функции в одном файле functions.custom.php для удобства сопровождения.
• Используйте уникальные префиксы для имён функций, чтобы избежать конфликтов с ядром и расширениями.
• Добавляйте документацию к каждой функции (PHPDoc-комментарии) для облегчения понимания.
• Не забывайте проверять, определена ли функция, перед её объявлением (можно использовать if (!function_exists('...'))).

Пример структуры файла:

<?php
/**
 * Пользовательские функции Cotonti
 */

if (!function_exists('cot_tpl_url')) {
    function cot_tpl_url($base, $type = 'module', $admin = null) {
        // ...
    }
}

if (!function_exists('cot_debug_tpl_url')) {
    function cot_debug_tpl_url() {
        // ...
    }
}

Заключение

Cotonti предоставляет гибкую систему шаблонов, и получение пути к шаблону может быть выполнено разными способами в зависимости от контекста:

• cot_tpl_url() – для получения URL конкретного шаблона по имени.
• cot_debug_tpl_url() – для автоматического определения текущего шаблона (удобно при отладке).
• $t->assign() – для явной передачи пути в шаблон из PHP-кода расширения.

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

Размещение пользовательских функций в system/functions.custom.php гарантирует, что они не будут потеряны при обновлении движка и будут доступны повсеместно.

Приложение A. Полный листинг функций

A.1. cot_tpl_url()

/**
 * Возвращает абсолютный URL к файлу шаблона.
 *
 * Использует cot_tplfile() для поиска файла и добавляет к нему базовый URL сайта.
 *
 * @param string|array $base  Имя шаблона (как в cot_tplfile)
 * @param string       $type  Тип расширения: 'plug', 'module' или 'core'
 * @param bool|null    $admin Использовать файл из админ-темы (по умолчанию автоопределение)
 * @return string|null Абсолютный URL к шаблону или null, если файл не найден
 */
function cot_tpl_url($base, $type = 'module', $admin = null)
{
    // Получаем путь к файлу через стандартную функцию
    $filePath = cot_tplfile($base, $type, $admin);
    if ($filePath === null) {
        return null;
    }

    // Определяем базовый URL сайта
    global $sys;
    $absUrl = isset($sys['abs_url']) ? $sys['abs_url'] : '';

    if (empty($absUrl)) {
        // Если базовый URL не задан, вычисляем из $_SERVER
        $absUrl = 'http' . (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off' ? 's' : '') . '://' . $_SERVER['HTTP_HOST'] . rtrim(dirname($_SERVER['SCRIPT_NAME']), '/') . '/';
    }

    // Убираем лишние слэши
    if (preg_match('#^(/|[A-Za-z]:[\\\\/])#', $filePath)) {
        // Если путь абсолютный (начинается с '/' или 'C:\'), возвращаем null
        return null;
    }

    return rtrim($absUrl, '/') . '/' . ltrim($filePath, '/');
}

A.2. cot_debug_tpl_url()

/**
 * Возвращает абсолютный URL текущего файла шаблона.
 *
 * Функция анализирует стек вызовов, находит объект XTemplate,
 * который в данный момент обрабатывает шаблон, извлекает из него путь к файлу
 * шаблона через Reflection API и добавляет к нему базовый URL сайта.
 *
 * @return string|null Абсолютный URL текущего шаблона или null, если не удалось определить.
 */
function cot_debug_tpl_url()
{
    global $sys;

    // Базовый URL
    $absUrl = isset($sys['abs_url']) ? rtrim($sys['abs_url'], '/') : '';

    // Получаем стек вызовов с объектами
    $backtrace = debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT);

    foreach ($backtrace as $frame) {
        if (isset($frame['object']) && $frame['object'] instanceof XTemplate) {
            $tplFile = null;
            $ref = new ReflectionObject($frame['object']);

            // Перечень возможных имён свойства с путём к шаблону
            $candidateProperties = ['filename', 'file', 'tpl_name', 'template'];

            foreach ($candidateProperties as $propName) {
                if ($ref->hasProperty($propName)) {
                    $prop = $ref->getProperty($propName);
                    // В PHP 8.1+ setAccessible() не нужен
                    $tplFile = $prop->getValue($frame['object']);
                    break;
                }
            }

            // Запасной вариант: поиск свойства с 'file' или 'tpl' в имени
            if ($tplFile === null) {
                foreach ($ref->getProperties() as $prop) {
                    $name = $prop->getName();
                    if (stripos($name, 'file') !== false || stripos($name, 'tpl') !== false) {
                        $tplFile = $prop->getValue($frame['object']);
                        break;
                    }
                }
            }

            if (!empty($tplFile)) {
                return $absUrl . '/' . ltrim($tplFile, '/');
            }
        }
    }

    return null;
}

Приложение B. Примеры использования в разных модулях

Страница списка новостей (модуль page)

В файле page.list.tpl можно вставить:

<!-- Показать путь к текущему шаблону -->
<div class="debug">Шаблон: {PHP|cot_debug_tpl_url()}</div>

<!-- Показать URL шаблона "page.list" -->
<div>URL общего шаблона: {PHP|cot_tpl_url('page.list')}</div>

Форум – темы

В forums.topics.tpl:

<!-- Автоматический путь -->
<p>Текущий шаблон: {PHP|cot_debug_tpl_url()}</p>

Плагин комментариев

В PHP-коде плагина:

$tpl_path = cot_tplfile('comments', 'plug');
$t->assign('COMMENTS_TPL_PATH', $tpl_path);

В шаблоне:

<footer>Комментарии: {COMMENTS_TPL_PATH}</footer>

Для других модулей используйте соответствующие имена:

   forums.topics.tpl → {PHP|cot_tpl_url('forums.topics')}

   users.profile.tpl → {PHP|cot_tpl_url('users.profile')}

   polls.tpl → {PHP|cot_tpl_url('polls')}

Приложение C. Код для размещения в functions.custom.php

Ниже представлен полный код, который можно скопировать в файл system/functions.custom.php.

<?php
/**
 * Пользовательские функции Cotonti
 */

if (!function_exists('cot_tpl_url')) {
    /**
     * Возвращает абсолютный URL к файлу шаблона.
     *
     * @param string|array $base  Имя шаблона (как в cot_tplfile)
     * @param string       $type  Тип расширения: 'plug', 'module' или 'core'
     * @param bool|null    $admin Использовать файл из админ-темы (по умолчанию автоопределение)
     * @return string|null Абсолютный URL к шаблону или null, если файл не найден
     */
    function cot_tpl_url($base, $type = 'module', $admin = null)
    {
        // Получаем путь к файлу через стандартную функцию
        $filePath = cot_tplfile($base, $type, $admin);
        if ($filePath === null) {
            return null;
        }

        // Определяем базовый URL сайта
        global $sys;
        $absUrl = isset($sys['abs_url']) ? $sys['abs_url'] : '';

        if (empty($absUrl)) {
            // Если базовый URL не задан, вычисляем из $_SERVER
            $absUrl = 'http' . (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off' ? 's' : '') . '://' . $_SERVER['HTTP_HOST'] . rtrim(dirname($_SERVER['SCRIPT_NAME']), '/') . '/';
        }

        // Убираем лишние слэши
        if (preg_match('#^(/|[A-Za-z]:[\\\\/])#', $filePath)) {
            // Если путь абсолютный (начинается с '/' или 'C:\'), возвращаем null
            return null;
        }

        return rtrim($absUrl, '/') . '/' . ltrim($filePath, '/');
    }
}

if (!function_exists('cot_debug_tpl_url')) {
    /**
     * Возвращает абсолютный URL текущего файла шаблона.
     *
     * @return string|null Абсолютный URL текущего шаблона или null, если не удалось определить.
     */
    function cot_debug_tpl_url()
    {
        global $sys;

        // Базовый URL
        $absUrl = isset($sys['abs_url']) ? rtrim($sys['abs_url'], '/') : '';

        // Получаем стек вызовов с объектами
        $backtrace = debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT);

        foreach ($backtrace as $frame) {
            if (isset($frame['object']) && $frame['object'] instanceof XTemplate) {
                $tplFile = null;
                $ref = new ReflectionObject($frame['object']);

                // Перечень возможных имён свойства с путём к шаблону
                $candidateProperties = ['filename', 'file', 'tpl_name', 'template'];

                foreach ($candidateProperties as $propName) {
                    if ($ref->hasProperty($propName)) {
                        $prop = $ref->getProperty($propName);
                        // В PHP 8.1+ setAccessible() не нужен
                        $tplFile = $prop->getValue($frame['object']);
                        break;
                    }
                }

                // Запасной вариант: поиск свойства с 'file' или 'tpl' в имени
                if ($tplFile === null) {
                    foreach ($ref->getProperties() as $prop) {
                        $name = $prop->getName();
                        if (stripos($name, 'file') !== false || stripos($name, 'tpl') !== false) {
                            $tplFile = $prop->getValue($frame['object']);
                            break;
                        }
                    }
                }

                if (!empty($tplFile)) {
                    return $absUrl . '/' . ltrim($tplFile, '/');
                }
            }
        }

        return null;
    }
}

После сохранения файла функции станут доступны во всех частях Cotonti, включая шаблоны.

Надеемся, данное руководство поможет вам эффективно работать с шаблонами Cotonti. Используйте предложенные методы в зависимости от ваших задач.