Система хуков в RC4+

[Bugo]

Часть первая (ознакомительная)

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

Более полную информацию об этих новых функциях можно найти в wiki-документации. Называются они хуками. К сожалению, там описаны далеко не все реализованные хуки (но в будущем ситуация должна измениться).

Рассмотрим несколько новых хуков на примере Quick Spoiler. Этот мод добавляет кнопку в редактор, для вставки в сообщения пары тегов:

Код Выделить Развернуть

[spoiler][/spoiler]

Итак, прежде всего заглянем в архив мода и обратим внимание, что там нет привычного файла install.xml (или modification.xml). Там вообще из привычных *.xml файлов остался только package-info.xml, в котором прописана процедура установки. В частности, в нем указано, что при установке (и удалении) мода нужно запустить файл hooks.php. Откроем этот файл.

Наблюдаем следующую запись

Код Выделить Развернуть


$hooks = array(
'integrate_pre_include' => '$boarddir/Sources/Subs-QuickSpoiler.php',
'integrate_bbc_codes' => 'spoiler_bbc_add_code',
'integrate_bbc_buttons' => 'spoiler_bbc_add_button',
'integrate_general_mod_settings' => 'spoiler_settings'
);

if (!empty($context['uninstalling']))
$call = 'remove_integration_function';
else
$call = 'add_integration_function';

foreach ($hooks as $hook => $function)
$call($hook, $function);

Это и есть хуки. Функция add_integration_function обходит массив $hooks и добавляет указанные значения в соответствующие переменные. Например, переменной $modSettings['integrate_bbc_codes'] будет присвоено значение spoiler_bbc_add_code, а переменной $modSettings['integrate_bbc_buttons'] — spoiler_bbc_add_button. При удалении мода [if (!empty($context['uninstalling']))] эти значения из переменных удаляются.

Хук integrate_pre_include обрабатывается в Load.php и содержит в себе путь к файлу, который необходимо подключить после установки мода. Раньше, без этого хука, для подключения нужного файла приходилось прописывать строчку require_once('путь к файлу') в index.php (тем самым внося изменения в один из ключевых файлов форума) — причем делать это после каждого обновления форума. Теперь же путь будет храниться в базе данных, а подключаемый файл может содержать внутри любые ваши функции.

Продолжаем изучение package-info.xml. Как видим, при установке в директорию /Sources распаковывается файл Subs-SimpleSpoiler.php. Наши функции, которые вызываются в остальных хуках, описаны именно в этом файле: spoiler_bbc_add_code, spoiler_bbc_add_button и spoiler_settings.

Конструкция в начале файла Subs-QuickSpoiler.php

Код Выделить Развернуть


if (!defined('SMF'))
die('Hacking attempt...');

обязательна, так как не даёт запустить файл напрямую, минуя SMF. Не забывайте её использовать в своих проектах.

В функции spoiler_bbc_add_code через хук integrate_bbc_codes добавляем нужные нам теги (в данном случае: [spoiler][/spoiler]):

Код Выделить Развернуть


$codes[] = array(
'tag' => 'spoiler',
'before' => '<div class="sp-wrap"><div class="sp-body" title="' . $txt['quick_spoiler'] . '">',
'after' => '</div></div>',
'block_level' => true,
);
$codes[] = array(
'tag' => 'spoiler',
'type' => 'unparsed_equals',
'before' => '<div class="sp-wrap"><div class="sp-body" title="$1">',
'after' => '</div></div>',
'block_level' => true,
);


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

Код Выделить Развернуть


spoiler_header();


Функция spoiler_bbc_add_button через хук integrate_bbc_buttons предоставляет возможность добавить новую кнопку, для вставки наших тегов:

Код Выделить Развернуть


function spoiler_bbc_add_button($buttons)
{
global $txt;

$buttons[count($buttons) - 1][] = array(
'image' => 'spoiler',
'code' => 'spoiler',
'before' => '[spoiler]',
'after' => '[/spoiler]',
'description' => $txt['quick_spoiler'],
);
}


В конце файла видим небольшую функцию spoiler_settings, которая подключается через хук integrate_general_mod_settings:

Код Выделить Развернуть


function spoiler_settings($config_vars)
{
global $txt;
loadLanguage('QuickSpoiler');
$config_vars[] = array('select', 'qs_hide_img', explode('|', &$txt['qs_hide_select']));
$config_vars[] = array('check', 'qs_fancy');
}

Это ни что иное, как добавление настроек мода в раздел Настройки модификаций. То есть при установке даже не потребуется редактировать файл ManageSettings.php, как это делалось раньше. Обратите внимание: все текстовые переменные хранятся в отдельном файле, который подключается через функцию loadLanguage.
Кстати, названия ваших функций могут быть любыми. Лишь бы они вызывались через нужные хуки.

Таким образом, при очередном обновлении форума вам даже не потребуется переустанавливать этот мод — всё будет подключаться автоматически, при наличии нужных записей в переменных $modSettings. При установке других подобных модов, использующих те же хуки, значения этих переменных не обнуляются, а дополняются, через запятую. Главное, чтоб названия пользовательских функций не совпадали. Единственное, что может потребоваться сделать — закинуть файлик spoiler.gif в директорию images каждой темы оформления, которую вы захотите добавить позже.

Часть вторая (познавательная)

Примечание: один из новых хуков, введенных в RC5, оказался не на том месте и не в том «оформлении». Речь идёт о хуке, помогающем добавлять настройки модов в раздел Настройки модификаций, без изменения файла ManageSettings.php. Именно изменения в этом файле зачастую вызывают кучу проблем при установке каждого очередного мода. Разработчики уже в курсе ошибки, но исправлять её отказались, до выхода финала (как обычно). Но это исправление не сложно сделать самостоятельно.

Открываем ManageSettings.php, находим блок:

Код Выделить Развернуть


function ModifyModSettings()
{
global $context, $txt, $scripturl, $modSettings, $settings;

$context['page_title'] = $txt['admin_modifications'];

$subActions = array(
'general' => 'ModifyGeneralModSettings',
// Mod authors, once again, if you have a whole section to add do it AFTER this line, and keep a comma at the end.
);

loadGeneralSettingParameters($subActions, 'general');

// Load up all the tabs...
$context[$context['admin_menu_name']]['tab_data'] = array(
'title' => $txt['admin_modifications'],
'help' => 'modsettings',
'description' => $txt['modification_settings_desc'],
'tabs' => array(
'general' => array(
),
),
);

// Make it easier for mods to add new areas.
call_integration_hook('integrate_modify_modifications', array(&$subActions, &$context[$context['admin_menu_name']]['tab_data']['tabs']));

// Call the right function for this sub-acton.
$subActions[$_REQUEST['sa']]();
}

и меняем его на:

Код Выделить Развернуть


function ModifyModSettings()
{
global $context, $txt, $scripturl, $modSettings, $settings;

$context['page_title'] = $txt['admin_modifications'];

$subActions = array(
'general' => 'ModifyGeneralModSettings',
// Mod authors, once again, if you have a whole section to add do it AFTER this line, and keep a comma at the end.
);

// Make it easier for mods to add new areas.
call_integration_hook('integrate_modify_modifications', array(&$subActions));

loadGeneralSettingParameters($subActions, 'general');

// Load up all the tabs...
$context[$context['admin_menu_name']]['tab_data'] = array(
'title' => $txt['admin_modifications'],
'help' => 'modsettings',
'description' => $txt['modification_settings_desc'],
'tabs' => array(
'general' => array(
),
),
);

// Call the right function for this sub-acton.
$subActions[$_REQUEST['sa']]();
}


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

Код Выделить Развернуть


'tabs' => array(
'general' => array(
),
),

и затем заменяется на что-то вроде:

Код Выделить Развернуть


'tabs' => array(
'general' => array(
),
'my_mod' => array(
),
),


Это крайне неудобно. Даже если затем мы по порядку установим ещё несколько модов, без всяких проблем, мы обязательно столкнемся с проблемами при удалении какого-нибудь мода. Но хук integrate_modify_modifications решает проблему. После изменения, предложенного мной выше, достаточно будет в install.php вашего мода прописать:

Код Выделить Развернуть


$hooks = array(
'integrate_pre_include' => '$boarddir/Sources/Subs-MyMod.php',
'integrate_admin_areas' => 'my_mod_admin_areas',
'integrate_modify_modifications' => 'my_mod_modifications',
);

if (!empty($context['uninstalling']))
$call = 'remove_integration_function';
else
$call = 'add_integration_function';


При этом файл Subs-MyMod.php может выглядеть примерно так:

Код Выделить Развернуть


<?php

if (!defined('SMF'))
die('Hacking attempt...');

function my_mod_admin_areas(&$admin_areas)
{
global $txt;

$admin_areas['config']['areas']['modsettings']['subsections']['my_mod_features'] = array($txt['my_mod_title']);
}

function my_mod_modifications(&$subActions)
{
$subActions['my_mod_features'] = 'my_mod_settings';
}

function my_mod_settings()
{
global $context, $txt, $scripturl;
   
$context['page_title'] = $context['settings_title'] = $txt['my_mod_modifications_desc'];
$context['post_url'] = $scripturl . '?action=admin;area=modsettings;save;sa=my_mod_area';
$context[$context['admin_menu_name']]['tab_data']['tabs']['my_mod_features'] = array('description' => $txt['my_mod_desc']);

$config_vars = array(
array('check', 'my_mod_any_option'),
);

// Saving?
if (isset($_GET['save']))
{
checkSession();
saveDBSettings($config_vars);
redirectexit('action=admin;area=modsettings;sa=my_mod_area');
}

    prepareDBSettingContext($config_vars);
}

?>


Обратите внимание на первую функцию (my_mod_admin_areas(&$admin_areas)) в этом файле. Она (через хук integrate_admin_areas) замещает те изменения, которые раньше при установке модов приходилось делать в Admin.php.

Часть третья (заключительная)

Рассмотрим ещё несколько полезных хуков: integrate_display_buttons, integrate_mod_buttons, integrate_menu_buttons, integrate_buffer. Порядок их использования аналогичен уже рассмотренным в примерах выше.

Например, хуки integrate_display_buttons и integrate_mod_buttons позволяют добавить свою кнопку на страницу просмотра темы, без редактирования файла Display.template.php. Первый хук — для обычных кнопок, второй — для модераторских. Подробно их рассматривать не буду.

Для добавления/изменения кнопок в главном меню предназначается хук integrate_menu_buttons. Например, в моде Fancy Features я с помощью этого хука устанавливаю опциональное отображение кнопки "Помощь", а также добавляю в подменю Админка новый пункт — Расширенные настройки (для быстрого перехода к настройкам мода):

Код Выделить Развернуть


function fancy_menu_buttons($buttons)
{
global $modSettings, $context, $txt, $scripturl;

if (!empty($modSettings['fancy_button_help'])) {
unset($buttons['help']);
if ($context['current_action'] == 'help') redirectexit('action=home');
}

if ($context['allow_admin']) {
$counter = 0;
foreach ($buttons['admin']['sub_buttons'] as $area => $dummy)
{
$counter++;
if ($area == 'packages')
break;
}

$buttons['admin']['sub_buttons'] = array_merge(
array_slice($buttons['admin']['sub_buttons'], 0, $counter, TRUE),
array('modsettings' => array(
'title' => $txt['fancy_modifications_desc'],
'href' => $scripturl . '?action=admin;area=modsettings;sa=fancy_features',
'show' => allowedTo('admin_forum'),
)),
array_slice($buttons['admin']['sub_buttons'], $counter, NULL, TRUE)
);
}
}


Хук integrate_buffer — без сомнения, один из самых интересных. К примеру, в моде Custom Copyright с помощью этого хука под копирайтом SMF можно добавить собственный:

Код Выделить Развернуть


function editBuffer($buffer)
{
global $modSettings;

if(empty($modSettings['custom_copyright_message']) || $modSettings['custom_copyright_message'] == 'Edit This...' || empty($modSettings['custom_copyright_enable']))
return $buffer;

$search = ', Simple Machines LLC</a>';
$replace = ', Simple Machines LLC</a><br />' . $modSettings['custom_copyright_message'];
return (isset($_REQUEST['xml']) ? $buffer : str_replace($search, $replace, $buffer));
}


[Inter]

ты бы всю страницу перевел -> http://wiki.simplemachines.org/smf/Integration_Hooks   

[Mavn]

ну если не заметил то эта статья не является переводом статьи на офф сайте и расписано здесь куда более понятнее чем там.

[Bugo]

ты бы всю страницу перевел -> http://wiki.simplemachines.org/smf/Integration_Hooks

Никогда не любил сухую теорию, предпочитаю только практику

На примере мода Topic Rating Bar рассмотрим добавление пользовательских actions для выполнения определенных действий, без редактирования файлов форума.

Итак, мод предназначен для оценивания тем по шкале из 5 звёздочек (в базу данных заносится ID проголосовавшего пользователя, вместо IP — потому что IP штука изменчивая). При нажатии на одну из звездочек на сервер отправляется запрос, содержащий номер нажатой звездочки, id темы и общее количество звёздочек:

Код Выделить Развернуть

?action=rating;stars=4;topic=1;scale=5

Как создается action=rating? Для начала рассмотрим, что это вообще такое. А это всего лишь ссылка на определенную функцию (rating_control) в определенном файле (TopicRating.php). Раньше для этого пришлось бы добавлять строчку:

Код Выделить Развернуть

'rating' => array('TopicRating.php', 'rating_control'),
в массив $actionArray в файле index.php (в корне форума). Но благодаря хуку integrate_actions теперь всё гораздо проще. В файле TopicRating.php определяем функцию:

Код Выделить Развернуть

function rating_action(&$actionArray)
{
$actionArray['rating'] = array('TopicRating.php', 'rating_control');
}
И вызываем её через хук (в файле install.php):

Код Выделить Развернуть

'integrate_actions' => 'rating_action'

Сам файл TopicRating.php подключается через хук integrate_pre_include, рассмотренный ранее (см. первый пост темы).

Далее, через хук integrate_load_theme (чтобы не редактировать index.template.php каждой темы и не трогать Load.php) вызывается функция rating_header, загружающая таблицу стилей:

Код Выделить Развернуть

function rating_header()
{
global $context, $settings;

$context['html_headers'] .= '
<link rel="stylesheet" type="text/css" href="' . $settings['default_theme_url'] . '/css/rating.css" />';
}

Хук integrate_display_buttons предназначен для добавления своих кнопок в сообщения ("Отправить", "Цитата" и т. д.), но не возбраняется использовать этот хук и для других целей:

Код Выделить Развернуть

'integrate_display_buttons' => 'rating_display'

Код Выделить Развернуть

function rating_display()
{
global $context;

rating_bar($context['current_topic'], 5);
}
Вызываемая функция rating_bar описывается в файле TopicRating.php и выводит в шаблоне панельку со звездочками, прямо в верхней части темы, id которой указан первым параметром. Вторым параметром служит количество звездочек в шкале. Очень удобно.


Другая задача: при просмотре общего списка тем было бы неплохо видеть среднее количество выставленных звездочек напротив каждой из темы. Я реализовал это через jQuery, без редактирования MessageIndex.template.php, index.template.php, Load.php, MessageIndex.php и т. д. С помощью хука integrate_messageindex_buttons (который, по сути, предназначен не совсем для этого, а для добавления кнопок типа "Новая тема" и т. д.):

Код Выделить Развернуть

'integrate_messageindex_buttons' => 'rating_messageindex'
В функции rating_messageindex содержится запрос к базе данных и jQuery-код, добавляющий перед определенными элементами новый span с количеством звездочек:


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

Код Выделить Развернуть

'integrate_load_permissions' => 'rating_permissions'

Код Выделить Развернуть

function rating_permissions(&$permissionGroups, &$permissionList)
{
global $txt, $context;

loadLanguage('TopicRating');

$permissionList['membergroup']['rate_topics'] = array(false, 'general', 'view_basic_info');
$context['non_guest_permissions'][] = 'rate_topics'; // Гостям незачем оценивать темы, во избежание накрутки
}
После этого в правах доступа в разделе «Использование основных функций форума» появляется новая строчка — «Оценка тем».

Языковой файл — TopicRating.russian-utf8.php:

Код Выделить Развернуть


<?php
// Version: 2.0 RC5; TopicRatings

$txt['tr_rating'] = 'Рейтинг темы:';
$txt['tr_rate_pl'] = 'Оцените эту тему:';
$txt['tr_currently'] = 'Текущий рейтинг ';
$txt['tr_rates'] = 'Ужасно|Плохо|Средне|Хорошо|Отлично';
$txt['tr_error'] = 'Оценка собственных тем запрещена!';
$txt['tr_access_error'] = 'Извините, но Вам запрещено оценивать темы.';
$txt['tr_votes'] = 'Всего голосов: ';

// Permissions
$txt['permissionname_rate_topics'] = 'Оценка тем';
$txt['permissionhelp_rate_topics'] = 'Пользователи могут оценивать темы в разделах (кроме собственных).';
?>


При установке мода Topic Rating Bar не вносится ни одного изменения в файлы движка — всё работает через базу данных и хуки. Языковые переменные хранятся в отдельных файлах и подключаются при необходимости. Поэтому при обновлении форума мод не утратит работоспособности.

[Макар]

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

к сожалению еще никак не могу въехать в эту систему

[Bugo]

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

[Макар]

Скачал, посмотрел. Все же мод "не чистый" там присутствует install.xml в котором описаны прямые правки sourse файлов . Получается при оновлении мод слетит............

Хук integrate_buffer — без сомнения, один из самых интересных. К примеру, в моде Custom Copyright с помощью этого хука под копирайтом SMF можно добавить собственный

а почему ты не воспользовался ей при

Хук integrate_display_buttons предназначен для добавления своих кнопок в сообщения ("Отправить", "Цитата" и т. д.), но не возбраняется использовать этот хук и для других целей:

и

Другая задача: при просмотре общего списка тем было бы неплохо видеть среднее количество выставленных звездочек напротив каждой из темы. Я реализовал это через jQuery, без редактирования MessageIndex.template.php, index.template.php, Load.php, MessageIndex.php и т. д. С помощью хука integrate_messageindex_buttons (который, по сути, предназначен не совсем для этого, а для добавления кнопок типа "Новая тема" и т. д.):

ведь по сути Хук integrate_buffer более подходит для правки шаблонов ? или я что то не то понял


Bugo, можно на примере помочь с пониманием этой каши ?

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


если в файл BoardIndex.template.php

в код

Код Выделить Развернуть

foreach ($context['categories'] as $category)
{
 
// If theres no parent boards we can see, avoid showing an empty category (unless its collapsed)
if (empty($category['boards']) && !$category['is_collapsed'])
continue;

добавить

Код Выделить Развернуть

foreach ($context['categories'] as $category)
{
                      if (in_array($category['id'],array(6)))
continue;
// If theres no parent boards we can see, avoid showing an empty category (unless its collapsed)
if (empty($category['boards']) && !$category['is_collapsed'])
continue;


где array(6,8,1) - массив с номерами скрываемых категорий, при выводе они не будут показаны но сохранится функционал и доступность разделов по прямой ссылке. Которую, например можно добавить в основное меню сделав в нем кнопку, или в блок портала ...........

Но не об этом речь  Я сейчас могу оформить этот код в виде обычного мода использующего xml инструкции вида найти/заменить .

А как  это  сделать при помощи хуков ?
создаю скелет мода с файлами

package-info.xml
install.php
uninstal.php

в package-info.xml описываем мод

Код Выделить Развернуть



<?xml version="1.0"?>
<!DOCTYPE package-info SYSTEM "http://www.simplemachines.org/xml/package-info">
<package-info xmlns="http://www.simplemachines.org/xml/package-info" xmlns:smf="http://www.simplemachines.org/">
<id>xxx:HideCategories</id>
<name>HideCategories</name>
<version>0.0</version>
<type>modification</type>

<install for="2.0 RC5 - 2.99.99">
<database>install.php</database>
</install>

<uninstall for="2.0 RC5 - 2.99.99">
<code>uninstall.php</code>
</uninstall>
</package-info>


начинаем заполнять файл install.php

Код Выделить Развернуть


<?php
// If SSI.php is in the same place as this file, and SMF isn't defined, this is being run standalone.
if (file_exists(dirname(__FILE__) . '/SSI.php') && !defined('SMF'))
require_once(dirname(__FILE__) . '/SSI.php');

elseif(!defined('SMF'))
die('<b>Error:</b> Cannot install - please verify you put this in the same place as SMF\'s index.php.');



add_integration_function(); // какой тип выбирать ?


?>



следующий шаг какой ?

где мне описывать функцию


// HideCategories
function HideCategories
{
// Какой тип выбирать и как опсывать ?
}

[digger®]

ведь по сути Хук integrate_buffer более подходит для правки шаблонов ? или я что то не то понял

Хук integrate_buffer работает с полным текстом сгенерированной страницы, поэтому с точки зрения производительности и расхода памяти это худший вариант.

[Макар]

О четко и понятно

какой хук тогда использовать для правки файлов .template. тем оформления ?

[digger®]

О четко и понятно

какой хук тогда использовать для правки файлов .template. тем оформления ?

Не помогут тебе хуки, правь шаблоны.

[TXT]

нужно запустить файл hooks.php

Bugo, подскажи, пожалуйста: если вручную ставил (ну как ставил - скопировал файлы) на Quick Spoiler на SMF 2.1 - как выполнить

Код Выделить Развернуть

<hook hook="integrate_pre_load" function="QuickSpoiler::hooks" file="$sourcedir/Class-QuickSpoiler.php" />Иначе ничего не происходит

В админке в "Хуки интеграции" пусто.

[GeorG]

Зачем вручную, через админку мод ставится.

[Yarik]

Bugo, подскажи, пожалуйста: если вручную ставил (ну как ставил - скопировал файлы) на Quick Spoiler на SMF 2.1 - как выполнить

Код Выделить Развернуть

<hook hook="integrate_pre_load" function="QuickSpoiler::hooks" file="$sourcedir/Class-QuickSpoiler.php" />Иначе ничего не происходит

В админке в "Хуки интеграции" пусто.

В БД форума таблица сеттинг.
Там находим поле integrate_pre_load,в него вставляем QuickSpoiler::hooks,сохраняем.

[TXT]

Зачем вручную

Приходится.

[Bugo]

Чтобы в этом случае в базу данных не заглядывать, в конце файла index.php в корне форума можно добавить строчку

Код Выделить Развернуть

add_integration_function('integrate_pre_load', '$sourcedir/Class-QuickSpoiler.php|QuickSpoiler::hooks');Затем обновить в браузере любую страницу форума, и в базе данных появится информация в соответствующей таблице и строке (smf_settings, integrate_pre_load). После этого эта строчка в файле index.php уже будет не нужна, закомментировать или удалить.

[TXT]

Удалил в базе строку integrate_pre_load - надеюсь, правильно удалил хук. После его установки начались глюки на форуме - 

Следующие ошибки возникли при попытке отправки сообщения: Ваша сессия истекла во время написания сообщения. Пожалуйста, попробуйте заново.

и вообще выбрасывало с аккаунта.