Функция cot_tplfile в Cotonti

предназначена для определения пути к файлу шаблона в зависимости от темы, расширения и типа использования (модуль, плагин или ядро). Она помогает разработчикам фреймворка Cotonti динамически находить и использовать правильные файлы шаблонов.

Опубликовано в: Cotonti - чтиво. Документация.

Назначение функции cot_tplfile и ее описание.

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

/**
 * Returns path to a template file. The default search order is:
 * 1) Current theme folder (plugins/ subdir for plugins, admin/ subdir for admin)
 * 2) Default theme folder (if current is not default)
 * 3) tpl subdir in module/plugin folder (fallback template)
 *
 * @param mixed $base Item name (string), or base names (array)
 * @param string $type Extension type: 'plug', 'module' or 'core'
 * @param bool $admin Use admin theme file if present. Tries to determine from base string by default.
 * @return ?string
 */
function cot_tplfile($base, $type = 'module', $admin = null)
{
    // Class Cot may be not initialized yet
    global $cfg, $usr;

    // Get base name parts
    if (is_string($base) && mb_strpos($base, '.') !== false) {
        $base = explode('.', $base);
    }

    if (!is_array($base)) {
        $base = [$base];
    }

    $extensionCode = $base[0];
    $baseParts = [];
    if (mb_strpos($extensionCode, '.') !== false) {
        $baseParts = explode('.', $extensionCode);
        $extensionCode = $baseParts[0];
    }

    if (is_null($admin)) {
        $admin = ($extensionCode === 'admin')
            || (isset($base[1]) && $base[1] === 'admin')
            || (isset($baseParts[1]) && $baseParts[1] === 'admin');
    }

    $directoriesToScan = [];
    $themesDir = $cfg['themes_dir'];
    $theme = !empty($usr['theme']) ? $usr['theme'] : '';
    $adminTheme = !empty($cfg['admintheme']) ? $cfg['admintheme'] : '';
    // Possible search directories depending on extension type
    if ($type === 'plug') {
        // Plugin template paths
        if ($admin) {
            if ($adminTheme !== '') {
                $directoriesToScan[] = "{$themesDir}/admin/{$adminTheme}/plugins/{$extensionCode}/";
                $directoriesToScan[] = "{$themesDir}/admin/{$adminTheme}/plugins/";
            }
            $directoriesToScan[] = "{$themesDir}/{$theme}/admin/plugins/{$extensionCode}/";
            $directoriesToScan[] = "{$themesDir}/{$theme}/admin/plugins/";
        }
        $directoriesToScan[] = "{$themesDir}/{$theme}/plugins/{$extensionCode}/";
        $directoriesToScan[] = "{$themesDir}/{$theme}/plugins/";
        $directoriesToScan[] = $cfg['plugins_dir'] . "/{$extensionCode}/tpl/";

    } elseif ($type === 'core' && in_array($extensionCode, ['admin', 'header', 'footer', 'message'])) {
        // Built-in core modules
        if ($adminTheme !== '') {
            $directoriesToScan[] = "{$themesDir}/admin/{$adminTheme}/";
        }
        if ($theme !== '') {
            $directoriesToScan[] = "{$themesDir}/{$theme}/admin/";
        }
        $directoriesToScan[] = $cfg['system_dir'] . '/admin/tpl/';

    } else {
        // Module template paths
        if ($admin) {
            if ($adminTheme !== '') {
                $directoriesToScan[] = "{$themesDir}/admin/{$adminTheme}/modules/{$extensionCode}/";
                $directoriesToScan[] = "{$themesDir}/admin/{$adminTheme}/modules/";
            }
            $directoriesToScan[] = "{$themesDir}/{$theme}/admin/modules/{$extensionCode}/";
            $directoriesToScan[] = "{$themesDir}/{$theme}/admin/modules/";
        }
        $directoriesToScan[] = "{$themesDir}/{$theme}/modules/{$extensionCode}/";
        $directoriesToScan[] = "{$themesDir}/{$theme}/modules/";
        $directoriesToScan[] = "{$themesDir}/{$theme}/";
        $directoriesToScan[] = $cfg['modules_dir'] . "/{$extensionCode}/tpl/";
    }

    // Build template file name from base parts glued with dots
    $baseDepth = count($base);
    for ($i = $baseDepth; $i > 0; $i--) {
        $levels = array_slice($base, 0, $i);
        $themeFileName = implode('.', $levels) . '.tpl';

        // Search in all available directories
        foreach ($directoriesToScan as $dir) {
            $themeFile = $dir . $themeFileName;
            if (file_exists($themeFile)) {
                return $themeFile;
            }
        }
    }

    return null;
}

Разбор и комментарии к функции cot_tplfile

Описание параметров функции:

1. $base (строка или массив)

Название базового элемента (например, название плагина, модуля или ядра).
Пример: 'gallery' для плагина или 'page.list' для модуля.
Может быть строкой или массивом частей имени, например: ['page', 'list'].

2. $type (строка, по умолчанию 'module')

Тип расширения, для которого ищется шаблон. Возможные значения:

'plug': для плагинов.
'module': для модулей.
'core': для ядра фреймворка.
$admin (логическое, по умолчанию null)
Указывает, искать ли шаблоны для административной части. Если null, значение определяется автоматически исходя из $base.

Детальный разбор тела функции
Разделение базового имени на части

if (is_string($base) && mb_strpos($base, '.') !== false) {
    $base = explode('.', $base);
}

Если $base содержит точку (.), строка разбивается на массив частей, чтобы поддерживать вложенные шаблоны, например 'page.list'.

Преобразование $base в массив

if (!is_array($base)) {
    $base = [$base];
}

Если $base передан как строка, он преобразуется в массив для унификации обработки.

Определение административного режима

if (is_null($admin)) {
    $admin = ($extensionCode === 'admin')
        || (isset($base[1]) && $base[1] === 'admin')
        || (isset($baseParts[1]) && $baseParts[1] === 'admin');
}

Автоматически определяет, является ли шаблон административным, если $admin не указан. Проверяется, содержит ли имя части 'admin'.

Формирование списка директорий для поиска
В зависимости от типа расширения (plug, module, core) добавляются пути в массив $directoriesToScan.

Пример для плагинов:

if ($type === 'plug') {
    $directoriesToScan[] = "{$themesDir}/{$theme}/plugins/{$extensionCode}/";
    $directoriesToScan[] = $cfg['plugins_dir'] . "/{$extensionCode}/tpl/";
}

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

$baseDepth = count($base);
for ($i = $baseDepth; $i > 0; $i--) {
    $levels = array_slice($base, 0, $i);
    $themeFileName = implode('.', $levels) . '.tpl';

    foreach ($directoriesToScan as $dir) {
        $themeFile = $dir . $themeFileName;
        if (file_exists($themeFile)) {
            return $themeFile;
        }
    }
}

Формирует возможные пути к шаблону, проверяя все директории из $directoriesToScan.
Шаблон создаётся из частей $base (например, 'page.list.tpl').

Возврат результата

Если файл найден, возвращается его полный путь. Если нет — возвращается null.

Назначение функции

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

Применение в контексте Cotonti

Пример использования:

$template = cot_tplfile('page.list', 'module');
if ($template) {
    include $template;
}

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

Используйте для всех файлов шаблонов. Это позволяет избегать жёстко заданных путей в коде.
Учитывайте административный режим. Передавайте $admin = true для шаблонов, используемых в панели администратора.
Оптимизируйте директории тем. Убедитесь, что структуры директорий и имена файлов шаблонов соответствуют логике функции.
Не допускайте отсутствия fallback-шаблонов. В случае отсутствия файла функция вернёт null, что может вызвать ошибку.

Описание функции
Функция cot_tplfile — мощный инструмент для поиска и подключения файлов шаблонов в Cotonti, поддерживающий различные темы, плагины, модули и режимы работы.

В контексте функции cot_tplfile фреймворка Cotonti проанализируем код ниже:

$templateFile = cot_tplfile('login', 'core');
if (empty($templateFile) || !is_readable($templateFile)) {
    $templateFile = cot_tplfile('users.auth', 'module');
}
if (empty($templateFile) || !is_readable($templateFile)) {
    cot_die_message(500, true, 'Template file not found');
}

$t = new XTemplate($templateFile);

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

Код

$templateFile = cot_tplfile('login', 'core');

Разбор:
Функция cot_tplfile
Здесь вызывается cot_tplfile для поиска файла шаблона с базовым именем 'login' и типом 'core'.

'login' — это базовое имя шаблона. Оно может указывать на файл шаблона, связанный с процессом авторизации.
'core' — тип шаблона, который говорит функции искать файл в директориях ядра.

Результат

Если файл найден, переменная $templateFile содержит полный путь к файлу.
Если файл не найден, функция возвращает null.

if (empty($templateFile) || !is_readable($templateFile)) {
    $templateFile = cot_tplfile('users.auth', 'module');
}

Разбор:
Проверка результата

empty($templateFile) — проверяет, был ли найден файл шаблона.
!is_readable($templateFile) — проверяет, доступен ли файл для чтения (например, если у файла недостаточно прав доступа).

Фallback (резервный вариант)

Если файл шаблона 'login' не найден или недоступен, выполняется повторный вызов cot_tplfile для поиска шаблона с именем 'users.auth' и типом 'module'.

'users.auth' может относиться к модулю, отвечающему за авторизацию пользователей.
'module' указывает функции искать файл шаблона в директориях модулей.

if (empty($templateFile) || !is_readable($templateFile)) {
    cot_die_message(500, true, 'Template file not found');
}

Разбор:
Окончательная проверка
Выполняется повторная проверка переменной $templateFile:

Если она пуста или недоступна для чтения, выполнение скрипта завершается с ошибкой.
Функция cot_die_message

Генерирует HTTP-ответ с кодом ошибки 500 (внутренняя ошибка сервера).
Аргумент 'Template file not found' содержит сообщение об ошибке, которое может быть выведено пользователю или записано в лог.

$t = new XTemplate($templateFile);

Разбор:
Создание объекта шаблонизатора
Создаётся новый объект класса XTemplate, который отвечает за работу с шаблонами.

$templateFile передаётся в конструктор класса, чтобы шаблонизатор знал, какой файл использовать.

Назначение
Объект $t используется для дальнейшей обработки шаблона: заполнения данных, парсинга и вывода.

Полный разбор логики

Шаг 1: Попытка найти и загрузить основной шаблон 'login' из ядра.
Шаг 2: Если основной шаблон не найден или недоступен, используется резервный шаблон 'users.auth' из модуля.
Шаг 3: Если оба варианта не удаются, возвращается ошибка 500 с сообщением "Template file not found".
Шаг 4: Если шаблон найден, создаётся объект XTemplate для дальнейшей работы с ним.

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

Комментарии для новичков:
Использование cot_tplfile
Функция позволяет абстрагироваться от жёстко заданных путей к шаблонам, что делает код гибким и удобным для работы с разными темами.

Fallback-логика
Обеспечивает надёжность: если основной шаблон отсутствует, используется резервный.

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

Работа с шаблонизатором XTemplate
После выбора шаблона создаётся объект для работы с ним. Это стандартный подход в Cotonti.

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

Добавляйте fallback-шаблоны
Обязательно создавайте резервные шаблоны, чтобы минимизировать вероятность ошибок.

Логируйте ошибки
Вместо вывода сообщения об ошибке можно логировать проблему для последующего анализа.

Еще пример применения функции в Cotonti:

Подробное объяснение.

Переменная $mskin

$mskin = cot_tplfile(array('forums', 'topics', Cot::$structure['forums'][$s]['tpl']));

Вызывается функция cot_tplfile, которая ищет файл шаблона.

Параметры функции в данном контексте функции, которая внутри переменной `$mskin`

'forums' — код расширения (в данном случае, модуль форумов).
'topics' — базовое имя шаблона (вероятно, страницы, отображающей список тем в форуме).
Cot::$structure['forums'][$s]['tpl'] — пользовательская схема (шаблон), указанная в структуре для конкретной категории $s.

Результат работы cot_tplfile

Возвращает путь к файлу шаблона. Если файл не найден, возвращает null.

Класс `XTemplate`

$t = new XTemplate($mskin);

Создание объекта XTemplate
Новый объект класса XTemplate создаётся для работы с найденным файлом шаблона $mskin.

Аргумент `$mskin`

Если $mskin содержит путь к шаблону, XTemplate загружает этот шаблон. В противном случае (например, если $mskin равно null), произойдёт ошибка, так как XTemplate ожидает корректный путь.

Полный анализ логики

Поиск шаблона:

Функция cot_tplfile ищет файл шаблона в следующем порядке:
В текущей теме (например, /themes/ваша_тема/modules/forums/).
В директории модуля (например, /modules/forums/tpl/).

Параметр Cot::$structure['forums'][$s]['tpl'] позволяет указать пользовательский шаблон, заданный в структуре форума (для категории $s).

Загрузка шаблона:

Если файл шаблона найден, его путь сохраняется в $mskin, и объект XTemplate используется для работы с ним.

Ошибки:

Если шаблон не найден, переменная $mskin будет равна null, что вызовет ошибку при создании объекта XTemplate.

Назначение этого кода

Код загружает шаблон, который используется для отображения списка тем в выбранной категории форума. Если для категории указана пользовательская схема (tpl), она будет использована. Это позволяет легко настраивать внешний вид для отдельных разделов форума.

Пояснения для новичков:

cot_tplfile с массивом:

Первый элемент массива — это код модуля (например, 'forums').
Второй элемент — это базовое имя шаблона ('topics').
Третий элемент (если указан) — это конкретный шаблон, заданный в структуре - Cot::$structure:

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

Класс XTemplate:

Этот класс обрабатывает шаблон, позволяя вставлять в него данные и парсить готовую страницу.

Пример использования в Cotonti:
Шаблоны категорий форума:
Для каждой категории форума можно задать уникальный шаблон, указав его в настройках структуры. Это позволяет гибко настраивать внешний вид для разных разделов форума.

Fallback (резервный вариант):
Если пользовательский шаблон отсутствует, cot_tplfile автоматически попытается загрузить стандартный.

Рекомендации:
Проверяйте $mskin перед созданием объекта XTemplate:
Убедитесь, что файл шаблона найден, чтобы избежать ошибок.

if (empty($mskin) || !is_readable($mskin)) {
    cot_die_message(500, true, 'Template not found');
}

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

Логируйте ошибки:
Если шаблон не найден, запишите это в лог для упрощения отладки.

9 минут чтения Administrator

Комментарии (0)

Комментарии отсутствуют

Добавление комментариев доступно только зарегистрированным пользователям

Автор контента

Оффлайн

Administrator

Последняя авторизация: 05.07.2026 18:32

Страница размещена: 22.01.2025 14:50
Последнее обновление: 22.01.2025 15:16

Похожих страниц не найдено

Справка и поддержка

Статьи и блоги

Функция cot_tplfile в Cotonti

Назначение функции cot_tplfile и ее описание.

Переменная $mskin

Параметры функции в данном контексте функции, которая внутри переменной `$mskin`

Результат работы cot_tplfile

Класс `XTemplate`

Аргумент `$mskin`

Полный анализ логики

Поиск шаблона:

Загрузка шаблона:

Назначение этого кода

Комментарии (0)

Автор контента

Administrator

Справка и поддержка

Статьи и блоги

Функция cot_tplfile в Cotonti

Назначение функции cot_tplfile и ее описание.

Переменная $mskin

Параметры функции в данном контексте функции, которая внутри переменной $mskin

Результат работы cot_tplfile

Класс XTemplate

Аргумент $mskin

Полный анализ логики

Поиск шаблона:

Загрузка шаблона:

Назначение этого кода

Комментарии (0)

Автор контента

Administrator

Параметры функции в данном контексте функции, которая внутри переменной `$mskin`

Класс `XTemplate`

Аргумент `$mskin`