Разрботка расширений для CMS Joomla

Языковые файлы фронтенда хранятся в папке /language/<ln-LN>, где <ln-LN> - код языка по стандарту RFC3066. Файл должен называться по схеме <ln-LN>.<префикс><имя расширения>.ini, где префикс зависит от вида расширения: "com_" (компонент), "mod_" (модуль), "tpl_" (шаблон) и т.д. Например, путь к языковому файлу компонента contact для русского языка следующий: /language/ru-RU/ru-RU.com_contact.ini

Языковые файлы бэкенда хранятся в папке /administrator/language/<ln-LN>.

Кроме файлов .ini, для расширения должен также быть создан файл *.sys.ini, в котором могут храниться переводы сообщений, выводящихся после установки расширения, переводы пунктов меню, создающихся для компонента в панели управления, переводы параметров компонента и переводы надписей, выводящихся в менеджере расширений. Например, путь к файлу .sys.ini компонента contact для русского языка выглядит так: /administrator/language/ru-RU/ru-RU.com_contact.sys.ini

Содержимое языкового файла состоит из пар "ключ-значение" и, при необходимости, комментариев. Пустые строки игнорируются. Комментарии начинаются с символа ";". Например:

; Это комментарий

Ключ - это строка для перевода, а значение - это перевод данной строки на заданный язык. Ключ отделяется от значения знаком равенства:

КЛЮЧ=Значение

Например:

COM_CONTACT="Контакты"

Ключ должен быть записан в верхнем регистре и не должен содержать пробелы. Все ключи во фронтенде должны начинаться со строки <префикс><имя расширения>_, например:

COM_CONTACT_CHANGE_CONTACT_BUTTON

Значение (перевод ключа) должно быть заключено в двойные кавычки. Если значение к тому же содержит двойные кавычки, то они должны быть записаны в виде HTML-сущности, например, &quot.

Для использования переводов применяются методы статического класса JText _(), sprint() и printf().

Простейший способ вывести перевод строки - использовать метод JText::_(), который просто переводит строку, переданную ему параметром. Например:

echo JText::_('COM_MYCOMPONENT_HELLO_WORLD');

Если перевод для заданной строки не будет найден в языковых файлах, то метод _() вернет саму эту строку. Перед поиском строка будет переведена в верхний регистр, поэтому не имеет значения, в каком регистре ее записать в коде.

Если в строку необходимо включить какие-либо значения, то используются методы JText sprintf() и printf(), аналогичные одноименным функциям в PHP. Их параметрами являются строка для перевода и любое количество аргументов для подстановки в переведенную строку. Сами параметры не будут переведены. Методы sprintf() и printf() различаются тем, что printf() выводит получившуюся строку на экран и возвращает ее длину, а sprintf() возвращает саму строку и ничего не выводит.

Например, если в языковом файле ru-RU.com_mycomponent.ini задано

COM_MYCOMPONENT_THANK_YOU="Спасибо за Ваше сообщение, %s!"

а в коде расширения имеется строка

echo JText::sprintf('COM_MYCOMPONENT_THANK_YOU', 'Вася');

то результатом будет вывод на экран строки "Спасибо за Ваше сообщение, Вася!".

Аргументы задаются так же, как в одноименных функциях PHP: %s означает строку, %d - целое число, %f - число с плавающей точкой и т.д.

Паттерн "фабрика" (класс JFactory)

В Joomla существует статический класс JFactory, реализующий паттерн "фабрика". Методы данного класса (getApplication(), getDate(), getDbo(), getDocument(), getLanguage(), getURI(), getUser(), getMailer(), getEditor() и др.) позволяют получить доступ к соответствующим глобальным объектам фреймворка (JApplication, JDate, JDatabase, JDocument, JLanguage, JURI, JUser, JMail, JEditor и др.), ряд которых будет рассмотрен далее.

Рассмотрим пример получения доступа к объекту JUser:

$user =& JFactory::getUser(); if ($user->guest) echo "Вы не вошли на сайт"; else echo "Вы вошли на сайт как ".$user->name;

Обратите внимание на знак амперсанда перед вызовом метода getUser(). Мы получаем ссылку на объект-представитель текущего пользователя. Если пропустить амперсанд, то будет создана копия этого объекта и изменения, которые мы будем в ней производить, не затронут оригинал.

HTTP-запрос (класс JRequest)

В Joomla вместо непосредственного использования глобальных массивов $_GET, $_POST, $_FILES, $_COOKIE, $_ENV, $_SERVER и $_REQUEST удобнее применять класс JRequest. Его методы пропускают данные, введенные пользователем, через фильтр во избежание инъекций.

Для получения переменных запроса GET/POST используется метод mixed getVar(string $name, string $default=null, string $hash='default', string $type='none', int $mask=0), где:

$name имя переменной; $default значение по умолчанию, которое вернет метод getVar(), если значение переменной не задано; $hash источник данных, по умолчанию они будут получены из массива $_REQUEST. Явное указание массива GET или POST повысит безопасность кода; $type тип ожидаемого значения: INT INTEGER FLOAT DOUBLE BOOL BOOL WORD ALNUM допускает только буквенно-цифровые значения; CMD BASE64 допускает только те символы, которые могут быть представлены в кодировке base64 (т.е. a-z, A-Z, 0-9, /, + и =); STRING ARRAY PATH исключает возможность атаки. Например, если исходное значение содержало /./ или /../, то вместо него метод вернет пустую строку; USERNAME удаляет управляющие символы (0x00 - 0x1F), 0x7F, <, >, ", ', % и &; $mask константа, задающая опции фильтрации: JREQUEST_NOTRIM не удалять пробелы в начале и конце строки; JREQUEST_ALLOWRAW без какой-либо фильтрации; JREQUEST_ALLOWHTML не удалять HTML-код, но пропустить значение через фильтр (в частности, удалить опасные теги - script, applet, iframe и др.).

Эти константы не заключаются в кавычки, т.к. это не строки, а статические переменные. Если ни одной опции не задано, то HTML-теги, а также пробелы в начале и конце строки будут удалены.

Пример:

$answer = JRequest::getVar('answer', 'no answer', 'post', 'string', JREQUEST_ALLOWRAW);

Если нужно получить весь массив переменных запроса в отфильтрованном виде, используется

mixed get(string $hash='default', int $mask=0)

Например, получим массив $_POST:

$arr = JRequest::get('post');

Для присвоения переменным запроса значений используется метод string setVar(string $name, string $value=null, string $hash='method', bool $overwrite=true)

Если $overwrite=false и в запросе уже задано значение переменной $name, то метод просто вернет само это значение. В противном случае переменной будет присвоено значение $value, а метод вернет старое значение $name.

Пример:

JRequest::setVar('var1', 'val1');

Класс JRequest содержит также методы, позволяющие получить значение определенного типа: getBool(), getCmd(), getFloat(), getInt(), getString(), getWord().

Приложение (класс JApplication)

Очередь сообщений

В Joomla существует очередь сообщений- массив строк, которые будут выведены на экран при следующей загрузке какой-либо страницы. Стандартными являются три типа сообщений (рис. 1.2): message (собственно сообщение), notice (предупреждение) и error (ошибка):

Рис. 1.2.  Типы сообщений

Для добавления сообщений в очередь используется метод void enqueueMessage(string $msg, [string $type = 'message']), где:

$msg - текст сообщения; $type - тип сообщения.

Например:

global $app; $app->enqueueMessage('Message'); $app->enqueueMessage('Notice', 'notice'); $app->enqueueMessage('Error', 'error');

В данном примере $app - это глобальный объект JApplication.

Для получения копии очереди сообщений используется метод array getMessageQueue(). Например, для предыдущей очереди из трех сообщений он возвращает массив: