Метод out() в Cotonti

Метод out() отвечает за вывод обработанного блока шаблона и отладочной информации, если она включена. В начале метода проверяется, активирован ли режим отладки (self::$debugMode) и вывод отладочной информации (self::$debugOutput). Если оба условия выполняются, выводится отладочная информация о текущем файле шаблона. Для этого используется функция basename($this->filename), чтобы извлечь имя файла шаблона. Затем выводится заголовок <h1> с именем файла, после чего начинается перебор данных отладки для этого файла. Каждая секция отладочной информации соответствует определенному блоку шаблона. Имя блока выводится как заголовок второго уровня (<h2>), а теги внутри блока отображаются в виде списка <ul>, где каждый тег выводится с его значением. Если значение тега — это массив, то выводятся вложенные элементы. Для этого используется дополнительный цикл, который выводит каждое вложенное значение с добавлением ключа родительского тега. Если режим отладки не включен, то выполняется другой блок кода, который выводит непосредственно содержимое блока шаблона через метод text(). Этот метод генерирует строку с содержимым указанного блока шаблона. В конце метода возвращается сам объект XTemplate, что позволяет использовать цепочку вызовов.

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

1. Что такое блок в Cotonti?

Прежде чем понять, как работает метод out(), важно понимать, что такое блок в контексте Cotonti. Блоки в шаблонах — это части HTML-кода или логики, которые могут быть заменены или обработаны динамически. В шаблоне можно определить несколько блоков, например:

• MAIN — основной контент страницы,
• HEADER — шапка,
• FOOTER — подвал.

Каждый из этих блоков может быть заполнен данными, изменён, или заменён на основе условий, прописанных в шаблоне.

2. Что делает метод out()?

Метод out() отвечает за вывод содержимого одного из блоков шаблона на экран. В Cotonti блоки обычно обрабатываются динамически, заменяя или заполняя места в шаблоне в зависимости от данных, переданных в шаблон (через метод assign()).

Основная задача метода:

• Вывести содержимое блока.
• Показать отладочную информацию, если включен режим отладки.

3. Подробное объяснение метода

Вот как работает метод out():

Метод out() в этом коде отвечает за вывод содержимого блока шаблона, а также за вывод отладочной информации, если включен режим отладки. Давайте подробно прокомментируем каждую строку:

/**
 * Prints a parsed block
 *
 * @param string $block Block name
 * @return XTemplate $this object for call chaining
 */

Комментарий описывает назначение метода: он выводит обработанный блок шаблона. Параметр $block указывает имя блока, который нужно вывести. Возвращаемое значение — объект типа XTemplate, что позволяет использовать цепочку вызовов.

public function out($block = 'MAIN')

Это определение метода out(), который принимает один параметр $block, по умолчанию равный 'MAIN'. Этот параметр указывает на имя блока, который нужно вывести.

if (self::$debugMode && self::$debugOutput) {

Здесь проверяется, включены ли режим отладки и вывод отладочной информации. Если оба флага (переменные класса self::$debugMode и self::$debugOutput) установлены в true, то выполняется код для вывода отладочной информации.

$file = basename($this->filename);

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

echo "<h1>$file</h1>";

Выводим имя файла шаблона в виде заголовка <h1>. Это необходимо для того, чтобы в отладочной информации было видно, для какого файла выводятся данные.

foreach (self::$debugData[$file] as $block => $tags) {

Перебираем все отладочные данные для текущего файла (self::$debugData[$file]). Для каждого блока шаблона из этих данных перебираются его теги.

$block_name = $file . ' / ' . str_replace('.', ' / ', $block);

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

echo "<h2>$block_name</h2>";

Выводим название блока как заголовок второго уровня <h2>, чтобы выделить его в отладочной информации.

echo "<ul>";

Начинаем вывод списка, в котором будут перечисляться теги внутри блока.

foreach ($tags as $key => $val) {

Перебираем все теги внутри блока. Каждый тег представлен ключом $key и значением $val.

if (is_array($val)) {

Проверяем, является ли значение тега массивом. Если да, то это значит, что тег содержит вложенные данные.

foreach ($val as $key2 => $val2) {

Если значение является массивом, то перебираем вложенные данные. Здесь $key2 — это ключ вложенного элемента, а $val2 — его значение.

echo self::debugVar($key . '.' . $key2, $val2);

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

} else {

Если значение тега не является массивом, переходим к следующей части.

echo self::debugVar($key, $val);

Выводим отладочную информацию для простого тега, если его значение не является массивом.

}

Закрываем условие, проверяющее, является ли значение массива.

echo "</ul>";

Закрываем список HTML, который содержал теги и их значения.

}

Закрываем цикл, перебирающий все теги в блоке.

} else {

Если режим отладки не включен, то выполняется следующий блок кода.

echo $this->text($block);

Выводим обработанный контент блока. Метод text() генерирует и возвращает строку, представляющую содержимое указанного блока шаблона (в данном случае блока с именем $block).

}

Закрываем условие, проверяющее, включен ли режим отладки.

return $this;

Возвращаем объект XTemplate для возможности вызова других методов цепочкой. Это позволяет, например, продолжать работу с объектом после вызова метода out().

Таким образом, метод out() в Cotonti выполняет две основные функции: выводит содержимое блока шаблона и, в случае включенного режима отладки, выводит подробную информацию о данных, используемых в шаблоне.

/**
 * Печатает обработанный блок
 *
 * @param string $block Имя блока
 * @return XTemplate $this Объект для цепочки вызовов
 */
public function out($block = 'MAIN')
{
    // Проверяем, включен ли режим отладки и нужно ли выводить отладочную информацию
    if (self::$debugMode && self::$debugOutput) {
        // Выводим информацию для отладки по текущему файлу
        $file = basename($this->filename); // Извлекаем имя файла шаблона
        echo "<h1>$file</h1>"; // Выводим заголовок с именем файла

        // Перебираем отладочные данные для данного файла
        foreach (self::$debugData[$file] as $block => $tags) {
            // Формируем имя блока, заменяя точки на слэши
            $block_name = $file . ' / ' . str_replace('.', ' / ', $block);
            echo "<h2>$block_name</h2>"; // Выводим имя блока в заголовке второго уровня
            echo "<ul>"; // Открываем список

            // Перебираем теги и их значения для блока
            foreach ($tags as $key => $val) {
                // Если значение тега — это массив
                if (is_array($val)) {
                    // Поддерживаем один уровень вложенности
                    foreach ($val as $key2 => $val2) {
                        // Выводим каждый вложенный элемент с его ключом
                        echo self::debugVar($key . '.' . $key2, $val2);
                    }
                } else {
                    // Если значение не массив, выводим его сразу
                    echo self::debugVar($key, $val);
                }
            }
            echo "</ul>"; // Закрываем список
        }
    } else {
        // Если режим отладки не включен, выводим содержимое блока
        echo $this->text($block);
    }

    // Возвращаем текущий объект для цепочки вызовов
    return $this;
}

4. Детальный разбор работы метода

4.1. Отладочный режим

Первая часть метода отвечает за вывод отладочной информации, если включен режим отладки.

if (self::$debugMode && self::$debugOutput) {

• self::$debugMode — это флаг, который проверяет, включен ли режим отладки.
• self::$debugOutput — флаг, который определяет, нужно ли выводить отладочную информацию на экран.

Если оба флага активированы, то выполняется следующий код.

Шаги работы в отладочном режиме:

1. Получение имени текущего файла шаблона:

   $file = basename($this->filename);
   echo "<h1>$file</h1>";
   

   Это позволяет вывести имя текущего шаблона (например, index.tpl), для которого будет выводиться отладочная информация.

2. Перебор отладочных данных для текущего шаблона:

   foreach (self::$debugData[$file] as $block => $tags) {
   

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

3. Вывод каждого блока с отладочными данными:

   • Формируется имя блока с помощью:

     $block_name = $file . ' / ' . str_replace('.', ' / ', $block);
     echo "<h2>$block_name</h2>";
     

     Это имя будет включать путь к блоку в шаблоне, где точки заменяются на слэши.

   • Далее выводится список всех тегов, использующихся в блоке. Для каждого тега выводится его значение:

     foreach ($tags as $key => $val) {
         if (is_array($val)) {
             foreach ($val as $key2 => $val2) {
                 echo self::debugVar($key . '.' . $key2, $val2);
             }
         } else {
             echo self::debugVar($key, $val);
         }
     }
     

4. Завершается вывод:

   echo "</ul>";
   

Результат отладки:

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

4.2. Обычный режим

Если отладка не включена, метод работает в обычном режиме и выводит сам контент блока:

echo $this->text($block);

• $this->text($block) — это метод, который фактически получает обработанный контент для указанного блока. Метод text() отвечает за рендеринг данных для блока, его динамическую обработку, подстановку значений переменных и т.д.

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

5. Возвращаемый объект

Метод out() возвращает текущий объект XTemplate:

return $this;

Это позволяет вызывать методы цепочкой. Например:

$tpl->assign('TITLE', 'My Title')->out();

В данном случае, после выполнения метода out() можно продолжить работу с объектом, вызывая другие методы.

6. Как работает метод в реальной жизни?

Предположим, у нас есть шаблон с блоками MAIN и FOOTER:

• Блок MAIN может содержать основной контент страницы, а блок FOOTER — информацию о подвале страницы.
• Метод out() выведет содержимое этих блоков, обработав их в зависимости от данных и условий.

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

$tpl = new XTemplate('template.tpl');
$tpl->assign('TITLE', 'Welcome to My Site');
$tpl->out('MAIN'); // Выведет содержимое блока MAIN
$tpl->out('FOOTER'); // Выведет содержимое блока FOOTER

В этом случае метод out() сначала обработает и выведет содержимое блока MAIN, затем — блока FOOTER. Если режим отладки включен, вместо содержимого блоков будет выведена отладочная информация.

7. Почему это важно?

Метод out() является важным элементом в шаблонизации в Cotonti. Он позволяет:

• Выводить динамически сгенерированные данные в шаблонах.
• Предоставлять отладочную информацию, что особенно полезно при разработке и отладке шаблонов.
• Обеспечивает удобство работы с шаблонами, позволяя разработчикам легко подставлять данные и выводить их в соответствующие блоки.

Заключение:

Метод out() в Cotonti — это ключевая часть системы шаблонов, которая отвечает за вывод содержимого шаблонов или блоков. В зависимости от состояния отладки, он либо выводит обычный контент, либо предоставляет подробную информацию для отладки, что делает его важным инструментом для разработчиков при создании динамичных веб-страниц.

🔍 Подробный разбор метода out() в Cotonti

Метод out() используется для вывода готового HTML-кода из шаблона Cotonti. В зависимости от режима работы он либо:

1. Выводит готовый HTML-код блока (в обычном режиме).
2. Выводит отладочную информацию о содержимом блока (если включена отладка).

Теперь разберём код построчно и доступно.

📌 Объявление метода

public function out($block = 'MAIN')

• Метод out() объявлен как public, то есть его можно вызывать из других частей программы.
• Он принимает один аргумент — $block, который по умолчанию равен 'MAIN'.
  • Если при вызове метода не указать имя блока, он выведет главный блок шаблона (MAIN).
• Возвращает объект XTemplate, позволяя вызывать методы цепочкой (call chaining).

🏁 Проверка режима отладки

if (self::$debugMode && self::$debugOutput) {

• self::$debugMode — это статическая переменная, которая хранит флаг включённого режима отладки.
• self::$debugOutput — отвечает за разрешение вывода отладочной информации.
• Если оба флага включены, то выполняется режим отладки, иначе просто выводится шаблон.

🔍 Отладочный режим (если debugMode включён)

$file = basename($this->filename);
echo "<h1>$file</h1>";

• Получает имя текущего файла шаблона (без пути к нему).
• Выводит это имя в HTML как <h1>Название файла</h1>.

foreach (self::$debugData[$file] as $block => $tags) {

• Перебирает массив debugData, который хранит отладочную информацию о всех блоках шаблона в файле $file.

$block_name = $file . ' / ' . str_replace('.', ' / ', $block);
echo "<h2>$block_name</h2>";

• Преобразует имя блока в удобочитаемый формат:
  • Например, если блок называется PAGE.CONTENT.TEXT, то он станет PAGE / CONTENT / TEXT.
• Выводит название блока в <h2>.

🔹 Вывод списка тегов блока

echo "<ul>";
foreach ($tags as $key => $val) {

• Открывает HTML-список (<ul>), который будет содержать переменные (теги) внутри блока.
• foreach перебирает все переменные (теги) блока.

🏷 Обработка простых и сложных тегов

if (is_array($val)) {
    foreach ($val as $key2 => $val2) {
        echo self::debugVar($key . '.' . $key2, $val2);
    }
} else {
    echo self::debugVar($key, $val);
}

• Если переменная ($val) — массив, значит, у неё есть вложенные значения (например, PAGE.TITLE и PAGE.CONTENT).
• В таком случае выполняется вложенный перебор массива, и каждый подэлемент передаётся в debugVar().
• В противном случае просто вызывается debugVar() для обычной переменной.

Что делает debugVar()?

• Форматирует и красиво выводит значения переменных.
• Например, если переменная PAGE.TITLE = "Привет, мир!", метод выведет что-то вроде:

  <li>PAGE.TITLE: "Привет, мир!"</li>
  

🖥 Обычный режим (если debugMode выключен)

echo $this->text($block);

• Если отладка выключена, просто выводит содержимое блока с помощью метода text($block).
• Метод text() возвращает обработанный HTML-код блока.

Пример:

<div class="header">Добро пожаловать!</div>

✅ Возвращение объекта (call chaining)

return $this;

• Возвращает текущий объект ($this).
• Это позволяет цепочечные вызовы методов:

  $tpl->out()->parse();
  

  Здесь out() выведет шаблон, а parse() обработает следующий блок.

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

🔹 Простой вызов

$tpl = new XTemplate('template.tpl');
$tpl->assign('TITLE', 'Привет, мир!');
$tpl->out(); // Выведет блок MAIN
$tpl->out('FOOTER'); // Выведет блок FOOTER

• Создаётся объект XTemplate.
• Устанавливается переменная TITLE.
• Вызывается out() без аргументов — выводит главный блок (MAIN).
• Затем out('FOOTER') выводит блок FOOTER.

🔹 Отладочный режим

XTemplate::$debugMode = true;
XTemplate::$debugOutput = true;

$tpl = new XTemplate('template.tpl');
$tpl->assign('TITLE', 'Привет, мир!');
$tpl->out();

• Включает режим отладки (debugMode).
• Вместо обычного HTML выведет отладочную информацию:

  <h1>template.tpl</h1>
  <h2>template.tpl / MAIN</h2>
  <ul>
    <li>TITLE: "Привет, мир!"</li>
  </ul>
  

• Покажет, какие переменные были назначены.

📝 Вывод

🔹 Метод out() в Cotonti выполняет две основные задачи:

1. Выводит готовый HTML-код блока (если отладка выключена).
2. Выводит отладочную информацию о шаблоне (если отладка включена).

🔹 Как он работает?

• Если включён debugMode, то показывает переменные внутри блока.
• Если отладка выключена, то выводит готовый HTML шаблона.
• Использует text($block) для генерации HTML.
• Возвращает $this, позволяя цепочечные вызовы.

🔹 Зачем нужен?

• Позволяет контролировать вывод шаблонов.
• Упрощает отладку шаблонов, показывая какие данные были переданы.