Переменные конфигурации
Разделы: Документация / Расширяем Cotonti / Расширения
Механизм Cotonti спроектирован таким образом, что позволяет при создании Расширения задать набор переменных, которые будут доступны для настройки через панель администрирования. Они отображаются на странице (Управление сайтом → расширения → 'имя расширения' → Конфигурация). Таким образом разработчик может создавать более гибкие расширения.
Настройки переменных конфигурации загружаются из файла настроек Расширения (extension_name.setup.php) во время установки Расширения в панели администрирования.
Поэтому, если вы разрабатываете свое Расширение и изменили или добавили переменные в файл установки (setup файл), то вам необходимо произвести процедуру переустановки Расширения в Админ панели (Управление сайтом → Расширения → 'ваше расширение', кнопка Обновить).
Для описания переменных конфигурации в установочном файле Расширения (extension_name.setup.php) должен быть размещен текстовый блок, выделенный следующими маркерами:
[BEGIN_COT_EXT_CONFIG]
...
[END_COT_EXT_CONFIG]
Внутри этого блока должно находится описание переменных настройки. Описание каждой переменной находится на отдельной строке и задается отдельными «полями» в следующем формате:
Variable=[Order]:[Type]:[Values]:[Default]:[Description]
Квадратные скобки указаны как знак того, что некоторые поля могут быть опущены при задании переменной. Знаки : и =обязательны.
Рассмотрим подробнее составляющие формата:
Variable: Имя переменной для доступа из програмного кода, без знака $.Order: Порядковый номер. Служит для контроля порядка отображения (сортировки) полей ввода на странице Конфигурации.Type: Тип переменной конфигурации. Подробнее о типах смотри следующий раздел «Используемые типы переменных».Values: Допустимые значения. Для переменных типа select and radio задается список значений разделенных запятыми. Для типа range в этом поле задаются минимальное и максимальное значение для задания диапазона возможных вариантов выбора. Для типа callback или custom здесь указывается имя функции обработчика (см. описание в следующем разделе). В остальных случаях поле остается пустым.Default: Значение по умолчанию. Для типов select и radio в качестве значения по умолчанию может быть только одно из тех, что указано в поле Values. Для остальных указывается значение (строковое), которое будет использовано как начальное, или восстановлено при нажатии кнопки сброс в панели Конфигурации. Значение по умолчанию может быть не задано (пустым).Description: Описание. Текст который будет отображен в панели Конфигурации для описания назначения данной настройки. [При использовании мультиязычных сайтов описания переменных могут быть локализованы (переведены) посредством языковых файлов. Подробнее об этом смотри в статье «Локализация расширений».]stringСтрока данных, максимальной длинной 255 символов. отображается на странице настроек как обычное однострочное поле ввода. Значение поля Values для этого типа не используется.
selectМеню выбора. Отображается как стандартный раскрывающийся список. Элементы списка задаются в поле Values через запятую. Позволяет выбрать только один вариант из списка.
radioМеню выбора в виде переключателя (или как их еще называют радио-кнопок). Используется для переменных, которые отображают параметр, с несколькими возможными состояниями, выбрать из которых можно только один.
Обратите внимание! Для различных версий Siena, варианты задания и отображения опций несколько различаются:
версии 0.9.18.1 и более ранних: поле Values не используется. Значение по умолчанию может быть только 1или 0 (для состояний «включено|выключено»). Отображается на странице настроек всегда в виде пунктов «Да» / «Нет».
для версий начиная с 0.9.19: поддерживается расширенный вариант использования, когда можно задать более двух пунктов с произвольными значениями. В этом случае в поле Values задаются значения списка (в точности аналогично типу Select).
textТип text используется для ввода текстовых данных без ограничения на длину строк (актуальный максимальный размер данных определяется настройками серверного ПО, например смотри параметр post_max_size из php.ini файла). Значение поля Values для этого типа не используется. Надо также отметить, что тип text используется как тип по умолчанию в том случае, если актуальный тип не указан в описании переменной (или указан с ошибкой).
callbackТип callback отображается аналогично типу select, с той лишь разницей, что список элементов для выбора не указан жестко при описании, а генерируется заданной функцией. Имя такой функции указывается в поле Values. Для примера, если поле Values содержит запись cot_get_parsers(), то для формирования списка будет использован массив возвращаемый этой функцией. Подробнее об этом типе смотри в разделе «Расширенные типы переменных».
hiddenПеременная аналогичная типу String, но скрытая от взгляда пользователя (не выводится на странице Конфигурации) и используемая программно из кода Расширения.
separatorТип разделитель. По сути это не переменная, а описание визуального элемента в интерфейсе панели администрирования, который служит для отделения одной группы параметров от другой. Чтобы разделитель оказался в нужном месте списка настроек ему, как и остальным переменным надо правильно задать порядковый номер (в полеOrder). Текст указанный в поле Description будет использован как заголовок при отображении разделителя.
rangeСоздает меню выбора (в виде раскрывающегося списка) целых значений из диапазона заданного в настройках переменной. Границы диапазона (минимум и максимум) указываются в поле Values через запятую.
customТип custom добавлен в Cotonti в версии 0.9.18 (и дополнен в версии 0.9.19) для расширения ограниченного набора стандартных типов. Тип custom позволяет разработчику написать самостоятельный обработчик поля ввода данных, т.е. определить:
Имя функции обработчика, как и в случае с типом callback задается в поле Values. Подробнее об этом типе смотри в разделе «Расширенные типы переменных».
[BEGIN_COT_EXT_CONFIG]
myvar1=01:string::50:This is my first variable
myvar2=02:select:1,2,3,4,5,6,7,8,9,10:7:This is my second variable
myvar3=03:radio::1:This is my third variable
myvar4=04:text::Default text goes here:This is my fourth variable
myvar5=05:callback:cot_get_parsers():none:This is one of the available parsers
myvar6=06:hidden::123foo:This option is not visible for admins
myvar7=07:separator:::Separator is displayed here
myvar8=08:range:1,100:50:A selection from 100 numbers
myvar9=09:custom:custom_input_func(a,b,c):50:Custom function field
[END_COT_EXT_CONFIG]
Теперь пользователь сможет изменять настройки вашего Расширения через панель администрирования. Доступ к указанным значениям в программном коде осуществляется через обращение к системному массиву $cfg. Для плагина значения переменных доступны таким образом:
$cfg['plugin']['имя_плагина']['myvar1'] $cfg['plugin']['имя_плагина']['myvar2'] ...
где имя_плагина надо заменить на название вашего плагина. Для модулей доступ к переменным несколько отличается:
$cfg['имя_модуля']['myvar1']
где имя_модуля это название модуля.
В описании переменной типа select в поле Values в качестве элементов списка могут быть указаны только простые строки. Эти строки будут использованы и как значения и как описание элемента списка при формировании кода. Т.е. строка описания var=01:select:v1,v2,v3:v1:Description будет преобразована примерно в следующий html код для использования на странице Конфигурации:
<select name="var"> <option value="v1" selected>v1</option> <option value="v2">v2</option> <option value="v3">v3</option> </select>
В тех случаях, когда надо задать описания пунктов списка отличные от реальных значений (v1,v2,v3) можно воспользоваться типом callback (см. ниже) или механизмом локализации переменных (об этом подробнее смотри в статье «Локализация Расширений»).
Визуально переменная типа callback на странице настроек отображается аналогично типу select, как выпадающий список, но перечень пунктов этого списка задается не в описании переменной, а формируется из массива данных, возвращаемого указанной функцией. Имя такой функции задается в описании (см. выше «Формат задания переменных»). Функция должна возвращать массив.
Обратите внимание Для версий 0.9.18 и ниже допустим только «простой» нумерованный формат массива:
array( 'value1', 'value2', 'value3', );
значения массива (value1, value2, value3) будут использованы и как значения пунктов списка и как их названия (см. пример HTML кода выше в описании типа 'Select').
Начиная с версии 0.9.19 допустимо использовать ассоциативный массив ключи которого будут использованы как значения элементов списка, а строки массива, как описание (названия) элементов списка. Т.е. массив
array( 'key1' => 'title1', 'key2' => 'title2', 'key3' => 'title3', );
будет преобразован в следующий список:
<option value="key1">title1</option> <option value="key2">title2</option> <option value="key3">title3</option>
Не зависимо от версии может быть использован механизм локализации переменных настройки (см. ссылку на статью выше). Локализованные описания элементов списка имеют приоритет над заданными массивом.
Тип callback может потребоваться в случаях, когда элементы списка зависят от дополнительных условий (например настроек другого Расширения). При описании переменной, функция может быть задана с параметрами. Эти параметры будут переданы ей при вызове.
myvar5=05:callback:cot_get_parsers(html):none:This is one of the available parsers
Тип custom призван исправить проблему ограниченного числа стандартных типов т.к. позволяет написать код обработки и контролировать отображение поля ввода и фильтрацию введенных пользователем данных. Это почти не ограниченно расширяет возможности разработчика по взаимодействию с пользователем через панель администрирования.
Механизм работы переменных данного типа подробно изложен в отдельной статье на примере конкретных задач («Тип 'custom' в переменных конфигурации»).
Обратите внимание! Данный тип будет работать только в Cotonti начиная с версии 0.9.19. Если вы разрабатываете Расширение для более старых версий имейте это в виду.
Подробно процесс локализации переменных конфигурации изложен на странице «Локализация Расширений». Здесь лишь отметим, что описания переменных и отображаемые в списках значения могут быть переведены на необходимые языки и быть отражены в зависимости от выбранного на сайте языка.
Некоторые Расширения, а точнее Модули могут использовать такой, встроенный в Cotonti, механизм, как «структура (дерево) категорий». Как пример модули 'page' и 'forums' имеют категории для страниц и разделов форума. По умолчанию каждая, создаваемая в дереве категория, имеет предустановленный набор параметров (заголовок, описание и т.п.). Однако этот набор может быть программно расширен, путем добавления дополнительных переменных конфигурации, аналогично тому, как мы это можем делать для добавления параметров настройки Расширений. Точно так же описания этих переменных должно находится в установочном файле модуля (module_name.setup.php) в специальном блоке COT_EXT_CONFIG_STRUCTURE. Вот пример подобного блока из модуля 'page':
[BEGIN_COT_EXT_CONFIG_STRUCTURE]
order=01:callback:cot_page_config_order():title:
way=02:select:asc,desc:asc:
maxrowsperpage=03:string::30:
truncatetext=04:string::0:
allowemptytext=05:radio::0:
keywords=06:string:::
[END_COT_EXT_CONFIG_STRUCTURE]
Как можно увидеть формат описания переменных в точности повторяет таковой описанный для Расширений.
Настройки по умолчанию для вновь создаваемых категорий можно изменить на странице общих настроек Модуля (Управление сайтом → Расширения → Имя модуля → Конфигурация). Конечные настройки для каждой из категорий могут быть настроены следующим образом: Управление сайтом → Расширения → Имя модуля → кнопка Структура, далее напротив нужной категории кнопка Конфиг.
Обновление расширений
Разделы: Документация / Администрирование
Вы, вероятно, читали об обновлениях в Cotonti и знаете, как обновлять систему в целом. В этой статье обновление расширений рассматривается подробно. Слово "расширение" означает "модуль" или "плагин" в Cotonti.
Расширения обновляются в двух случаях:
Строго рекомендуется использовать функцию "Обновить" вместо переустановки расширений. Переустановка была необходима в Cotonti 0.6.x, но более не нужна. Обновление работает гораздо разумнее.
Для каждого обновляемого расширения Cotonti выполняет следующее:
XTemplate для программистов
Разделы: Документация / Расширяем Cotonti / Расширения
Каждый, кому приходилось создавать или изменять шаблоны Cotonti, видел и использовал шаблон теги. Теги - это короткие кусочки кода, которые при разборе (парсинге) системой XTemplate, замененяются на блок HTML-кода. Это обеспечивает существование файла шаблона только в виде HTML-кода. Любой код, сгенерированный PHP, поддерживается с помощью плагина и анализируется с помощью тега.
При разработке плагина, важно знать, как определять теги и условные блоки в системе XTemplate. Раньше большинство плагинов использовали обычный способ получения HTML для разбора и отображения. Хотя использование XTemplate и свой собственный файл шаблона гораздо приятный способ построить свой плагин, вы все еще можете использовать классический способ для standalone плагинов. Это можно сделать с помощью переменных $plugin_title, $plugin_subtitle и $plugin_body. Они автоматически присваиваются тегам {PLUGIN_TITLE}, {PLUGIN_SUBTITLE} и {PLUGIN_BODY}. В этом случае, вам не нужно создавать свой собственный файл шаблона (и вы можете не включать tpl каталог). Cotonti будет использовать plugin.tpl из скина взамен него.
Итак, вы хотите использовать свой собственный файл шаблона. Вы начинаете с определения файла шаблона в качестве нового объекта XTemplate. Это верно, система XTemplate является объектно-ориентированной частью кода. После того как вы создали новый объект XTemplate, вы можете использовать набор методов (функций), поставляемых с классом XTemplate. Мы будем использовать только два из них: assign() и parse(). Сначала мы создаем новый объект XTemplate:
$t = new XTemplate(‘path/to/file.tpl’);
We are using $t as the XTemplate object variable name, but you can use any variable name you like. The ‘path/to/file.tpl’ is the path to the template file, from the Cotonti root folder. While this would work perfectly fine, it’s not a very flexible way to define the template file. Therefore we will use the cot_tplfile() function instead, like this:
$t = new XTemplate(cot_tplfile('pluginname', 'plug'));
Первым параметром является имя файла без расширения. Второй параметр должен быть установлен в 'plug', поскольку мы имеем дело с плагином. Другие возможные значения 'module' и 'core'.Функция cot_tplfile() будет искать правильный путь к файлу шаблона. Имя файла всегда должно начинаться с pluginname. Если вы хотите использовать несколько файлов шаблонов, вы должны использовать имена вроде этого: pluginname.secondary.tpl. Не забудьте опустить расширение при использовании cot_tplfile().
Следующим шагом является назначение некоторых тегов в шаблоне файла. Мы делаем это с помощью метода assign() нашего объекта XTemplate:
$t->assign();
Метод assign() может может принять один тег или массив тегов:
$t->assign('SINGLE_TAG', '<p>Piece of HTML</p>');
$t->assign(array(
'TAG_ONE' => '<p>Piece of HTML</p>',
'TAG_TWO' => $somevariable
));
Как вы можете видеть, очень просто назначить кучу тегов сгенерированного PHP контента. Хотя это хороший способ для реализации шаблонов дизайна MVC, но не очень гибкий. Что делать, если вы хотите отобразить несколько строк контента из базы данных? XTemplate использует HTML-комментарий и метод parse(), чтобы позволить это. Допустим, вы только что выполнили SQL запрос, чтобы получить все страницы. Скорее всего, вы будете использовать цикл while для прохода по строкам. Рассмотрим следующий код:
while($row = $sql->fetch())
{
$t->assign(array(
'PAGE_ROW_ID' => $row['page_id'],
'PAGE_ROW_TITLE' => $row['page_title']
));
}
Этот код позволяет переопределять теги в каждой итерации цикла while, и в результате теги будут установлены в значение последней строки. Чтобы предотвратить это, мы должны заставить разбирать теги непосредственно после их определения. Это достигается с помощью метода parse().
$t->parse();
Метод parse() принимает один параметр: блок кода. Блок кода является уникальным кодом, который находится внутри файла шаблона в виде HTML комментариев. Он всегда содержит BEGIN и END, как здесь:
<!-- BEGIN: BLOCK_CODE --> ... <!-- END: BLOCK_CODE -->
Возможно, вы заметили, что каждый файл шаблона Cotonti начинается и заканчивается таким тегом, фактически определяющим весь документ в виде блока. Как правило, это блок MAIN, но вы можете использовать другой, если вы действительно хотите этого.
В PHP-коде плагина мы добавим метод parse() к циклу while:
while($row = $sql->fetch())
{
$t->assign(array(
'PAGE_ROW_ID' => $row['page_id'],
'PAGE_ROW_TITLE' => $row['page_title']
));
$t->parse('MAIN.PAGE_ROW');
}
Только что определенный блок называется ‘PAGE_ROW’, а поскольку он будет использоваться в блоке MAIN, мы добавляем блок с названием родительского блока и точку, чтобы разделить их. Наш шаблон может выглядеть следующим образом:
<!-- BEGIN: MAIN -->
<h1>{SINGLE_TAG}</h1>
<!-- BEGIN: PAGE_ROW -->
<p>{PAGE_ROW_TITLE}</p>
<!-- END: PAGE_ROW -->
<!-- END: MAIN -->
Если вы не хотите или не можете использовать блок MAIN, вы можете заменить его на другой код. Однако это потребует от вас сделать еще один разбор в конце кода плагина. Блок MAIN автоматически анализируется Cotonti, но любой другой блок должен быть обработан вручную вашим плагином. Просто вызовите метод parse() снова, и, наконец, выведите блок (для standalone):
$t->parse('ALTERNATIVE');
$t->out('ALTERNATIVE'); // Only for standalone
Лучше всего делать это непосредственно перед закрывающим тегом PHP.
Установка плагинов
Разделы: Документация / Администрирование
Что такое Расширение
По сути — это PHP-скрипт (или их набор), включаемый в заранее определенные области ядра Cotonti, реализующий дополнительную функциональность.
Функциональность
Размер и сложность архитектуры плагина зависят от конечной цели, поставленной перед его разработчиком. Плагины бывают как очень простые (вывод последних опубликованных страниц), так и довольно масштабные (фото- или видеогалерея).
Готовые плагины смотрите в разделе «Расширения».
Cotonti построена таким образом, что ее штатный функционал может быть изменен за счет Расширений. Архитектура каждого Расширения должна подчиняться определенным правилам, благодаря чему реализуется автоматизация их установки и настройки.
На заметку: по историческим причинам в Cotonti существует 2 типа Расширений (Модули и Плагины). Разница между ними, с точки зрения конечного кользователя или Администратора, не значительная. Поэтому в рамках этой статьи мы не будем вдаваться в подробности их различий и опишем общие принципы установки и настройки.
Раширения могут различаться по принципу своей работы: автономные, обычно производящие какой-либо вывод на отдельной странице, и интегрируемые, целью которых является изменение текущего поведения модулей Cotonti.
В качестве примера попытаемся установить плагин User’s pages. Скачайте его на свой ПК, распакуйте архив. В распакованном архиве будет лежать папка, которая и является плагином. Иногда в этой папке можно найти инструкции от разработчиков по установке плагина или документы лицензионного соглашения.
На заметку: пожалуй самая не однозначная для новичка часть в процекссе установки Расширения это определить тип Расширения (Модуль это или Плагин), т.к. в зависимости от типа необходимо разместить код Расширения в соответствующей типу системной папке — Modules или Plugins.
На заметку: имена некоторых системных папок могут быть изменены Администратором на этапе установки системы (CMF). Для подробностей смотри файл настроек config.php и его описание.
Папку (userpages) необходимо скопировать на сайт в каталог /plugins/. Сделать это можно посредством любого FTP-клиента.
Рис. 1. Загрузка плагина в каталог /plugins/ с помощью FTP-клиента Total Commander.
Зайдите на сайт в раздел Админка → Расширения и найдите вновь загруженный файл в списке расширений (рис. 2).
Рис. 2. Список плагинов в админ-панели сайта.
Имя папки плагина одновременно является и кодовым именем (slug) плагина. Поэтому, для более точной идентификации, осуществлять поиск лучше по коду (кодовому имени) плагина (в нашем случае — userpages).
После завершения процесса установки плагина (для этого нажмите кнопку «Установить») вы увидите страницу описания плагина.
Наиболее интересные нам области выделены рамкой (рис. 3).
Рис. 3. Страница детального описания плагина.
Некоторые плагины позволяют производить настройку (если есть такая возможность) через административный интерфейс. Для этого просто перейдите по ссылке «Изменить».
Данный плагин состоит только из одной части, вызываемой по хуку users.details.tags.ajax (это как раз и есть тот самый хук, о которым мы говорили выше).
Подробнее о «Хуках» читайте в отдельной статье.
Обычно нужные права доступа к плагину установлены по умолчанию его разработчиком, но для надежности все же стоит это проверить после установки плагина на сайт. Перейдите на страницу настройки прав доступа (рис. 4) и установите нужные на ваше усмотрение значения.
Рис. 4. Настройка прав доступа.
Виды прав:
Более подробно с темой прав пользователей и их настройкой можно ознакомится в статьях: «Пользователи и Группы», « Управление правами в Cotonti»
Т. к. User’s pages является интегрируемым плагином, для его работы мы должны разместить в шаблоне сайта определенные TPL-теги, выводящие результат работы плагина. В нижней части страницы описания плагина (рис. 3) находится перечень TPL-тегов плагина. Данные теги необходимо (в нашем случае) разместить в любом удобном для вас месте шаблона users.details.tpl (он располагается в директории /themes/имя_шаблона_сайта/).
На этом установку и настройку можно считать завершенной.
Более подробно о Шаблонах и Тегах читайте, например, тут и тут.
Существует два способа прекратить работу плагина:
Первый способ нужно использовать в случае, если вы планируете в дальнейшем возобновить работу плагина или просто желаете сохранить его настройки и данные в БД (при наличии таковых).
Используйте второй способ только будучи полностью уверенными, что текущие настройки плагина и данные в БД в будущем вам не понадобятся.