Wiki.Ru-Mambo.ru : РуководствоПоСозданиюМодулей

Введение
Целью этого пособия является изложение базового концепта написания модулей для Mambo. В нем мы разработаем простейший модуль приветствия Hello World, и, используя patTemplate, подготовим его для представления.
Требования
Для работы с этим пособием вам понадобится:
· Mambo 4.5.2 или старше
Поехали!
Нам потребуется создать 2 файла в папке, которая называется /modules/. Давайте рассмотрим файлы, которые нам потребуются.
mod_helloworld.php
Файл, который является движком для модуля.
mod_helloword.xml
Установочный xml файл для модуля. Определяет необходимую информацию для того, чтобы устанавливать модуль.
Установка Базового Модуля
Мы не можем создать наш модуль из ничего просто из администраторской панели, поэтому давайте разработаем и создадим несколько базовых файлов для начала, а затем установим их как модуль.
Давайте сперва сделаем модуль. Сохраните нижеприведенный код как mod_helloworld.php.
<?php
/**
* @version 1.0 $
* @package Hello World
* @copyright © 2005 Andrew Eddie
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
*/

/** ensure this file is being included by a parent file */
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );

?>
<h1>Hello World</h1>
Затем сохраните этот код в файле mod_helloworld.xml.
<?xml version="1.0" encoding="iso-8859–1"?>
<mosinstall type="module" version="4.5.2">
</mosinstall>
Первая строчка этого файла является установкой определения. Вам не нужно много задумываться о том, что он означает, но он просто ДОЛЖЕН быть внутри файла и обязательно должен быть первой строчкой файла (пробелы до него не допускаются). Теперь о том, что означают другие тэги:
mosinstall
Родительский тэг, определяющий оставшуюся часть установчного файла для mambo. У него есть атрибут типа, который в данном случае является модулем. Также он принимает значение версии Mambo с которой он работает.
name
Имя вашего модуля.
author
Имя создателя модуля.
creationDate
Дата создания модуля.
copyright
Копирайт.
license
Название, или ссылка на название лицензии под которой модуль был выпщен.
version
Версия модуля.
description
Текстовое описание модуля.
files
Описывает файлы, включенные в модуль.
filename
Файл, который был использован. Можно перечислить любое количество файлов, включая файлы в поддиректориях. Файл, который вызывается Mambo, чтобы запустить модуль, должен содержать атрибут module, который принимает значение имени файла без.php расширения.
А сейчас зазипуйте эти два файла в файл, который будет называться mod_helloworld.zip или загрузите его копию здесь (mod_helloworld.zip).

Следуйте этим инструкциям, чтобы установить базовый модуль:
1. Залогиньтесь в Панель Администратора.
2. Выберите Modules -> Install / Uninstall из меню.
3. В области Upload Package File, кликните на кнопку Browse и выберите zip-файл, который вы только что создали или загрузили (mod_helloworld.zip). Затем нажмите на кнопку Upload File and Install.


Если все прошло хорошо, вы должны увидеть сообщение об удачной установке. Жмите на ссылку Continue.

Пока мы находимся под логином Администратора, выберите Modules -> Site Modules из Меню. Прокрутите вниз, пока не появится список для Hello World. Вы увидите, что ваш модуль не опубликован и привязан к левой позиции в шаблоне. Нажите на красный Х, чтобы опубликовать ваш модуль.


Посмотрите на ваш сайт. Вы должны увидеть модуль, который вас приветствует.

Поздравляем! Вы только что сконструировали и опубликовали ваш первый модуль! Теперь, когда он установлен, мы можем изменять файлы напрямую, чтобы добавить в наш модуль новые фишки.
Улучшая Презентацию
Вы обнаружите, что ваш новый модуль был установлен в директорию /modules на вашем сайте. Сначала давайте отделим слой презентации из файла модуля.

Создайте новую директорию в папке /modules назвав ее /mod_helloworld. В этой новой дирекотрии создайте файл и назовите его default.html. Скопируйте код, приведенный ниже, в этот файл:
<mos:comment>
@version 4.5.2
@package Hello World
@copyright © 2005 Andrew Eddie
@license http://www.gnu.org/copyleft/gpl.html GNU/GPL
</mos:comment>
<mos:tmpl name="helloworld">
</mos:tmpl>
Мы добавили немного дополнительного кода, чтобы показать, как добавить переменную в ваш шаблон для модуля. Вы также заметите, что html превратился в тэг mos:tmpl. Это служит определением шаблона и мы присвоили имя шаблону – helloworld.

А сейчас найдите файл mod_helloworld.php в дирекотрии /modules и откройте его в вашем html-редакторе.
Совет: Существует много бесплатных редакторов типа PSPad и HTML-Kit. Мы советуем вам попробовать поработать с редактором Eclipse.

Уберите тот код, что у вас имеется и замените его следующим:
<?php
/**
* @version 1.0
* @package Hello World
* @copyright © 2005 Andrew Eddie
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
*/

/** ensure this file is being included by a parent file */
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );

// load the patTemplate library
require_once( $mosConfig_absolute_path . '/includes/patTemplate/patTemplate.php' );

// create the template
$tmpl =& patFactory::createTemplate( , false, false );

// set the path to look for html files
$tmpl->setRoot( dirname( FILE ) . '/mod_helloworld' );

$tmpl->readTemplatesFromInput( 'default.html' );

$tmpl->addVar( 'helloworld', 'time', date( 'H:i:s' ) );

$tmpl->displayParsedTemplate( 'helloworld' );
?>
Давайте проверим, что же происходит в этом файле.
· Блок комментариев сверху определяет мета-данные о файле, в частности лицензию и копирайт. Этот блок имеет несколько специальных примечаний и приложение под названием phpDocumentor. Он используется для сборки API-документации (Application Programmer Interface – Приложение Интерфейса Программиста). Важным в данном случае является версия и определение копирайта для файла.
· Затем мы ищем константу, которая называется _VALID_MOS. Так как константа определяется в Мамбо в других местах, она служит подтверждением того, что только Mambo пытается получить доступ к файлу. Она предотвращает пользователю прямое открытие этого файла из браузера
· Затем мы включаем библиотеку patTemplate.
· Объект patTemplate создан и теперь мы устанавливаем корневую директорию для файлов шаблона (html) к директории/mod_helloworld в вашем модуле.
· Так как мы установили корневую директорию, мы можем просто получать данные из файла default.html с помощью метода readTemplatesFromInput.
· Затем нам нужно присвоить переменной {TIME} значение в нашем шаблоне. Чтобы это сделать, мы используем метод addVar объекта шаблона. Метод использует три аргумента. Первый – это имя шаблона, второй – имя переменной шаблона и третий – значения, которые нужно присвоить.
· В самом конце мы отображаем шаблон helloworld.

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

Вы можете загрузить файлы последней части туториала здесь (mod_helloworld_1.zip). Обратите внимание, что файл XML был обновлен, чтобы включить новый html файл.


Module Hello World 2

Введение
Целью этого пособия является постороение модуля helloworld, который мы начали разрабатывать в первой части. Вы научитесь как получать информацию из базы данных и как представлять эти данные в таблицу, используя patTemplate.
Требования
Для работы с этим пособием вам понадобится:
· Mambo 4.5.2 или более новая версия.
Поехали!
Вспомните о том, как вы завршили первую часть этого пособия, касающегося построения модуля, отображающего сообщение и текущее время. Все это было очень интересным, но гораздо более интересным для нас представляется информация, содержащаяся в таблицах базы данных Mambo. В этом примере мы разработаем пример модуля текущих новостей.
Презентационный Слой (HTML)
Давайте начнем со «внутренностей» нашего модуля. Так как код (или логика) модуля на данный момент отделен от презентационного слоя, (HTML), это дает дизайнеру возможность сконструировать внутренности отдельно от модуля.
Кодировщик, написавший модуль, проинформировал нас о том, что список элементов содержания будет предоставлен в шаблоне. Данные элемента содержания будут включать id элемента, имя элемента и количество хитов, которые получил элемент.
А сейчас откройте файл default.html (мы сохранили его в директории /mod_helloworld). Удалите то, что там находится и вставьте нижеследующий код:
<mos:comment>
@version 1.0
@package Hello World
@copyright © 2005 Andrew Eddie
@license http://www.gnu.org/copyleft/gpl.html GNU/GPL
</mos:comment>

<mos:tmpl name="helloworld">

<h1>Hello World</h1>
This is the latest and the greatest from <strong>{SITENAME}</strong>
<table>

<tr>

<th>

Title

</th>
<th>

Hits

</th>
</tr>
<mos:tmpl name="rows">
<tr>

<td>

{ROW_TITLE}

</td>
<td>

{ROW_HITS}

</td>

</tr>
</mos:tmpl>

</table>

</mos:tmpl>
Так же как и в первой части, мы превратим наш модуль целиком в шаблон, который мы назвали helloworld. Все это выглядит так же как стандартный HTML за исключением нескольких вещей.

Вы увидите, что мы отражаем сообщение с переменной {SITENAME}. Эта переменная уже была определена для вашего шаблона. Она эквивалентна операции вывода переменной $mosConfig_sitename. Другие переменные, которые были определены, включают {SITEURL} и{ADMINURL} и указывают URL сайта и соответственно URL администратора.

Обратите внимание на шаблон, который мы назвали rows. Он включает в себя всего одну строку таблицы HTML. Дизайнер модуля рассказал нам, что он определил префиксы для всех переменных в шаблоне rows с помощью “row_", и то, что он как минимум, предоставил имя (Title), на которое указывает {ROW_TITLE}, и количество хитов {ROW_HITS}.

Ну вот мы и разобрали этот шаблон. Кажется вы считаете, что это черезчур просто?
Слой Данных
Давайте вернемся к файлу модуля mod_helloworld.php, в котором мы соберем данные, для того, чтобы передать их в шаблон. Откройте файл в редакторе, и замените содержимое файла следующим кодом:
<?php
/**
* @version 1.0 $
* @package Hello World
* @copyright © 2005 Andrew Eddie
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
*/

/** ensure this file is being included by a parent file */
defined( '_VALID_MOS' ) or

die( 'Direct Access to this location is not allowed.' );

// COLLECT DATA

// assemble query
$query = '

SELECT id, title, hits
FROM #__content
ORDER BY hits DESC
LIMIT 5

';

// prepare the query in the database connector
$database->setQuery( $query );

// retrieve the rows as objects
$rows = $database->loadObjectList();

// DISPLAY DATA

// load the patTemplate library
require_once( $mosConfig_absolute_path

. '/includes/patTemplate/patTemplate.php' );

// create the template
$tmpl =& patFactory::createTemplate( , false, false );

// set the path to look for html files
$tmpl->setRoot( dirname( FILE ) . '/mod_helloworld' );

// load the template
$tmpl->readTemplatesFromInput( 'default.html' );

// add the 'rows' to the rows template with a prefix
$tmpl->addObject( 'rows', $rows, 'row_' );

// output the template
$tmpl->displayParsedTemplate( 'helloworld' );
?>
Давайте исследуем, что здесь происходит:
· Начнем со стандартного комментария и блока безопасности.
· Затем подготовим наш запрос. Данные, которые нас интересуют, находятся в таблице mos_content. Так как мы не уверены, что префикс “mos_" prefix был использован по умолчанию, мы будем использовать префикс "#__" вместо него. Это должно быть автоматически заменено на правильный префикс в таблице базы данных. Мы обращаемся к трем полям – id, имя и хиты. Мы располагаем их по количеству хитов в порядке убывания и устанавливаем лимит на количество максимальных результатов на 5.
· Затем мы инициализируем запрос в базе данных ($database, что всегда доступна в файлах модулей), используя метод setQuery.
· Вслед за этим, мы вызовем метод loadObjectList, чтобы получить результаты из базы данных, как массив объектов PHP. Он записывается в переменную $rows.
Ну вот и все для первой части модуля. Вот это и есть сбор данных. Последняя половина модуля приблизительно такая же как в нашем модуле из первой части. Единственная разница заключается в том, что мы используем метод addObject, чтобы добавить массив к шаблону строк.
Внимание: метод addObject может брать либо единственный объект, либо массив объектов

Следует здесь обратить внимание на то, что для каждого члена массива в $rows, шаблон rows (строк) в HTML файле будет отображаться своя копия. Иными словами, если в массиве $rows есть 5 элементов (то есть, база данных вытащила 5 строчек записей), то шаблон rows (строки) будет повторяться 5 раз. Шаблон rows работает так же как цикл foreach в PHP.



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

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

// сбор запроса
global $mosConfig_offset;

$now = date( 'Y-m-d H:i:s', time() + $mosConfig_offset * 3600 );

$query = '
';
В следующей части мы научимся добавлять параметры к нашему модулю.
Вы можете загрузить файлы последней части туториала здесь (mod_helloworld_2.zip).

Введение
Этот туториал нацелен на дальнейшее построение модуля helloworld. Вы научитесь как использовать параметры, чтобы настроить информацию, которая будет отображаться. Мы также научимся менять внешний вид вашего модуля.
Требования
Для работы с этим пособием вам понадобится:
· Mambo 4.5.2 или более новая версия.
Поехали!
Давайте вспомним, что во второй части наш модуль отражал количество хитов. К несчастью, мы могли только отобразить 5 элементов и не могли менять порядок расположения. В этом примере мы научимся добавлять параметры к модулю, так, чтобы затем мы могли варьировать эти условия.
Установка Параметров
Нам нужно будет заново пересмотреть файл xml, который мы создали в первой части. Мы определим все параметры в этом файле. Вначале давайте рассмотрим, какие переменные мы будем менять:
1. Нам понадобится переменная, для изменения количества отображаемых элементов.
2. Мы хотим сами выбирать порядок отображения элементов в списке.
3. Мы хотим получить возможность выбирать шаблон, чтобы изменять внешний вид отображения результатов.
Чтобы это сделать, мы добавляем тэги param в тэг params. Откройте файл mod_helloworld.html. Замените его содержимое этим кодом:
<?xml version="1.0" encoding="iso-8859–1"?>
<mosinstall type="module" version="4.5.2">
</mosinstall>
Каждый тэг param имеет определенные атрибуты:
имя 
Имя поля формы html и имя параметра, к которому вы получите доступ в коде вашего модуля.
тип 
Тип поля. Стандартные параметры:
· text – текстовое поле
· textarea – поле textarea. Можно также добавить атрибуты к строчкам и колонкам.
· list – список выбора из поля. Списки могут иметь опции и тэги.
· radio – «радио-группа». Тип радио может иметь опции и тэги
· spacer – показывает горизонтальную линейку html.
· imagelist – показывает выбранный список картинок. Вы также должны указать аттрибуты директории (по умолчанию это /images/stories), опциональный аттрибут hide_none (0 или 1, где 1 покажет опцию “Use no image” (не использовать изображение)) и аттрибут hide_default (0 или 1, где 1 покажет опцию “Use default image” (Использовать изображение по умолчанию)).
· mos_category – показывает выбор списка содержания категорий Mambo
· mos_section – показывает выбор списка секций содержания Mambo.
· mos_menu – показывает список элементов меню Mambo.
default
Значение по умолчанию для поля формы если не было указано никакого значения.
label
Метка для поля формыы.
description
Описание поля формы.
Существуют также дополнительные атрибуты, основанные на типе параметров описанных ниже. Для тех параметров, которые имеют опции, используется стандартный html option тэг, обычно с атрибутом value.

Давайте посмотрим на каждый из тегов param в тэге params (каждый параметр будет определен по атрибуту name):
moduleclass_sfx
Стандартный параметр, который должен был включен во все модули. Большинство модулей помещаются во wrapper (если только вы не используете макро темплейт loadModules со стилем меньше ноля) и этот wrapper имеет css класс moduleclass. Вы можете включить ваш собственный вариант этого класса и обозначить его уникальным идентификатором, например, moduleclass_hello. Чтобы использовать ваш собственный класс, вы должны ввести _hello в поле
@spacer
Этот параметр просто отображает горизонтальную линейку. Может оказаться полезным для визуального разделения групп ассоциативных параметров.
count
Это определит количество элементов, которые мы будем отображать.
ordering
Эта опция отображает список возможных опций для упорядочивания списка элементов
@spacer
Еще один spacer.
skin
Покажет список имеющихся в наличие «оболочек» для вывода модуля.

Когда вы выгрузите xml файл, идите в Modules -> Site Modules из меню Администратора. Щелкните на пролинкованном имени для модуля Hello World (он может быть на другой странице списка, в зависимости от своей позиции).


Когда появится экран редактирования, вы должны увидеть, что параметры показаны внизу первой колонки формы.

Вы можете увидеть, как работает spacer, отделяя параметры по группам. Вы можете также увидеть, что списки составлены с опциями, определенными в файле xml. Сейчас вы можете оставить count пустым, но когда мы закончим работу с кодом, вернитесь и отредактируйте форму и проэкспериментируйте с разными значениями. Обратите внимание, что Page Class Suffix будет соответствовать если у вас есть определенный список стилей для шаблона вашего сайта.
Код для Параметров Модуля
Следующий наш шаг – извлечь параметры в наш модуль и применить их. Откройте модуль файла php mod_helloworld.php в вашем редакторе и замените его код следующим кодом:
<?php
/**
* @version 1.0 $
* @package Hello World
* @copyright © 2005 Andrew Eddie
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
*/

/** ensure this file is being included by a parent file */
defined( '_VALID_MOS' ) or

// COLLECT DATA

// assemble query
global $mosConfig_offset;

$now = date( 'Y-m-d H:i:s', time() + $mosConfig_offset * 3600 );

// Retreive parameters

$count = intval( $params->get( 'count', 10 ) );
$ordering = $params->get( 'ordering', 'hits' );
$skin = $params->get( 'skin', 'default' );

// Assign ordering

switch ($ordering) {
}

$query = '
;

// prepare the query in the database connector
$database->setQuery( $query );

// retrieve the rows as objects
$rows = $database->loadObjectList();

// DISPLAY DATA

// load the patTemplate library
require_once( $mosConfig_absolute_path . '/includes/patTemplate/patTemplate.php' );

// create the template
$tmpl =& patFactory::createTemplate( '', false, false );

// set the path to look for html files
$tmpl->setRoot( dirname( FILE ) . '/mod_helloworld' );

// load the template based on the selected skin
$tmpl->readTemplatesFromInput( $skin . '.html' );

// add the 'rows' to the rows template with a prefix
$tmpl->addObject( 'rows', $rows, 'row_' );

// output the template
$tmpl->displayParsedTemplate( 'helloworld' );
?>

Вы увидите, что после комментария по «извлечению параметров» мы добавили несколько строчек кода. Объект переменной $params уже стал доступным в модуле. У него есть метод, называемый get. Этот метод берет 2 аргумента: первый – имя параметра, второй – значение по умолчанию, если пользователь не установил никакого значения.

Теперь, когда у нас есть параметры в варьируемой форме, вы увидите, что мы используем их, чтобы модифицировать порядок запроса, а также количество элементов, возвращенных по запросу. Далее вы увидите пример использования переменной $skin для загрузки выбранной оболочки в вывод.
Добавление другой оболочки
Последнее, что нам нужно будет научиться делать – это добавлять нашу альтернативную оболочку. Рузультат мы представим в виде списка вместо таблицы. Вспомните, что наш текущий шаблон называется default.html в папке mod_helloworld. В той же директории создайте новый файл, который будет называться bullets.html и скопируйте в него следующий код:
<mos:comment>
@version 1.0
@package Hello World
@copyright © 2005 Andrew Eddie
@license http://www.gnu.org/copyleft/gpl.html GNU/GPL
</mos:comment>

<mos:tmpl name="helloworld">
</mos:tmpl>

Когда вы закончите, вернитесь к экрану редактирования модуля и поменяйте некоторые значения. Посмотрите, что произойдет.
То, что мы здесь продемонстрировали – есть возможность представить одни и те же данные разными способами без вмешательство в основной php-код. Изменение в презентационном слое было сделано в знакомых файлах HTML, что дает Mambo возможность подстраиваться под ваши специальные нужды.
Вы можете загрузить файлы для этого туториала здесь (mod_helloworld_3.zip).