Monday, 06 August 2012 17:45

Создаем простой Joomla плагин

Не так давно я получил вопрос от пользователя какой лучший способ добавить некоторые стили CSS для Joomla шаблона. Я ответил, что один из простых и самых лучших способов добавления дополнительных стилей CSS на ваш сайт будет создание простого Joomla плагина. Так как иногда довольно часто приходиться обновлять шаблон на новые версии, чтобы не редактировать постоянно главный CSS файл можно воспользоваться таким способом.

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

Что такое плагин?

В Joomla есть 5 типов расширений: компоненты, модули, плагины, шаблоны и языки. Плагины сами еще делятся несколько видов:

  1. System плагины для выполнения действий основанных на системе
  2. Content плагины, которые управляют содержимым
  3. Authentication плагины, которые позволяют альтернативные методы аутентификации
  4. User плагины, для выполнения действий, основанных на пользовательские события
  5. Editor плагины, для пользовательских типов редакторов
  6. Editor-xtd плагины, для добавления функций в процессе редактирования
  7. Search плагины, для добавления различных типов поиска
  8. Component плагины, которые добавляют функциональность для конкретных расширений

Мы будем создавать system плагин. Каждый плагин типа может выполнять функции для определенных событий. Эти конкретные события, изложенные в документации Joomla API.

Требования для System плагина

Плагин является относительно простым куском кода, но есть несколько вещей, которые необходимы для того чтобы пройти валидность при установке на Joomla. Мы создадим Joomla 1,7 совместимый плагин, но нет большой разницы при создании например для Joomla 2,5 или других версий.

  1. Создайте папку с именем "customcss" в фолдере где установлена Joomla plugins/system folder
  2. В папке создаем два файла: customcss.php и customcss.xml

code01

XML файл

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

<?xml version="1.0" encoding="utf-8"?>
<extension version="1.7.0" type="plugin" group="system" method="upgrade">
  <name>System - CustomCSS</name>
  <creationDate>November 6, 2011</creationDate>
  <author>Clasny, LLC</author>
  <authorUrl>http://www.clasny.com</authorUrl>
  <copyright>(C) 2010 - 2012 Clasny, LLC. All rights reserved.</copyright>
  <license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
  <version>2.0</version>
  <description>Allows the addition of custom CSS to your site</description>
  <files>
    <filename plugin="customcss">customcss.php</filename>
  </files>
  <config>
    <fields name="params">
      <fieldset name="basic">
        <field name="sitecss" type="textarea" default="30" label="Site CSS" description="The custom CSS to be added to the Site" />
        <field name="admincss" type="textarea" default="30" label="Admin CSS" description="The custom CSS to be added to the Admin" />
      </fieldset>
    </fields>
  </config>
</extension>

Давайте разберем этот файл чтобы понять что к чему:

  <?xml version="1.0" encoding="utf-8"?>

Первая строка определяет что это XML-формат в кодировке utf-8. Следующая строка открывающего тега для элемента расширения и содержит различные атрибуты: версия, тип, группа, и метод.

<extension version="1.7.0" type="plugin" group="system" method="upgrade">

Версия показывает, что это предназначено для Joomla 1.7 и тип указывает что это плагин, группа указывает что это system плагин, а также метод обновления означает, что этот плагин может быть обновлен вместо того чтобы удалять старую и устанавливать новую версию. Следующие несколько строк содержат элементы, описывающие имя плагина, и автора подробно и т.д.

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

Файлы элементов могут содержать имя файла элементов, а также папку элементов, но для нашего простого плагина нужно только один элемент файла. Он имеет единственный атрибут подключаемый модуль, который определяет имя файла заключенного в customcss.php как фактическом файле плагина.

<config>
  <fields name="params">
    <fieldset name="basic">
      <field name="sitecss" type="textarea" rows="10" cols="30" default="" label="Site CSS" description="The custom CSS to be added to the Site" />
      <field name="admincss" type="textarea" rows="10" cols="30" default="" label="Admin CSS" description="The custom CSS to be added to the Admin" />
    </fieldset>
  </fields>
</config>

Последний блок XML-кода определяет пользовательские параметры, которые мы хотим сделать доступными, когда мы изменяем свойства этого плагина через плагин менеджер администрации Joomla. Есть несколько встроенных типов полей, таких как текст, радио и т.д. Полный список можно найти в Joomla Документации. В нашем примере, мы хотим использовать два текстовых поля.

PHP файл

Функционирование происходит в файле PHP. Для добавления наших условий, стили CSS это относительно простой кусок кода:

<?php
/**
* @version   1.0
* @author    Clasny http://www.clasny.com
* @copyright Copyright (C) 2010 - 2012 Clasny, LLC
* @license   http://www.gnu.org/licenses/gpl-2.0.html GNU/GPLv2 only
*/
 
// no direct access
defined('_JEXEC') or die('Restricted index access');
 
jimport('joomla.plugin.plugin');
 
class plgSystemCustomCSS extends JPlugin {
 
  public function onAfterInitialise() {
 
  $app =& JFactory::getApplication();
  $doc =& JFactory::getDocument();
 
  if ($app->isAdmin()) {
      // we are in the administrator
      $doc->addStyleDeclaration( $this->params->get('admincss',''));
    } else {
      // we are in the frontend site      
      $doc->addStyleDeclaration( $this->params->get('sitecss',''));
    }
  }
}

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

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

Это защита от доступа к файлу, от недобросовестных людей.

jimport('joomla.plugin.plugin'); 

jimport для загрузки и доступа.

 class plgSystemCustomCSS extends JPlugin {

Определение класса является важной частью плагина, следует использовать следующий синтаксис: plg[plugin-type][plugin-name] а в нашем случае это plgSystemCustomCSS. Этот класс также должен расширять JPlugin для обеспечения всех плагинов по умолчанию.

$app =& JFactory::getApplication();
$doc =& JFactory::getDocument(); 

Эти две строки текущий объект приложения и объект документа, который использует Joomla.

 if ($app->isAdmin()) {
  // we are in the administrator
  $doc->addStyleDeclaration( $this->params->get('admincss',''));
} else {
  // we are in the frontend site      
  $doc->addStyleDeclaration( $this->params->get('sitecss',''));
}

Вот где происходит реальная работа. Если мы находимся в админке Joomla, то мы получаем значение, хранящееся в "admincss" поле для параметров плагина. Это значение затем передается в addStyleDeclaration () метод объекта документа. AddStyleDeclartion () метод является вспомогательным методом, который позволяет добавлять произвольные фрагменты кода CSS для HTML документа, который представлен в браузере.

Установка

Один из очень удобных новых возможностей Joomla 1.7 является возможность "Discover" расширения, которые находятся в файловой системе, но фактически не установлены в Joomla еще. Предполагая, что вы создали свою папку и файлы в вашей Joomla директории сайта, вы можете просто войти в администраторскую зону и перейти в Менеджер расширений в верхнем меню. Просто нажмите на "Discover" суб-меню. Если вы ничего не видите в списке, нажмите "Discover" кнопку на панели инструментов, чтобы обновить процесс обнаружения.

code02

Вы должны увидеть строку в таблице для созданного CustomCSS плагина. Обратите внимание на отображаемое имя, все это определенно в customcss.xml. Этот файл используется для описания всех атрибутов плагина еще до того, как он полностью установлен. Чтобы установить новый плагин, просто поставьте галочку слева от названия, и нажмите кнопку "Установить" на панели инструментов. Вот и все, что нужно для установки плагина.

Настройки и тестирование

Для настроек плагина, мы должны войти в меню расширений плагины. После установки плагина, он не включен поэтому щелкните на него для редактирования свойств.

code03

Чтобы проверить если плагин работает, добавим в поле CSS код:

#main .blog-featured .items-leading h2 {
font-size: 5em;
font-family: Helvetica, Arial,sans-serif;
font-weight: bold;
} 

Этот CSS заменит ведущие теги h2. Вы можете видеть, по умолчанию текст "Joomla" на главной странице очень маленький. При этом стилями CSS мы меняем размер шрифта.

code04

Убедитесь, что вы включили плагин "Enabled", иначе плагин не будет работать.

Исходники

Прочитано 4435 раз