Файл XML для плагина Joomla
Название файла XML должно быть таким же, как у файла PHP (за исключением расширения); этот файл - один из двух файлов, необходимых для создания плагина Joomla. Начните создание этого файла с декларации тега XML и Document Type Definition (DOCTYPE ).
Чтобы указать тип плагина как "плагин для контента", добавьте в файл XML эту строку:
Тип плагина (type) укажет на то что данное расширение является плагином, группа (group) указывает, в какую группу должен быть помещен плагин. В данном случае это группа content. После этого добавьте информацию о вас (об авторе) в XML-файл плагина.
Теперь настало время добавить информацию про файл PHP в XML данные нового плагина. Имя этого файла должно быть такм же как имя файла XML. Если нужно, Вы можете добавить больше файлов для своего плагина, например изображения и скрипты JavaScript. Просто добавьте новую строку между files и /files, а затем поместите тег файла между тегами filename.
Некоторые файлы, такие как .js или .css, не не распознаются автоматически и вызовут ошибку, если Вы попытаетесь установить плагин. Для этого создайте новую папку в директории плагина, затем скопируйте файлы в папку. Добавьте строку с записью для папки в тег files. Конечно было бы проще управлять файлами .js и .css из файла шаблона, но если файлы принадлежат плагину, то лучше если они будут прописаны здесь.
Для интернационализации мы будем использовать языковые файлы. Это не обязательно, но пользователям из других стран понравится если они могут легко перевести Ваш плагин на свой родной язык. Языковые файлы плагина всегда устанавливаются в папку administrator/languages/xx-XX/, где xx-XX - код языка, установленного в Joomla.
Если нужно, Вы также можете добавить некоторые дополнительное параметры плагина.
- name: название параметра. Будет использоваться в файле PHP
- type: выберите тип параметра
- default: значение по умолчанию
- label: название параметра, показывается при редактировании свойств плагина в менеджере плагинов.
- description: текст всплывающей подсказки для этого параметра.
Если Вам не нужно использовать параметры, используйте следующий тег:
Обязательно закончите файл XML таким образом:
Файл PHP для плагина Joomla
Начните свой файл PHP с информации о лицензии и об авторе плагина Joomla для контента.
/**
* @version $Id: nameofplugin.php revision date lasteditedby $
* @package Joomla
* @subpackage Content
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
* Joomla! is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/
Затем обязательно поместите следующий код в самое начало кода PHP:
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
Это предотвращает прямое обращение к этому файлу.
После этого нужно импортировать файл библиотеки Joomla!.
jimport( 'joomla.plugin.plugin' );
Чтобы указать что Вы создаете плагин для контента, добавьте следующий код:
class plgContentNameofplugin extends JPlugin {
Пожалуйста заметьте использование заглавных букв. Вам нужно заменить Nameofplugin названием Вашего плагина.
Теперь, пришло время создавать непосредственно код плагина.
/**
* Constructor
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
* This causes problems with cross-referencing necessary for the observer design pattern.
*
* @param object $subject The object to observe
* @param object $params The object that holds the plugin parameters
* @since 1.5
*/
function plgContentNameofplugin( &$subject, $params )
{
parent::__construct( $subject, $params );
}
Теперь выберите, в какой момент плагин должен быть выполнен. Вы можете выбрать одно из следующих событий:
- onBeforeContentSave: событие, которое наступает непосредственно перед тем, как контент сохранен в базу данных.
- onAfterContentSave: событие, которое наступает после того как контент сохранен в базу данных.
- onPrepareContent: первая стадия подготовки контента для вывода и чаще всего "точка входа" для контент-плагинов.
- onAfterDisplayTitle: запрос об информации, которая должна быть выведена между заголовком и телом статьи.
- onBeforeDisplayContent: запрос об информации, которая должна быть выведена непосредственно перед созданным контентом.
- onAfterDisplayContent: запрос об информации, которая должна быть выведена непосредственно после созданного контента.
onBeforeContentSave
Используйте следующий код:
function onBeforeContentSave( &$article, $isNew )
{
$mainframe=JFactory::getApplication();
//add your plugin codes here
return true;
}
Параметры article и isNew должны иметь следующие значения:
- article: ссылка на сохраняемый объект JTableContent, который, в свою очередь, держит данные статьи.
- isNew: булева переменная, которая имеет значение true, если происходит подготовка создания контента.
onAfterContentSave
Используйте следующий код:
function onAfterContentSave( &$article, $isNew )
{
$mainframe=JFactory::getApplication();
//add your plugin codes here
return true;
}
Параметры article и isNew должны иметь следующие значения:
- article: ссылка на сохраняемый объект JTableContent, который, в свою очередь, держит данные статьи.
- isNew: булева переменная, которая имеет значение true, если создание контента завершено.
onPrepareContent
Используйте следующий код:
function onPrepareContent( &$article, &$params, $limitstart )
{
$mainframe=JFactory::getApplication();
//add your plugin codes here
//no return value
}
Параметры article, params и limitstart должны иметь следующие значения:
- article: ссылка на статью, которая создается видом.
- params: ссылка на ассоциативный массив соответствующих параметров. Вид определяет данные и передает эту информацию.
- limitstart: число, которое определяет "страницу" контента, который должен быть создан. Заметьте, что в контексте видов, которые не производят вывод HTML, страница это абстрактное понятие, которое зависит от контекста.
onAfterDisplayTitle
Используйте следующий код:
function onAfterDisplayTitle( &$article, &$params, $limitstart )
{
$mainframe=JFactory::getApplication();
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}
Параметры article, params и limitstart должны иметь следующие значения:
- article: ссылка на статью, которая обрабатывается видом.
- params: ссылка на ассоциативный массив соответствующих параметров. Вид определяет данные и передает эту информацию.
- limitstart: целое число, которое определяет "страницу" контента, который должен быть создан. Заметьте, что в контексте видов, которые не производят вывод HTML, страница это абстрактное понятие, которое зависит от контекста.
onBeforeDisplayContent
Используйте следующий код:
function onBeforeDisplayContent( &$article, &$params, $limitstart )
{
$mainframe=JFactory::getApplication();
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}
Параметры article, params и limitstart должны иметь следующие значения:
- article: ссылка на статью, которая обрабатывается видом.
- params: ссылка на ассоциативный массив соответствующих параметров. Вид определяет данные и передает эту информацию.
- limitstart: целое число, которое определяет "страницу" контента, который должен быть создан. Заметьте, что в контексте видов, которые не производят вывод HTML, страница это абстрактное понятие, которое зависит от контекста.
onAfterDisplayContent
Используйте следующий код:
function onAfterDisplayContent( &$article, &$params, $limitstart )
{
$mainframe=JFactory::getApplication();
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}
Параметры article, params и limitstart должны иметь следующие значения:
- article: ссылка на статью, которая обрабатывается видом.
- params: ссылка на ассоциативный массив соответствующих параметров. Вид определяет данные и передает эту информацию.
- limitstart: целое число, которое определяет "страницу" контента, который должен быть создан. Заметьте, что в контексте видов, которые не производят вывод HTML, страница это абстрактное понятие, которое зависит от контекста.
Образец файла PHP - Пример
Этот пример файла PHP для плагина Joomla содержит код плагина для загрузки модулей в контент. Это плагин, сделанный для того, чтобы выводить модули в составе статьи.
// The general information at the top of each file
/**
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2009 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License, see LICENSE.php
*/
// No direct access allowed to this file
defined( '_JEXEC' ) or die( 'Restricted access' );
// Import Joomla! Plugin library file
jimport('joomla.plugin.plugin');
//The Content plugin Loadmodule
class plgContentLoadmodule extends JPlugin
{
/**
* Plugin that loads module positions within content
*/
// onPrepareContent, meaning the plugin is rendered at the first stage in preparing content for output
public function onPrepareContent( &$row, &$params, $page=0 )
{
// A database connection is created
$db = JFactory::getDBO();
// simple performance check to determine whether bot should process further
if ( JString::strpos( $row->text, 'loadposition' ) === false ) {
return true;
}
// expression to search for
$regex = '//i';
// check whether plugin has been unpublished
if ( !$this->params->get( 'enabled', 1 ) ) {
$row->text = preg_replace( $regex, '', $row->text );
return true;
}
// find all instances of plugin and put in $matches
preg_match_all( $regex, $row->text, $matches );
// Number of plugins
$count = count( $matches[0] );
// plugin only processes if there are any instances of the plugin in the text
if ( $count ) {
// Get plugin parameters
$style = $this->params->def( 'style', -2 );
$this->_process( $row, $matches, $count, $regex, $style );
}
// No return value
}
// The proccessing function
protected function _process( &$row, &$matches, $count, $regex, $style )
{
for ( $i=0; $i < $count; $i++ )
{
$load = str_replace( 'loadposition', '', $matches[0][$i] );
$load = str_replace( '{', '', $load );
$load = str_replace( '}', '', $load );
$load = trim( $load );
$modules = $this->_load( $load, $style );
$row->text = preg_replace( '{'. $matches[0][$i] .'}', $modules, $row->text );
}
// removes tags without matching module positions
$row->text = preg_replace( $regex, '', $row->text );
}
// The function who takes care for the 'completing' of the plugins' actions : loading the module(s)
protected function _load( $position, $style=-2 )
{
$document = &JFactory::getDocument();
$renderer = $document->loadRenderer('module');
$params = array('style'=>$style);
$contents = '';
foreach (JModuleHelper::getModules($position) as $mod) {
$contents .= $renderer->render($mod, $params);
}
return $contents;
}
}
Файл(ы) INI
Для интернационализации вашего плагина Joomla удобно использовать языковые файлы INI. Вы можете добавить в языковой файл все тексты, которые видит пользователь, в таком порядке. Сейчас это может казаться немного непонятным, но читайте далее.
- Тег описания для XML
- Метка и описание для XML из параметров
- Метод JText::_( 'string' ), используемый плагином
Вам понадобится создать два файла: один для администраторского интерфейса и один для пользовательского интерфейса. Обозначение должно соответствовать пути расширения. Например, если вы создаете плагин для контента, названный sample, и он установлен в plugins/content/example, то тогда наши файлы нужно назватьтак: en-US.plg_content_example.ini (для пользовательского интерфейса сайта Joomla) и en-US.plg_content_example.sys.ini (языковой файл для администраторского интерфейса).
Начните свой файл INI со следующих строк:
# $Id: en-GB.plg_content_nameofplugin.ini
# Joomla! Project
# Copyright (C) 2005 - 2007 Open Source Matters. All rights reserved.
# License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
# Note : All ini files need to be saved as UTF-8 - No BOM
Конечно, Вы можете добавить и другую информацию, например, данные об авторе плагина Joomla. Пример языкового INI файла для администраторского интерфейса:
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT
PLG_CONTENT_EXAMPLE_LINKABLE_TEXT
Локализованные строки, переведенные в файле INI:
PLG_CONTENT_EXAMPLE_MODE=Mode
PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED=Select how the e-mails will be displayed
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT=Nonlinkable text
PLG_CONTENT_EXAMPLE_LINKABLE_TEXT=As linkable mailto address
Считается что keit использовать LOCALIZED_TAGS в верхнем регистре, без пробелов, и начинать их с имени расширения чтобы избежать пересечения с другими строками. Локализованные теги могут тогда быть переведены на разные языки. Если Вы хотите сделать плагин для контента доступным на большем количестве языков, сначала добавьте их в файл XML. Затем создайте файл INI и замените часть после =, например русский перевод выглядел бы как:
PLG_CONTENT_EXAMPLE_MODE=Режим
PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED=Выберите как отображать e-mail
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT=Не создавать ссылки
PLG_CONTENT_EXAMPLE_LINKABLE_TEXT=Текст как ссылка на e-mail
Пример файла для пользовательского интерфейса. На Joomla 2.5 Вы должны создать отдельный файл для пользовательского интерфейса как описано выше. Например:
PLG_CONTENT_EXAMPLE_LINKNAME="The Name of the Link Goes Here!"
В файле PHP плагина Вы должны загрузить языковой файл:
// Load user_profile plugin language
$lang = JFactory::getLanguage();
$lang->load('plg_content_simpleattachment', JPATH_ADMINISTRATOR);
echo $JText::_('PLG_CONTENT_EXAMPLE_LINKNAME');
