Перевод статьи Building your First ExpressionEngine Plugin
Не важно, насколько превосходна Ваша система управления контентом, наступит момент, когда вам потребуется что-то, на что она просто-напросто неспособна. В этой статье мы рассмотрим способ создания плагина для ExpressionEngine, который будет отвечать вашим нуждам.
Заметки о версиях. Совсем недавно, Ellislab, создатели ExpressionEngine, объявили официальную дату выхода ExpressionEngine 2.0, которая назначена на первое декабря 2009 года. Обратите внимание, что эта статья написана специально по версии 1.6.х. в версии 2.0 изменятся некоторые детали, такие как пути к файлам и глобальные объекты. Несмотря на эти изменения, основное приложение и подход к созданию плагинов для ExpressionEngine останется без изменений.
Типы адонов для ExpressionEngine.
Как все доступные нормальные системы управления, ExpressionEngine включает в себя несколько возможностей для разработчика добавить ему функциональности, которой нет в нем по умолчанию. В отличие от популярной системы типа WordPress, ExpressionEngine позволяет называть эти аддоны в зависимости от того, как они взаимодействуют с сайтом. Существует три основных способа, как вы можете добавить функциональности ExpressionEngine 1.6.х. это Плагины, Расширения и Модули. Плагины, в основном используются при изменении кода шаблона и чаще всего являются начальными шагами в работе. Расширения обычно подправляют функциональность на конечных этапах работы, или через Control Panel используя зацепки в системе. Модули обладают большим полем применения, у них есть свое место в Control Panel и также могут быть использованы для основной работы с веб-сайтами ExpressionEngine. Модули могут полноценными аддонами внутри ExpressionEngine и используют членство, шаблоны, базы данных и так далее.
Необходимые навыки.
Вот что вам поможет перед тем, как продвигаться дальше:
- Как настроить и установить ExpressionEngine в среде разработчика.
- Основные понятия Контрольной панели (Control Panel) ExpressionEngine и парсинг шаблонов.
- Основные понятия РНР и Объектно-ориентированного программирования.
Наш плагин.
Для нашей статьи мА собираемся создать простой плагин, который будет сканировать проходящую через него информацию и упаковывает некоторые строки HTML-тэгами. Это очень простое приложение для плагина ExpressionEngine, которое продемонстрирует вам как это легко – начать разработку плагинов. Наш плагин будет использоваться для поиска и замены акронимов, которые мы использовали как разработчики. Для наглядности мы будем использовать три из них: HTML, CSS и RSS. Назовем плагин “Auto Acronym”.
Как начать?
Наилучшим для начала разработки Аддона для ExpressionEngine является официальная документация ExpressionEngine (перевод). Перед тем, как окунетесь с головой в разработку приложений для ExpressionEngine, вам действительно стоит прочитать руководство, которое, при условии следования инструкциям, поможет поддержать систему в рабочем состоянии. «Руководство по эксплуатации» включает такие понятия как присвоение имени условным обозначениям, работа и безопасность. Потратьте несколько минут и прочитайте Руководство по разработке Аддонов для ExpressionEngine.
Итак, будем считать, вы прочитали, и теперь готовы к тому, чтобы ознакомиться с тем, как мы в действительности создадим Плагин и насколько это просто.
Части мозаики.
Для каждого Плагина требуется один класс и как минимум одна функция. Название условных обозначений является очень специфичной функцией, и взаимодействует с именем файла, именем класса и тэгами ExpressionEngine. Имя файла включает имя плагина и заменяет все пробелы подчеркиваниями, ставя в начале «pi.”. все буквы должны быть в нижнем регистре. В итоге, наш файл будет называться “pi.auto_acronym..php”. Все плагины ExpressionEngine сохраняются в одной директории, которая находится в system/plugins (Нет! Вы только представьте!).
Название класса схоже с названием файла за исключением того, что первая буква – заглавная. Выглядит это так: :Auto_acronym”. Этому плагину потребуется только одна функция, которую мы назовем также как и класс. Также это будет название, которые мы будем использовать в тэгах EXpressionEngine. Тэги плагина всегда начинаются с “exp:”, который говорит разделителю шаблонов «Алле! Тут че-то надо сделать!». Следом идет название класса (все в нижнем регистре). В итоге получим: “exp:auto_acronym”. Третий сегмент тэга плагина вызывает функцию внутри класса плагина. В нашем примере мы будем использовать только одну функцию, конструктор, поэтому нам понадобится только название класса. Итак, вот что нам известно о нашем плагине:
Auto Acronym
Название файла: pi.auto_acronym.php
Название класса и конструктора: Auto_acronym
Тэг ExpressionEngine: {exp:auto_acronym}
Включение этого в код.
Давайте посмотрим, как выглядит наш код:
<?php
class Auto_acronym
{
function Auto_acronym()
{
}
}
/* End of file pi.auto_acronym.php */
/* Location: ./system/plugins/pi.auto_acronym.php */
Тем из вас, кто знаком с разработкой плагинов для WordPress, известно, что WordPress извлекает немного информации из кода комментариев, когда демонстрирует детали в Менеджере Плагинов. ExpressionEngine делает то же самое, за исключением массива внутри файла плагина. Давайте продвинемся немного вперед и добавим это к нашему вышеуказанному файлу класс и дадим этому соответствующую информацию.
<?php
$plugin_info = array(
'pi_name' => 'Auto Acronym',
'pi_version' => '1.0',
'pi_author' => 'Erik Reagan',
'pi_author_url' => 'http://erikreagan.com',
'pi_description' => 'Automatically wraps certain acronyms in the HTML <acronym> tag',
'pi_usage' => Auto_acronym::usage()
);
class Auto_acronym
{
function Auto_acronym()
{
}
}
/* End of file pi.auto_acronym.php */
/* Location: ./system/plugins/pi.auto_acronym.php */
Каждый знак массива должен явно соответствовать тому, для чего он предназначен. Последний знак, как бы то ни было, слегка отличается. Очевидно, не только строка. Это используется для того, чтобы дать понять Контрольной Панели ExpressionEngine где найти применение или простую документацию для плагина. Каждый плагин ExpressionEngine должен иметь основную документацию внутри файла плагина, для того, чтобы пользователь плагина могли просмотреть ее в Контрольной Панели и разобраться, как использовать тэги. Это делается с помощью добавления функции классу плагина, которая называется “usage” (использование). Мне нравится ставить функцию «использование» в конце класса, поэтому давайте пройдем вперед и скопируем и вставим из ExpressionEngine Plugin Docs, уберем содержимое между тэгами РНР «?>» и «<?», так как тут будет наше содержимое.
// ----------------------------------------
// Plugin Usage
// ----------------------------------------
// This function describes how the plugin is used.
// Make sure and use output buffering
function usage()
{
ob_start();
?>
<?php
$buffer = ob_get_contents();
ob_end_clean();
return $buffer;
}
Наше использование будет написано после того, как мы закончим с нашим плагином. А сейчас, давайте вставим немного текста для тестирования. Не забывайте, что этот текст будет расценен как форматированный ранее и все знаки будут конвертированы в значения HTML; HTML не будет работать. Давайте взглянем на плагин целиком:
<?php
$plugin_info = array(
'pi_name' => 'Auto Acronym',
'pi_version' => '1.0',
'pi_author' => 'Erik Reagan',
'pi_author_url' => 'http://erikreagan.com',
'pi_description' => 'Automatically wraps certain acronyms in the HTML <acronym> tag',
'pi_usage' => Auto_acronym::usage()
);
class Auto_acronym
{
function Auto_acronym()
{
}
// ----------------------------------------
// Plugin Usage
// ----------------------------------------
// This function describes how the plugin is used.
// Make sure and use output buffering
function usage()
{
ob_start();
?>
This is where our simplified documentation will go
<?php
$buffer = ob_get_contents();
ob_end_clean();
return $buffer;
}
}
/* End of file pi.auto_acronym.php */
/* Location: ./system/plugins/pi.auto_acronym.php */
Итак, у нас есть костяк файла плагина, который нам надо сохранить в директорию system/plugins, чтобы быть уверенными, что он будет правильно прочитан системой. После его сохранения мы увидим его в Admin>Utilities>Plugin Manager (Администратор – Утилиты – Управление плагинами). Если вы кликните на новый плагин, вы должны увидеть примерно такую страницу, которая содержит информацию, которую мы только что добавили к плагину.
Запуск.
Теперь, когда наш плагин правильно введен в систему ExpressionEngine, мы можем наконец-то что-то сделать. Каждый плагин возвращает некоторую форму информации. Эта информация всегда будет исходить из стандартизированных переменных, которые будет искать ExpressionEngine. Они называются “return_data” (возвращаемая информация). Первое, что мы хотим сделать – это определить ее перед нашей первой функцией внутри класса. Тогда (чисто для проверки) мы будем использовать ее внутри нашей первой функции для возврата простой строки.
class Auto_acronym
{
var $return_data = "";
function Auto_acronym()
{
$this->return_data = "Just making sure this works";
}
Теперь у нас будет возвращаться некоторое количество информации, и мы можем протестировать ее на веб-сайте. Я использую минимальный шаблон в целях тестирования, но вы можете использовать любой шаблон ExpressionEngine. Если вы вспомните наш тэг, то он выглядит следующим образом: {exp:auto_acronym}. А так как у нас только одна функция нам нет нужды использовать третий сегмент плагина. Вот как выглядит мой код шаблона, и вот что покажет мой браузер:
<h1>Plugin Tutorial</h1>
<p>{exp:auto_acronym}</p>
Конечно не Бог весть что, но мы на шаг ближе к цели. Теперь, когда мы знаем, как направить информацию назад, мы можем перейти к рассмотрению захвата информации прошедшей через наш плагин.
Обработка данных нашим Плагином.
Первый метод, на котором мы остановим наше внимание, связанный с обработкой информации это как ExpressionEngine читает информацию между тэговыми парами плагина. Если вы еще не знаете, наша тэговая пара очень схожа с тем, как работает тэговая пара HTML. У нас есть открывающий тэг, за ним идет информация, а за ней закрывающий тэг. По такому типу:
{exp:auto_acronym}
This gets processed
{/exp:auto_acronym}
ExpressionEngine позволяет легко получить эту информацию, используя Template Object (объект шаблона). В этом случае нам будет нужно сделать ее глобальной (главной, основной) внутри нашей функции, для того чтобы иметь к ней доступ. Потом мы определим нашу переменную, вызывая проигрывание переменной “tagdata” (информация тэгов). Эта переменная представляет собой информацию между открывающей и закрывающей тэговыми парами. Взгляните:
function Auto_acronym()
{
global $TMPL;
$data = $TMPL->tagdata;
}
А сейчас, давайте сделаем кое-что очень простое с нашей информацией и сделаем ее выделенной полужирным шрифтом, так как теперь это просто текст. Мы добавим тэги <strong> вокруг нее, затем определим нашу переменную return_data. Вот так должны выглядеть наш код, шаблон и выполненная страница:
Plugin: Плагин
function Auto_acronym()
{
global $TMPL;
$data = '<strong>'.$TMPL->tagdata.'</strong>';
$this->return_data = $data;
}
Template: Шаблон
<h1>Plugin Tutorial</h1>
{exp:auto_acronym}
<p>This gets processed</p>
{/exp:auto_acronym}
Выполненное в браузере:
Сделайте уже хоть что-нибудь!
Ладно, ладно. Давайте уже немного повеселимся с этим. Наша цель относительно данного плагина – сканировать проходящую через него информацию на общие акронимы веб-дизайна. Я уже упоминал, что мы будем использовать три для статьи: HTML, CSS и RSS. Первое что мы хотим сделать – это вставить их в массив внутри нашей функции. Помните, что если мы использовали массив в плагине и у нас были множественные функции в плагине нам, возможно, придется сохранить это вне конструктора, так, чтобы это могло быть вызвано любой функцией.
function Auto_acronym()
{
global $TMPL;
$data = $TMPL->tagdata;
$acronyms = array(
'HTML' => 'HyperText Markup Language',
'CSS' => 'Cascading Style Sheets',
'RSS' => 'Really Simple Syndication'
);
}
Теперь, когда наша тэговая информация с массивом акронимов готова, нам нужно запустить петлю “foreach()” для каждого из акронимов. Первое что мы сделаем – это пропустим акроним и тэговую информацию через функцию “strpos()” для того, чтобы убедиться, что акроним действительно присутствует в нашей строке. Если ваш словарь акронимов включает в себя сотни значений, и вы пропускаете большое количество статей, это может привести к риску ненужного времени обработки. Если, и только если акроним находится внутри нашей тэговой информации, мы используем функцию “str_replace()” для того, чтобы уже добавить тэг «акроним» <acronym>. После петли “foreach()” мы определим нашу переменную возвратной информации (return_data). Вот как это выглядит:
function Auto_acronym()
{
global $TMPL;
$data = $TMPL->tagdata;
$acronyms = array(
'HTML' => 'HyperText Markup Language',
'CSS' => 'Cascading Style Sheets',
'RSS' => 'Really Simple Syndication'
);
foreach ($acronyms as $short => $long)
{
if (strpos($data, $short) !== FALSE)
{
$data = str_replace($short, '<acronym title="'.$long.'">'.$short.'</acronym>', $data);
}
}
$this->return_data = $data;
}
Для того, чтобы правильно протестировать, нам нужно изменить наш шаблон, для того чтобы наши акронимы действительно присутствовали в нем. Я собираюсь изменить шаблон следующим образом:
<h1>Plugin Tutorial</h1>
{exp:auto_acronym}
<p>My name is Erik and I am an addict. I stay up late into the night marking up HTML and CSS with magical alignment.
Whitespace speaks volumes of my care and finesse of the code. My RSS subscribers wait on their toes for my next
example of code beauty. Okay...not really.</p>
{/exp:auto_acronym}
Сохранение шаблона и обновление браузера представят следующую картину:
Вот уже кое-что!
Теперь, когда тэги между открывающими и закрывающими тэгами нашего плагина работают правильно, давайте рассмотрим другую опцию: пропускание информации через единичный тэг. Использование единичного тэга в плагине потребует добавления параметров, по которым информация, которая будет продолжать проходить через плагин, будет обрабатываться. Вы можете назвать параметр как вам угодно. В нашем случае мы используем следующее название и добавим его к нашему шаблону:
{exp:auto_acronym data="HTML"}
Теперь, когда у нас есть единичный тэг, мы должны найти способ как использовать его в нашем плагине. Любой параметр, который вы хотите использовать в вашем плагине, может быть выбран, используя Объект Шаблона (или Шаблон Объекта), который мы использовали ранее. Вместо возможности выбора через переменные вы должны выбрать функцию, которая называется “fetch_param()”. Мы хотим, чтобы наш плагин мог работать, используя как единичный тэг, так и тэговую пару, поэтому мы примем это в расчет, когда будем определять нашу $переменную информации ($data variable). Вот что мы изменим:
// Original
$data = $TMPL->tagdata;
// New
$data = ($TMPL->fetch_param('data')) ? $TMPL->fetch_param('data') : $TMPL->tagdata ;
Если вы не знакомы с этим синтаксисом, он в действительности говорит следующее: если информационный параметр существует (или true) тогда использовать его как нашу информационную переменную, в другом случае использовать тэговую информацию между тэговыми парами». Это изменение позволит нам использовать как тэговые пары, так и единичные тэги с определенным параметром информации. Вот как определится наш шаблон:
Почти готово!
Теперь у нас есть полностью функционирующий плагин для ExpressionEngine. Заключительным шагом в его завершении станет добавление полезной «используемой» (usage) информации. Дайте перейдем к функции “usage()” и добавим некоторую простую документацию для Контрольной Панели.
function usage()
{
ob_start();
?>
The "dictionary" of acronyms is stored in an array within the plugins/pi.auto_acronym.php file.
Automatically turn a string into an HTML acronym if it is within our acronym dictionary. You can do this with individual words or large blocks of text.
Simple Example
===========================
{exp:auto_acronym data="HTML"}
This outputs:
<acronym title="Hypertext Markup Language">HTML</acronym> in your ExpressionEngine template.
Large Block Example
===========================
{exp:auto_acronym}
<p>My name is Erik and I am an addict. I stay up late into the night marking up HTML and CSS with magical alignment.
Whitespace speaks volumes of my care and finesse of the code. My RSS subscribers wait on their toes for my next
example of code beauty. Okay...not really.</p>
{/exp:auto_acronym}
This outputs:
<p>My name is Erik and I am an addict. I stay up late into the night marking
up <acronym title="Hypertext Markup Language">HTML</acronym>
and <acronym title="Cascading Style Sheets">CSS</acronym> with magical alignment.
Whitespace speaks volumes of my care and finesse of the code.
My <acronym title="Really Simple Syndication">RSS</acronym> subscribers wait on their toes for my next
example of code beauty. Okay...not really.</p>
<?php
$buffer = ob_get_contents();
ob_end_clean();
return $buffer;
}
Теперь наша контрольная панель будет выглядеть следующим образом:
Поздравления!
Вот вы и закончили ваш первый плагин для ExpressionEngine. Надеюсь, это откроет перед вами двери, и вы поймете насколько это легко. Выбор и возврат информации – очень простой процесс, и вы можете использовать ваши волшебные формы РНР внутри самого плагина. Я размещаю этот плагин на моей странице, где вы можете скачать полный код плагина если захотите. В следующих сериях ExpressionEngine мы рассмотрим создание простого Расширения для Контрольной Панели. Не пропустите.
При перепечатке материала, просьба указывать eeclub.ru в качестве источника перевода.
