Простейший модуль на TextCMS

В данной теме будут показаны некоторые приемы написания модулей для TextCMS на примере классического "Hello, World!".
Итак, начнем. Сначала выберем название для нашего модуля. Пусть это будет hello (название должно соответствовать требованиям к идентификаторам в PHP, желательно не делать названия длиной более 8 символов). Создадим файл modules/hello/module.php в любом текстовом редакторе и в нем — основную функцию hello_main и вспомогательную _hello_str: <?php 
function _hello_str() {
 return 'Hello';
}
function hello_main($str='world') {
 return '<p>'._hello_str().', '.$str.'!</p>';
}
Итак, первый модуль готов! Вызвать его можно двумя способами: либо вставить в текст страницы или шаблона конструкцию
##block[hello_main]#
, либо через админку: admin.php?a=hello_main, либо из другого модуля, вызвав сначала функцию cms_load_module: <?php
if (cms_module_load('hello',false)) $hello_str = hello_main();
else $hello_str='';
Некоторые пояснения: во избежание конфликта имен все функции модуля должны начинаться с имя_модуля (если они предназначены для вызова через ##block[]# или напрямую через панель администрирования) или _имя_модуля (прочерк в начале нужен в том случае, если функция является вспомогательной, то есть предназначена для вызова только из других функций данного модуля).
Если функция предназначена для вызова через block[] или из панели администрирования, ее возвращаемым значением должна быть строка, содержащая HTML-код, который будет вставлен вместо конструкции ##block[]#. Если функция вызывается из Панели администрирования, результат ее работы вставляется вместо ##CONTENT#  в шаблоне admin.htm
При вызове через ##block[]# можно передавать в функцию параметры, разделяя их запятыми (без пробелов), так ##block[hello_main,мир]# выдаст "Hello, мир!". Хорошим стилем написания модулей TextCMS считается присвоение всем параметрам значений по умолчанию.
Если функция предназначена только для вызова из Панели администрирования, следует в ее начале добавить такую проверку:
if (!definded('TextCMS_Admin')) return '';
Чтобы для модуля появился пункт меню в Панели администрирования, создадим файл modules/hello/menu.txt вот такого вида:
hello_main:50:Демо Hello World
Каждая строка в этом файле состоит из трех частей, разделенных двоеточиями. Первая — это имя вызываемой функци (hello_main в нашем случае), номер для сортировки, который определяет, где выведется пункт меню (50), и текст самого пункта меню.

В PHP хорошим стилем программирования считается отделение PHP-части от HTML-кода. Для этого в TextCMS предусмотрен простейший шаблонизатор. Работа с ним делается с помощью cms_output_load_template (не требует подключения дополнительных модулей), которая загружает соответствующий шаблон и функции cmsmain_replace из модуля cmsmain, которая осуществляет замену полей в шаблоне на соответствующие значения.
Перепишем нашу функцию hello_main с использованием шаблонизатора:
<?php function hello_main($str='world') {
 $data['str1']=_hello_str();
 $data['str2']=$str;
 $page = cms_output_load_template('test.htm','hello'); // загружаем шаблон в переменную, hello во втором параметре указывает на то, что это шаблон модуля, а не CMS в целом, и искать его следует в template/имя_шаблона/modules/hello/test.htm, а не просто в template/имя_шаблона/test.htm
 if (cms_load_template('cmsmain',false)) $page = cmsmain_replace($page,$data); // производим замену полей на значения
 return $page;
}
Сам файл шаблона должен находиться в template/default/modules/hello/test.htm (оттуда он унаследуется другими шаблонам, если не будет переопределен в них) и иметь следующее содержимое:
<p>#str1#, #str2#!</p>
.
Как видно, последовательности вида #имя_поля# заменяются на данные, записанные в соответствующем ключе хеша $data.

Шаблонизатор является простейшим и не поддерживает ни циклов, ни условий (сделано это вполне сознательно, так как более сложные шаблонизаторы привели бы к "утяжелению" CMS). Поэтому в случае, если необходимо организовать вывод для множества элементов, цикл нужно размещать в самом модуле:
<?php // генерируется массив каких-то элементов в $items
$page = cms_output_load_template('test2.htm','hello');
$item_tmpl=cms_output_load_template('item.htm','hello');
$buffer = '';
if (cms_load_module('cmsmain',false)) foreach ($items as $item) { // в этом цикле накапливаем результаты шаблонизации для каждого элемента в буфер
 $buffer.=cmsmain_replace($item_tmpl,$item);
}
$page = str_replace('#items#',$buffer,$page); // а потом вставляем буфер в главный шаблон модуля
return $page; // и возвращаем полученное


Еще из полезных функций в cmsmain можно назвать функцию cmsmain_html_set, которая будет полезна при обработке форм. Она выставляет значения полей HTML-формы в соответствии с передаными ей данными. Функция принимает три параметра:
$html HTML-код с формой, в поля которой требуется расставить значения
$data Хеш-массив с данными для формы, где ключ элемента совпадает с именем поля в форме, в которое будет вставлено значение элемента
$params Хеш-массив с набором значений для элементов типа select. Ключ элемента массива — идентификатор элемента select, значение — хеш-массив, на основе которого генерируются теги <option>: ключи массива идут в поле value, а значения — в текстовое описание тега
Возвращаемое значение --строка HTML-кода с формой, поля которой заполнены значениями из массива $data.

Кроме того, если функция использует какие-то данные, которые могут изменяться со временем (скажем, считывает что-то из файлов), она должна изменять соответствующим образом глобальную переменную $GLOBALS['lastmod'], которая отвечает за выдачу заголовка Last-Modified и работу с кешем:
<?php 
function hello_main() {
// какая-то обработка данных, в ходе которых определяется значение $hello_last_mod
$GLOBALS['lastmod']=max($GLOBALS['lastmod'],$hello_last_mod);
Обратите внимание: глобальный lastmod нужно выставлять именно так, как показано в примере. В противном случае при наличии нескольких модулей на одной странице последний из них будет затирать значения, выставленные предыдущими, что может привести к выдаче некорректного Last-Modified и показу пользователю устаревшей страницы из кеша.