Среди множества новых возможностей, появившихся в релизе Joomla 3.2, наименее известными, но, безусловно, очень полезными для администраторов и интересными для разработчиков, являются так называемые «послеустановочные сообщения» (post-install messages). Они информируют администратора сайта о тех возможностях, которые требуют вашего внимания после успешной установки расширения.
Давайте подробнее рассмотрим эту новую возможность, а также узнаем, как она может использоваться разработчиками. Если вы уже установили Joomla 3.2, вы, скорее всего, обратили внимание на информативное сообщение в панели управления как на картинке ниже. После клика на кнопку "Review Messages" вы будете уведомлены о доступности "Two-factor authentication", которая требует вашего внимания. Это первый пример конкретного приложения, которое использует эту новую возможность.
Что это?
Это система для управления послеустановочными сообщениями или сообщениями обновления. Они могут использоваться во время установки и/или обновления расширения. Например, после установки многие расширения требуют обязательных настроек, без которых они не могут полноценно работать. Вышеупомянутое расширение "Two-factor authentication", используя систему уведомлений, информирует вас о том, что возможность доступна, но для её функционирования вам необходимо выполнить определенные настройки.
Как это работает
Вся работа делается новым компонентом com_postinstall
, который управляет взаимодействием между системой уведомлений и расширениями через определение двух функций:
- action (действия, которые необходимо выполнить, например перенаправить на страницу настроек)
- condition (условия для отображения сообщения, например после установки)
Данные хранятся в новой таблице #_postinstall_messages
.
Вообще-то com_postinstall
- это великолепный пример того, как можно использовать новый Joomla! Rapid Development Framework для быстрой разработки приложений.
Как это использовать в своем расширении
Использовать послеустановочные сообщения в своем расширении довольно просто. Давайте предположим, что мы хотим использовать эту систему для уведомления администратора сайта о том, что после установки расширения (условие) необходимо сделать некоторые настройки. В нашем случае расширением будет плагин типа system
, название которого "example_postinstall_messages". Мы хотим перенаправить администратора на страницу настроек плагина после клика по кнопке сообщения (действие). Код плагина вы можете найти на GitHub.
Мы должны добавить две вещи по сравнению с обычным расширением:
- создать файл, содержащий определение двух функций (postinstall_action, postinstall_condition)
- вставить информацию о расширении в таблицу
#_postinstall_messages
Для простоты я создал новую папку под названием postinstall в корне моего плагина и создал файл actions.php, который будет содержать код для двух функций, которые я собираюсь определить. Ссылка на этот файл будет содержаться в полях action_file
и condition_file
таблицы #_postinstall_messages
.
Давайте определим эти две функции (postinstall_action
и postinstall_condition
).
Функция postinstall_condition
будет обрабатывать условие появления сообщения. В нашем случае условием будет, когда плагин установлен, но не включен:
/**
* Checks if the plugin is enabled. If not it returns true, meaning that the
* message concerning this plugin should be displayed.
*
* @return boolean
*
* @since 1.0
*/
function example_postinstall_condition()
{
$db = JFactory::getDbo();
$query = $db->getQuery(true)
->select('enabled')
->from($db->quoteName('#__extensions'))
->where($db->quoteName('type') . ' = ' . $db->quote('plugin'))
->where($db->quoteName('enabled') . ' = 1')
->where($db->quoteName('folder') . ' = ' . $db->quote('system'))
->where($db->quoteName('element') . ' = ' . $db->quote('example_postinstall_messages'));
$db->setQuery($query);
if ($db->loadResult())
{
return false;
}
return true;
}
Функция postinstall_action
будет активироваться тогда, когда админ кликнет по кнопке, которая отображается в сообщении уведомления. В нашем случае действиями являются: включить плагин и перенаправить админа на страницу настроек плагина:
/**
* Enables plugin and redirects the user to the plugin configuration page.
*
* @return void
*
* @since 1.0
*/
function example_postinstall_action()
{
// Get the plugin information
$db = JFactory::getDbo();
$query = $db->getQuery(true)
->select('*')
->from($db->quoteName('#__extensions'))
->where($db->quoteName('type') . ' = ' . $db->quote('plugin'))
->where($db->quoteName('enabled') . ' = 0')
->where($db->quoteName('folder') . ' = ' . $db->quote('system'))
->where($db->quoteName('element') . ' = ' . $db->quote('example_postinstall_messages'));
$db->setQuery($query);
$plugin = $db->loadObject();
// Enable the plugin
$query->clear()
->update($db->quoteName('#__extensions'))
->set($db->quoteName('enabled') . ' = 1')
->where($db->quoteName('type') . ' = ' . $db->quote('plugin'))
->where($db->quoteName('folder') . ' = ' . $db->quote('system'))
->where($db->quoteName('element') . ' = ' . $db->quote('example_postinstall_messages'));
$db->setQuery($query);
$db->execute();
// Redirect a user to the plugin configuration page
$url = 'index.php?option=com_plugins&task=plugin.edit&extension_id=' . $plugin->extension_id;
JFactory::getApplication()->redirect($url);
}
Последнее, что необходимо сделать, это вставить конфигурационные данные в таблицу #_postinstall_messages
. Для этого мы используем тэг scriptfile
в файле манифеста (установочный XML-файл расширения):
<scriptfile>script.php</scriptfile>
Для того, чтобы com_postinstall
мог выполнить наш скрипт во время установки или обновления нашего расширения, мы должны обновить следующие поля в таблице:
- action
и condition_method
добавив названия соответствующих функций, которые мы определили ранее как example_postinstall_action()
и example_postinstall_condition()
- action_file
и condition_file
добавив название файла, который содержит соответствующие функции (в нашем случае actions.php).
Кроме того при удалении плагина необходимо позаботиться об удалении всех связанных с ним сообщений.
Вот как выглядит класс в файле script.php:
/**
* Plugin installer script
*
* @package Example_Postinstall_Messages
* @since 1.0
*/
class plgSystemExample_Postinstall_MessagesInstallerScript
{
/**
* Method to run on the plugin install.
*
* @param object $parent Parent object.
*
* @return void
*/
public function install($parent)
{
$db = JFactory::getDbo();
$query = $db->getQuery(true)
->insert($db->quoteName('#__postinstall_messages'))
->columns('`extension_id`,
`title_key`,
`description_key`,
`action_key`,
`language_extension`,
`language_client_id`,
`type`,
`action_file`,
`action`,
`condition_file`,
`condition_method`,
`version_introduced`,
`enabled`')
->values('700,
"PLG_SYSTEM_EXAMPLE_POSTINSTALL_MESSAGES_POSTINSTALL_TITLE",
"PLG_SYSTEM_EXAMPLE_POSTINSTALL_MESSAGES_POSTINSTALL_BODY",
"PLG_SYSTEM_EXAMPLE_POSTINSTALL_MESSAGES_POSTINSTALL_ACTION",
"plg_system_example_postinstall_messages",
1,
"action",
"site://plugins/system/example_postinstall_messages/postinstall/actions.php",
"example_postinstall_action",
"site://plugins/system/example_postinstall_messages/postinstall/actions.php",
"example_postinstall_condition",
"3.2.0",
1');
$db->setQuery($query);
$db->execute();
}
/**
* Method to run on the plugin uninstall.
*
* @param object $parent Parent object.
*
* @return void
*/
public function uninstall($parent)
{
$db = JFactory::getDbo();
$query = $db->getQuery(true)
->delete($db->quoteName('#__postinstall_messages'))
->where($db->quoteName('language_extension') . ' = ' . $db->quote('plg_system_example_postinstall_messages'));
$db->setQuery($query);
$db->execute();
}
}
Обратите внимание, что мы также вставили в таблицу языковые константы, которые будут формировать наше сообщение:
PLG_SYSTEM_EXAMPLE_POSTINSTALL_MESSAGES_POSTINSTALL_TITLE="Доступен плагин примера послеустановочных сообщений."
PLG_SYSTEM_EXAMPLE_POSTINSTALL_MESSAGES_POSTINSTALL_BODY="После клика на кнопку ниже:<ul><li>Joomla! включит этот плагин.</li><li>Вы будете перенаправлены на страницу настроек плагина.</li></ul>"
PLG_SYSTEM_EXAMPLE_POSTINSTALL_MESSAGES_POSTINSTALL_ACTION="Включить плагин"
Вот как выглядит послеустановочное сообщение, связанное с нашим плагином.
На этом все. Удачи в разработке!