Понедельник, 22 апреля 2013 14:26

Создаем модуль для CMS Joomla 2.5

Оцените материал

(4 голосов)

В этой статье я опишу процесс создания модуля для CMS “Joomla” версии 2.5. Модуль будет генерировать QR-код, на основе параметров из настроек модуля.

Модуль будет работать на основе библиотеки PHP QR Code.

Итак, начну по порядку. Сначала нужно скачать последнюю версию библиотеки с GitHub . Библиотеки CMS “Joomla” хранятся в папке libraties, расположенной в корневой папке сайта. Создадим в ней папку, например, с названием qrlib и разархивируем в нее содержимое скачанного архива. Добавим в папку файл index.html, следующего содержания:

HTML

	<!DOCTYPE html><title></title>

Его можно скопировать из любой папки, где содержатся библиотеки системы. Он защищает от прямого обращения к папке из браузера и просмотра ее содержимого. Основным файлом библиотеки является файл qrlib.php. Обратим на это внимание, потому что его имя пригодится для подключения библиотеки в коде модуля. Также в папке библиотеки PHP QR Code присутствует файл index.php. В этом файле находится примерный код работы с библиотекой. Его можно запустить для ознакомления с возможностями PHP QR Code. После ознакомления его можно удалить из папки /libraries/qrlib.

Теперь переходим в папку modules, в которой хранятся все модули CMS “Joomla”. Создаем там папку с именем mod_qrcode – в ней мы будем создавать файлы нашего модуля. Не забываем про файл index.html, упомянутый выше – скопируем его в папку модуля. У любого модуля в “Joomla” есть 2 обязательных файла: имя_модуля.xml и имя _модуля.php. В нашем случае – это будут mod_qrcode.xml и mod_qrcode.php. В mod_qrcode.xml будут храниться настройки модуля, а в mod_qrcode.php – код самого модуля. Остальные файлы модуля, кроме указанных, необязательны и могут отсутствовать.

Вообще, структура модуля в CMS “Joomla” следущая:

index.html – файл-заглушка
mod_имя_модуля.php – код модуля (обязательный)
mod_имя_модуля.xml – описание и настройки модуля (обязательный)
helper.php – в файле хранится код класса-помощника. Методы этого класса получают данные из БД и форматируют их для вставки в код шаблона.
tmpl– папка для шаблонов
- default.php – шаблон для отображения результатов работы модуля

Кроме описанных файлов, мы создадим еще 2 языковых файла – они предназначены для отображения текста на разных языках в файлах модуля. Создадим пока файлы для русского языка. Их имена будут следующими: ru-RU.mod_qrcode.ini и ru-RU.mod_qrcode.sys.ini. Эти файлы нужно будет поместить в папку \language\ru-RU. По имени файла можно понять, что в нем указывается название модуля: ru-RU.имя_модуля.ini и ru-RU.имя_модуля.sys.ini. Эти файлы мы создадим позже, а сейчас переходим к созданию файла mod_qrcode.xml с описанием и настроками модуля.

XML

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="2.5" client="site" method="upgrade">
	<name>mod_qrcode</name>
	<author>Matthew</author>
	<creationDate>April 2013</creationDate>
	<copyright>Copyright (C) 2013 Matthew. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
	<authorEmail>info@mattweb.ru</authorEmail>
	<authorUrl>www.mattweb.org</authorUrl>
	<version>1.0</version>
	<description>MOD_QRCODE_XML_DESCRIPTION</description>
	<files>
		<filename module="mod_qrcode">mod_qrcode.php</filename>
		<folder>tmpl</folder>
		<filename>index.html</filename>		
		<filename>mod_qrcode.xml</filename>
	</files>
	<languages>
		<language tag="ru-RU">ru-RU/ru-RU.mod_qrcode.ini</language>
		<language tag="ru-RU">ru-RU/ru-RU.mod_qrcode.sys.ini</language>
	</languages>
	<config>
	<fields name="params">
		<fieldset name="basic">
			<field
					name="qrcode_data"
					type="text"
					label="MOD_QRCODE_FIELD_DATA_LABEL"
					description="MOD_QRCODE_FIELD_DATA_DESC" />
			<field
					name="ecc_level"
					type="list"
					default="L"
					label="MOD_QRCODE_FIELD_ECC_LABEL"
					description="MOD_QRCODE_FIELD_ECC_DESC"
				>
					<option value="L">L</option>
					<option value="M">M</option>
					<option value="Q">Q</option>
					<option value="H">H</option>
				</field>
			<field
					name="qr_size"
					type="list"
					default="4"
					label="MOD_QRCODE_FIELD_QR_SIZE_LABEL"
					description="MOD_QRCODE_FIELD_QR_SIZE_DESC"
				>
					<option value="1">J1</option>
					<option value="2">J2</option>
					<option value="3">J3</option>
					<option value="4">J4</option>
					<option value="5">J5</option>
					<option value="6">J6</option>
					<option value="7">J7</option>
					<option value="8">J8</option>
					<option value="9">J9</option>
					<option value="10">J10</option>
				</field>
		</fieldset>
		<fieldset name="advanced">
			<field
					name="class_sfx"
					type="text"
					label="MOD_QRCODE_FIELD_CLASS_LABEL"
					description="MOD_QRCODE_FIELD_CLASS_DESC" />
		</fieldset>
	</fields>
 </config>
</extension>

Файл mod_qrcode.xml состоит из блоков с описанием отдельных сущностей модуля: файлов, языковых настроек, общих параметров модуля и других. Если посмотреть на его содержимое внимательней, то можно без особого труда разобраться с описанием модуля. Я не буду останавливаться на этом и подробно описывать все настройки - объясню только некоторые моменты. Некоторые xml-элементы содержат текст, состоящий из заглавных букв и символов подчеркивания – это и есть наименования настроек из языковых файлов. В процессе работы с модулем, например, в административной части, вместо них вставляется фраза на языке, используемом системой для определенного сайта. В блоке config описываются параметры модуля для административной части. Здесь нужно обратить внимание на типы полей, в которых хранятся настройки.

В создаваемом нами модуле, предполагаются следующие обязательные параметры:

Данные, на основе которых будет генерироваться QR-код;
Уровень коррекции ошибок для сгенерированного штрих-кода;
Размер каждого квадрата штрих-кода в пикселях;

Для первого параметра мы будем использовать поле типа текст (”text”), а для второго и третьего тип поле будет список (”list”). Ознакомиться с полным списком типов полей. .

Дополнительный параметр у нашего модуля будет всего один – «Суффикс класса модуля», текстового типа.

Теперь пришло время создать языковые файлы и разместить их в папке \language\ru-RU. Начнем с файла ru-RU.mod_qrcode.ini.

	;ru-RU.mod_qrcode.ini
	MOD_QRCODE_XML_DESCRIPTION = "Модуль генерирует QR-код в соответствии с переданными параметрами. При работе модуля используется библиотека PHP QR Code"
	MOD_QRCODE_FIELD_DATA_LABEL = "Данные для QR-кода"
	MOD_QRCODE_FIELD_DATA_DESC = "Текст или данные, которые будут закодированы в изображении"
	MOD_QRCODE_FIELD_ECC_LABEL = "Уровень коррекции ошибок"
	MOD_QRCODE_FIELD_ECC_DESC = "Уровень коррекции ошибок для сгенерированного штрих-кода"
	MOD_QRCODE_FIELD_QR_SIZE_LABEL = "Размер каждого квадрата штрих-кода"
	MOD_QRCODE_FIELD_QR_SIZE_DESC = "Размер каждого квадрата штрих-кода в пикселях"
	MOD_QRCODE_FIELD_CLASS_LABEL = "Суффикс класса блока с QR-кодом"
	MOD_QRCODE_FIELD_CLASS_DESC = "Суффикс добавляется к имени CSS-класса блока с QR-кодом по умолчанию"
	J1 = "1"
	J2 = "2"
	J3 = "3"
	J4 = "4"
	J5 = "5"
	J6 = "6"
	J7 = "7"
	J8 = "8"
	J9 = "9"
	J10 = "10"
	MOD_QRCODE_ERROR = "Ошибка: "
	MOD_QRCODE_ERROR_EMPTY = "Не переданы данные для генерации QR-кода"

Также нужно создать файл ru-RU.имя_модуля.sys.ini.

	;ru-RU.mod_qrcode.sys.ini
	MOD_QRCODE = "Модуль генерации QR-кодов"
	MOD_QRCODE_XML_DESCRIPTION = "Модуль генерирует QR-код в соответствии с переданными параметрами. При работе модуля используется библиотека PHP QR code"
	MOD_QRCODE_LAYOUT_DEFAULT="По умолчанию"

Немного забегу вперед, чтобы показать результат проделанной на данный момент нами работы: после регистрации модуля в базе данных (или установки модуля), в административной части сайта мы сможем увидеть форму для ввода параметров. Эта форма создается системой на основе данных из созданных нами файлов.

Настройки на странице модуля в административной части Joomla

А сейчас переходим к самому важному шагу – созданию файла mod_qrcode.php – в котором будет находиться код, описывающий работу нашего модуля.

PHP

	<?php
		defined('_JEXEC') or die('Restricted access');
		try{
			//set it to writable location, a place for temp generated PNG files
			 $PNG_TEMP_DIR = JPATH_BASE.DS.'tmp';
			 //html PNG location prefix
			$PNG_WEB_DIR = '/tmp/';
			// including php qrcode 
			jimport('qrlib.qrlib');
			// file name...
			$filename = $PNG_TEMP_DIR.'test.png';
			// ECC Level
			$errorCorrectionLevel = $params->get('ecc_level'); 
			// size of QR code block
			$matrixPointSizeParam = $params->get('qr_size');
			$matrixPointSize = min(max((int)$matrixPointSizeParam, 1), 10);
			// Data for QR code
			$data = $params->get('qrcode_data');
			//it's very important!
			if (trim($data == '')) throw new JException(JText::_('MOD_QRCODE_ERROR_EMPTY'));
			// user data
			$filename = $PNG_TEMP_DIR.DS.'test'.md5($data.'|'.$errorCorrectionLevel.'|'.$matrixPointSize).'.png';
			QRcode::png($data, $filename, $errorCorrectionLevel, $matrixPointSize, 2);  
			// class suffix
			$class_sfx	= htmlspecialchars($params->get('class_sfx'));
			// generated file URL
			$qrImgUrl = $PNG_WEB_DIR.basename($filename);
			// include default template
			require(JModuleHelper::getLayoutPath('mod_qrcode'));
		}
		catch(JException $e){
			echo JText::_('MOD_QRCODE_ERROR').$e->toString();
		}
	?>

Код работает следующим образом: В переменную $PNG_TEMP_DIR сохраняем путь к временной папке – в нее будет размещаться сгенерированный файл с QR-кодом. Подключаем библиотеку – с помощью функции jimport(). Аргумент, передаваемый этой функции, по сути, это путь к основному файлу библиотеки. Он состоит из имени папки и имени файла, разделенного точкой. Далее получаем значения всех параметров, необходимых модулю для работы. Это делается с помощью метода get() класса JParameter. Как говорилось ранее, параметры устанавливаются в административной части сайта, на странице модуля. В случае, если поле с данными для генерации QR-кода не заполнено, создается исключение, которое выводит сообщение об этом. Код, расположенный ниже в этом случае не выполняется и QR-код не генерируется. Если же все нормально и поле непустое, вызывается статический метод QRcode::png() библиотеки, который создает png-файл c QR-кодом.

Теперь остается только сохранить в переменной $qrImgUrl URL png-файла и подключить шаблон модуля.

Код шаблона модуля (tmpl/default.php) у нас очень прост. Отмечу только то, что в нем можно обращаться к переменным, созданным в файле модуля. В нашем случае, это переменная $qrImgUrl.

PHP

	<?php
	// No direct access.
	defined('_JEXEC') or die;
	?>
	<img src="/<?php echo $qrImgUrl;?>" />

Итак, почти все готово: переходим к последнему этапу – регистрации модуля в базе данных CMS “Joomla”.

Для этого нужно открыть базу данных сайта (например, используя phpMyAdmin) и выполнить следующий SQL-запрос:

SQL

	INSERT INTO `имя_БД`.`#__extensions` (
	`extension_id` ,
	`name` ,
	`type` ,
	`element` ,
	`folder` ,
	`client_id` ,
	`enabled` ,
	`access` ,
	`protected` ,
	`manifest_cache` ,
	`params` ,
	`custom_data` ,
	`system_data` ,
	`checked_out` ,
	`checked_out_time` ,
	`ordering` ,
	`state` 
	)
	VALUES (
	NULL , 'mod_qrcode', 'module', 'mod_qrcode', '', '', '1', '1', '0', '{"legacy":false,"name":"mod_qrcode","type":"module","creationDate":"April 2013","author":"Matthew","copyright":"Copyright (C) 2013 Matthew. All rights reserved.","authorEmail":"info@mattweb.ru","authorUrl":"www.mattweb.ru","version":"1.0","description":"MOD_QRCODE_XML_DESCRIPTION","group":""}', '', '', '', '0', '0000-00-00 00:00:00', '0', '0');

Символы «#__» в наименовании таблицы в запросе нужно заменить на префикс таблиц БД “Joomla”.

Если все сделано правильно, то при создании нового модуля в «Менеджере модулей» будет доступен наш модуль под названием «QR код». Теперь осталось только установить модуль, настроить его параметры и разместить в какой-нибудь позиции шаблона сайта.

При создании модуля мне очень помогли следующие материалы:

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

Опубликовано в Joomla

Теги

Другие материалы в этой категории: « Создаем компонент с помощью Joomla Component Creator Используем комментарии JComments в K2 »

	string(1) "1"
====string(1) "1"
====int(1)
====string(1) "1"
====bool(true)

Наверх