Свой модуль для Coffee CMS (v2)
Вторая попытка объяснить как делать модули.
Модуль для Coffee CMS это обычный php-файл, имя которого выглядит примерно так .cms/mod/my_module.mod.php
Создайте такой файлик и запишите в него следующий код:
<?php
$cms["modules"]["my_module.mod.php"] = array(
"name" => "Мой модуль",
"description" => "Описание модуля",
);Благодаря этим строчкам модуль появится в списке модулей в админке. Но и они не обязательны. Можете сразу же писать свой код, который выполнится во время загрузки модулей.
$cms - это глобальный ассоциативный массив, в котором хранится практически все, и настройки и временные переменные. В $cms["config"] хранятся данные, записываемые в файл настроек, а все остальные поля, в том числе и $cms["modules"] живут пока исполняется код.
Добавьте в этот файл строчку:
file_put_contents( __DIR__ . "/debug.php", '<?php $cms = ' . var_export( $cms, true) . ";\n", LOCK_EX );Теперь во время загрузки модуля будет создаваться файл debug.php в котором будет находиться все, что было в переменной $cms на время выполнения этого кода. Эта полезная строчка пригодится вам когда будете отлаживать свой модуль. Можете скидывать не всю $cms, а только интересующие части, чтобы легче было разобраться.
При разработке модуля важно понимать когда и что делается. Логично предположить, что сначала модули загружаются и уже потом, следуя какой-то логике, код начинает исполняться.
Но на самом деле код исполняется и во время загрузки модуля. Модули загружаются с помощью команды include() и весь код, не завернутый в функции тут же исполняется. А все, что нужно выполнить чуть позже нужно повесить на хуки.
Хуки - это события, которые могут возникать в определенные моменты, могут не возникать, и происходят в какой-то последовательности, в зависимости от обстоятельств. Название хук происходит от слова hook, которое переводится как крючок. На этот крючок навешивают функции и когда приходит время, крючок дергается и выполняет все привязанные к нему функции. Так устроены все CMS, отличаются только детали реализации.
Поэтому ваш модуль, загружаясь, должен понавешать функций на нужные вам хуки, а не выполнять всю работу сразу. А уже дальнейшая логика, следуя обстоятельствам, начнет дергать тот или иной хук.
Описать что дальше происходит можно только приблизительно. Любой модуль может поменять порядок исполнения хуков, добавлять свои хуки, отключать чужие хуки и поэтому вы не найдете ни к какой цмс документации где четко описана последовательность или имеется какая-то древовидная схема хуков или объясняется каким-то другим понятным образом. Вам просто дают гигантский перечень хуков, говорят когда они возникают и как повесить на них свои фукнции.
В Coffee CMS список не гигантский и хуки выполняются в последовательности, прописанной в самих хуках.
// в файле .cms/index.php
$cms["hooks"] = array(
"query" => array( "next" => "template" ),
"template" => array( "next" => "echo" ),
"echo" => array( "next" => "write" ),
"write" => array( "next" => "" ),
"admin" => array( "next" => "template" ),
"api" => array( "next" => "" ),
"cron" => array( "next" => "" ),
);
Основной режим работы состоит в последовательности query => template => echo => write. На хуке query анализируется запрос, извлекается статья из базы данных, на хуке template запихивается в шаблон, на хуке echo отправляется браузеру, на хуке write записывается на диск.
С помощью своего модуля вы можете вмешиваться в процесс, перезаписывать данные, дернуть свой придуманный хук, нужный для вашей логики, отключить какой-либо хук или изменить последовательность, перезаписав "next".
Так что подумайте, что вам нужно, определите хук и повесьте на него свою фукнцию, вот так:
// в файле .cms/mod/my_module.mod.php
hook_add_fn( "query", "my_function_name" );
function my_function_name() {
file_put_contents( __DIR__ . "/debug2.php", "Ололо\n", FILE_APPEND );
}
И, скорее всего, вам не хватит стандартного поведения и понадобится придумать свою логику для модуля, который будет принимать данные с сайта. Для этого придумайте имя своему хуку, например, my_mod_input_data и повесьте свою функцию на него. А чтобы хук сработал при дергании определенного url, напишите так:
// в файле .cms/mod/my_module.mod.php
$cms["urls"]["/input_data"] = "my_mod_input_data";
Цмс, запускаясь, пробегает массив $cms["urls"] и если находит соответствие запрошенного url, то ставит текущим хуком тот что указан. Если нет, то никаких изменений не происходит и выполняется стандартный набор query => template => echo => write.
Т.е., если вам надо создать много хуков и задать им последовательность, то вписывайте все в массив $cms["hooks"] по вышеприведенному образцу, навешивайте свои функции и таким образом стройте логику своего модуля. Функция hook_add_fn() сама создает хук если его нет и добавляет фукнцию. Поэтому просто навешайте функций и потом задайте порядок выполнения хуков если это нужно.
Модуль админки в цмс так и работает, ставит на нужный url хук admin, модули в этот момент создают свои админские странички, переключается шаблон на админский, запись на диск отключается и далее выполняются хуки template и echo.
Параметры своего модуля, которые нужно сохранять, записывайте в $cms["config"]["my_module.mod.php"]["param1"] чтобы не толкаться с другими модулями и после этого вызывайте cms_save_config(); чтобы сохранить их в файле. В следующий раз, когда модуль будет загружен, параметры уже будут находиться на своих местах.
Если вам нужно локализовать модуль, то используйте функцию __( "message_text" ); и задавайте переводы в файликах расположенных в папке .cms/lang/ по такому же принципу, который там увидите. Функция __() определена в файле .cms/index.fn.php, она сама определяет из какого файла ее вызывают и ищет переводы в соответствующем разделе, но вы можете указать вторым параметром в каком разделе искать переводы __( "message_text", "razdel2" ); Поглядите как переводы делаются в модуле base.mod.php, он сделан без лишних js-скриптов, сохраняет параметры путем классической отправки формы. И не забывайте после приема такой формы сделать редирект чтобы браузер не писал "Отправить форму повторно?".
Если остались вопросы, задавайте в комментах.