Введение в создание расширений

Первые шаги в создании модулей и плагинов для Cotonti

#1. Введение

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

#2. Создаем свой модуль. Краткая информация

Создание модулей / плагинов незначительно отличается для Cononti Siena от Cotonti Genoa. Основные отличия – явный доступ к мультихукингу и возможность добавления настроек модуля для различных его категорий, о чем будет рассказано позднее.

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

Если вы планируетет писать свое расширение, то первое, чего придется начать это выбор условного имени (иными словами «кодового имени») под которым оно будет распознаваться системой и под которым оно будет храниться на диске (т.к. имя папки расширения должно полностью соответствовать выбранному «кодовому имени»). При выборе имени стоит придерживаться следующих правил:

  1. быть достаточно уникальным — не пересекаться с другими установленными модулями или плагинами (по возможности отличаться от названия расширений других разработчиков) ;
  2. использовать в имени только нижний регистр букв;
  3. имя может содержать только буквы, цифры и знак подчеркивания (пробелы, специальные символы, символы национального алфавита — не допускаются).

Внимание! При не соблюдении данных простых правил вы можете столкнуться с нестабильной работой системы или даже полным ее отказом.

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

Каждое расширение в обязательном порядке должно иметь «установочный» файл. Это точка входа или привязки вашего расширения к ядру системы.

Структура файла установки (module.setup.php), на примере установщика модуля page:

<?php
/* ====================
[BEGIN_COT_EXT]
Name=Pages
Description=Pages and Categories
Version=0.9.0 
Date=2010-nov-25 
Author=Neocrome & Cotonti Team
Copyright=(c) Cotonti Team 2008-2011
Notes=BSD License
Auth_guests=R
Lock_guests=A 
Auth_members=RW1
Lock_members=
Admin_icon=img/adminmenu_page.png
[END_COT_EXT]

[BEGIN_COT_EXT_CONFIG]
markup=01:radio::1:
[END_COT_EXT_CONFIG]

[BEGIN_COT_EXT_CONFIG_STRUCTURE] 
order=01:callback:cot_page_config_order():title:
[END_COT_EXT_CONFIG_STRUCTURE]
==================== */ 

Setup файл представляет собой три блока опций: COT_EXT (между тегами [BEGIN_COT_EXT][END_COT_EXT]) – информация о самом модуле / плагине (была подробно рассмотрена, COT_EXT_CONFIG – конфигурация модуля / плагина, COT_EXT_CONFIG_STRUCTURE – настройки для отдельных элементов структуры модуля.

#2.1. Основные параметры

Рассмотрим важные элементы блока COT_EXT:

Name — обязательны блок имени модуля/плагина

Version — Версия. Четко ведите нумерацию версий. Она необходима для корректного обновления модуля/плагина в последующем. Избегайте скачков версий. Вот несколько действительных правил относительно нумерации:

  1. При нумерации используйте принцыпы семантического версионироания.
  2. Если используетет для отдельных файлв расширения описания в формате PHPDoc, старайтесь исключить указания в них дополнителных версий с применением тега (@version) т.к. это приведет к необходимости поддерживать соответствие значения тегов и основной версии расширения или приведет к путанице в нумерации.
  3. При разработке и внесении правок слияющих на поведение расширения старайтесь отражать это в номере версии (см.п.1). Это особенно актуально если вы ведте разработку своего расширения с использованием систем контроля версий или выкладываете свои разработки в общий доступ. Это упростит пользователям вашего расширения процедуру скачивания нужной версии и правильного обновления своего сайта. 
  4. При использовании публичных систем контроля версий (как например GitHub)  — следите чтобы версии указываемые в тегах соответствовали действительным версиям расширения указанным в setup файле (пример).

Date — Дата выпуска / последних изменений в плагине (информационное поле, реально не используется внутри системы, но облегчает понимание у пользователя при установке/обновлении).

Auth_guests / Auth_members — права, которые будут включены по умолчанию для гостей / пользователей (группа 4). Используется система RWA12345 (Чтение / Запись / Администрирование / 5 дополнительных ключей)

Lock_guests / Lock_members — права, которые будут заблокированы (недоступны для редактирования) для гостей / пользователей

Немного подробнее о системе прав читайте в отдельной статье.

Admin_icon — Путь к иконке. Если необходимо добавить иконку в шапку админ-панели. Данная опция доступна только лишь для модулей с подключенной частью admin.

#2.2. Параметры настройки расширения

Блок COT_EXT_CONFIG и COT_EXT_CONFIG_STRUCTURE содержать информацию в одинаковом формате, поэтому рассматривать их будем блоком. Данные модули позволяют нам добавить конфигурацию/настройки модуля в админ-панели. COT_EXT_CONFIG – вывод общих опций для плагина. Используются на сайте как $cfg[‘plugins’][‘код_плагина’][‘опция‘] - для плагинов или $cfg[‘код_модуля’][‘опция’] — для модулей. OT_EXT_CONFIG_STRUCTURE — доступен только для модулей, которые используют категории (например модули page и forums). Доступ к данным опциям $cfg[‘код_модуля’][‘код_категории’][‘опция’].

Теперь собственно о структуре строки опции в конфиг файле:

Код_опции=Номер:Тип:Параметры:По_умолчанию:Подпись

Подпись – это то, как будет отображаться текст в админ-панели. Данную часть можно указать непосредственно в setup файле, или использовать lang файлы, где подпись будет в формате:

$L[‘cfg_код_опции’] = array(‘Подпись’, ‘Дополнительная пояснительная записка’);

Номер – это последовательность отображения данной опции в админ-панели при конфигурации модуля/плагина.

По_умолчанию – значение по умолчанию, которое будет выставлено сразу после установки модуля/плагина.

Тип – тип поля, существуют следующие типы полей (смотрим функцию cot_config_parse() файла configuration.php):

- string – строка. Параметры не используются

- select – Селект. В качестве параметров указываются варианты выбора. Данные варианты доступны для локализации в виде ланг строки $L['cfg_код_опции_params'] = array(); (введено в сиене)

- radio – радио-выключатель. Может быть 0 – выключен или 1 - включен.

- callback – callback функция – в качестве параметра указывается имя функции (новое в сиене)

- hidden – параметр не доступный для правки из-под админ панели (новое в сиене).

- separator – специальный вид конфигуратора. Необходим для визуального разделения большого количество опций в админ-панели (новое в сиене).

- range – диапазон. Тот же select – но в виде диапазона чисел. В качестве параметров через запятую указывается минимальное и максимальное значение (новое в сиене).

- textarea – текстовое поле.

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

С параметрами разобрались. Все необходимы прочие действия при установке, будь то SQL патчи или PHP, находятся в папке setup модуля (модуль.install.php, модуль.uninstall.php, модуль.install.sql, модуль.uninstall.sql).

#2.3. Отдельные части расширения

Помимо этого, при установке Cotonti необходимо «знать», какой файл для чего использовать и где использовать. Для этого у всех файлов в корневой директории должны быть прописаны заголовки в определенном формате:

/* ====================
[BEGIN_COT_EXT]
Hooks=admin
[END_COT_EXT]
==================== */

В отличие от Cotonti Genoa в Cotonti Siena обязательно указывается лишь хук, остальные элементы автоматически указываются.

Hooks - это место, в котором наш файл будет подключен. Помимо хуков внутри файлов есть еще, которые необходимы для отдельного независимого отображения страницы – standalone, ajax (отображение страницы без шапки и футера), tools(админка для плагинов), admin (админка для модулей). Можно указывать не 1 хук, а несколько через запятую – тогда файл будет подключен в нескольких местах.

При необходимости вы можете найти исчерпывающую информацию в статье Хуки (или перехват управления).

Order – еще 1 параметр, который доступен для объявления, И по умолчанию равен 10. Необходим для создания правильной очередности подключения файлов для данного хука.

Tags – например header.tpl:{TAG1}, {TAG2}; footer.tpl:{TAG3} – указывает теги, которые будут использованы в шаблонах, необходимо для того чтобы облегчить установку плагина администраторам сайта.

Хотелось бы напоследок отметить еще одно ключевое отличие Siena: теперь все файлы модуля должны(!) иметь определенное имя:

КОДМОДУЛЯ.ЧАСТЬ.php

О других возможностях в работе инсталятора будет написано позднее.

#2.4. Дополнительный материал

Кроме приведенной здесь информации рекомендуем вам ознакомится и с другими статьями из раздела «Расширения», а так же методами локализации расширений.

 



1. diiagma  31.08.2011 09:47

You guys rock ! Congrats for your open source solution this is great. I finished the install part and I will start to develop some plugins and modules soon, thanks for your 1st tutorial it is presious help for a newbie like me.

 

 

2. Macik  10.09.2015 18:01

Some tutorial [in russian] you can find here: forums?m=posts&q=7887
Пошаговая инструкция по созданию плагина от одного из пользователейforums?m=posts&q=7887

Добавление комментариев доступно только зарегистрированным пользователям