Создание контент плагина

05/06/2009 Разработка модуля Joomla 2.5

Существует достаточно много способностей использования Контент Плагина. Они имеют отношение к показу Вашего контента и Ваших статей. Для создания контент плагина понадобиться как минимум два файла: XML и PHP. Поскольку есть много различий между двумя Контент Плагинами в PHP файле рассмотрим их оба. Так же к плагину можно добавить файл локализации .ini.

XML файл

Файл XML называют так же как и файл PHP, и он является одним из необходимых файлов. Этот файл всегда начинается с тегов XML, где определятся кодировка:

<?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE install PUBLIC 
  "-//Joomla! 1.5//DTD plugin 1.0//EN" "http://dev.joomla.org/xml/1.5/plugin-install.dtd">

Что бы определить что устанавливается именно плагин, относящийся к контенту добавляем строчку:

<install version="1.5" type="plugin" group="content">
 

type определит что это плагин, group определит что он относится к Контент Плагину.

Дальше можно добачить немного информации о разработчике и плагине:

 

<name>Имя Контент Плагина</name>
<creationDate>Дата создания</creationDate>
<author>Имя автора</author>
<authorEmail>e-mail автора</authorEmail>
<authorUrl>website автора</authorUrl>
<copyright>Copyright</copyright>
<license>Лицензия, для примера GNU/GPL</license>
<version>Версия плагина</version>
<description>Описание плагинаr</description>

Теперь подключаем PHP файл к Контент Плагину. Название этого файла должно быть таким же как и XML файла.

<files>
   <filename plugin="nameofplugin">nameofplugin.php</filename>
</files>

Как видите имя файла еще ставится в теге <filename plugin="nameofplugin">.  Если нужно использовать больше одного файла, то поместите их в теги <filename> между тегами <files> и </files>.

Подключени локализации производится с помощью тегов <languages>

<languages>
   <language tag="en-GB">en-GB.plg_content_nameofplugin.ini</language>
</languages>

Опционально, Вы можете добавить свои параметры к Плагину, это  делается так:

<params>
   <param name="paramname" type="typeofparameter" default="defaultsetting" label="title" description="description"/>
</params>
  • name - название параметры. Это название будет использоваться в PHP файле;
  • type - тип параметра, подробнее читайе Joomla Standard parameter types;
  • default - значение по умолчанию;
  • label - название параметра, отображаемое в Менеджере Плагинов при редактировании;
  • description - описание раметра;

Если Вы не используете никаких параметров, вставьте следующий тег:

<params/>

Конец установочного XML файла заканчивается тегом:

</install>

PHP файл

Начинается код плагина, как и все файлы Joomla с защиты:

// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

После этого Вы должны подключить главный плагин Joomla из библиотеки:

jimport( 'joomla.plugin.plugin' );

Что бы указать что используется Контент Плагин, добавьте следующий код:

class plgContentNameofplugin extends JPlugin {

Обратите внимания как используютя заглавные буквы. Вы должны заменить Nameofplugin на название своего плагина.

Теперь пришло времы создавать сам плагин:

/**
 * Constructor
 *
 * Для PHP 4 мы не должны использовать __constructor как constructor для плагинов
 * потому что функция func_get_args ( void ) возвратит копии всех переданных ссылок параметров в  NOT.
 * Это вызывает проблемы с системой перекрестных ссылок. 
 * @param object $subject Объект наблюдения
 * @param object $params  Объект, который содержит параметры
 * @since 1.5
 */
        function plgContentNameofplugin( &$subject, $params )
        {
                parent::__construct( $subject, $params );
        }

Теперь нужно выбрать когда будет выводится плагин. Можно выбрать из следующего:

  • onBeforeContentSave - Это событие возникает перед тем как контент запишется в БД;
  • onAfterContentSave - Это событие возникает после того как контент запишется в БД;
  • onPrepareContent - Это первый этап в подготовке материала для вывода и это самое основное событие для плагинов, ориентированных на работу с материалами. На этом этапе выполняется большая часть их работы. Перед тем, как вывести текст на экран, он может быть обработан в соответствии с вашими требованиями и параметрами самого материала;
  • onAfterDisplayTitle - Событие возникает для информирования плагина о возможности вывести текст между заголовком и текстом материала;
  • onBeforeDisplayContent - Это событие для определения, что должно быть размещено непосредственно перед сгенерированным контентом;
  • onAfterDisplayContent - Событие возникает для информирования плагина о выводе информации непосредственно после сгенерированного материала;

Более подробную информацию о событиях можно найти здесь - (Joomla) Content Events for Plugin System.

onBeforeContentSave и onAfterContentSave

Используйте следующий код:

function onBeforeContentSave( &$article, $isNew )
        {
                global $mainframe;
                //добавляем код плагина здесь
                return true;
        }

Параметры article и isNew должны содержать следующее:

  • article - Ссылается на объект JTableContent, который сохраняетсятся и содержит данные статьи.
  • isNew - Переменная (boolean), которая возвращает истину, если материл был создан.

onPrepareContent

function onPrepareContent( &$article, &$params, $limitstart )
        {
                global $mainframe;
                //добавлеям код плагина здесь                 
                //не возвращает значения
        }

Параметры article, params и limitstart содерджат следующее:

  • article - Ссылается на статью, которая выполняется представлением.
  • params - Ссылается на ассоциативный массив соответствующих параметров.
  • limitstart - Целое число,  определяющее "страницу" контента, которая должна быть сгенерирована.

onAfterDisplayTitle, onBeforeDisplayContent и onAfterDisplayContent

Для них код будет идентичен:

function onAfterDisplayContent( &$article, &$params, $limitstart )
        {
                global $mainframe;
                //добавлеям код плагина здесь
                return '';
                //возвращает строковое значение. Возвращенное значение из этого события отображается в placeholder. 
                //Большинство шаблонов отображает placeholder после разделителя материала.
        }

Параметры article, params и limitstart содерджат следующее:

  • article - Ссылается на статью, которая выполняется представлением.
  • params - Ссылается на ассоциативный массив соответствующих параметров.
  • limitstart - Целое число,  определяющее "страницу" контента, которая должна быть сгенерирована.

Пример PHP файла

Этот Контент Плагин позволит отображать модули в области контента. Эта функция будет включена в Joomla 1.6 и уже доступна начиная с версии 1.5.10.

<?php
// 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 = '/{loadposition\s*.*?}/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 файл(ы)

Для локализации плагина удобно создавать ini файлы. В которых будут хранится значения переменных, выводящих текст.

MODE=Mode
SELECT HOW THE EMAILS WILL BE DISPLAYED=Select how the e-mails will be displayed
NONLINKABLE TEXT=Nonlinkable text
AS LINKABLE MAILTO ADDRESS=As linkable mailto address

Советы:

  • В PHP файлах часто забывают ставить (;) в конце строки, которая естественно будет вызывать ошибку. Проверяйте это регулярно, перед тем как тестировать свой плагин и это избавит Вас от многих ошибок.
  • Забодьтесь о том что бы правильно объявлять параметры в XML файле. Все параметры которые объявляете должны быть закрыты правильно, тегом </param>.
  • Тестируйте плагины на локальном компьютере, это поможет сократить Ваше время и нервы. Вы сможете быстро исправить ошибку.
  • Типичный архив плагина содержит следующие файлы:
    • nameofplugin.XML
    • nameofplugin.PHP
    • en-GB.plg_content_nameofplugin.ini

 



0 

О Joomla!

Документация

Документация