χάμστερ :: Главная::Программизм::PHP::Cms Made Simple::Некоторые особенности написания модуля

На данной странице будут небольшие пометки об особенностях написания модуля для cmsmadesimple. В основном, чтобы самому не забыть.

Общие сведения:

1. Для того чтобы модуль заработал необходимы следующие условия: название модуля, название класса, название папки должны совпадать. Название файла, в котором расположен основной класс должен иметь вид: module_name.module.php и располагаться в соответствующей папке. Класс модуля должен наследоваться от класса CMSModule. Например, чтобы создать модуль с названием MyBestModule нужно в папке /modules создать папку MyBestModule, затем внутри папки /modules/MyBestModule создать файл MyBestModule.module.php,  а внутри файла создать класс: class MyBestModule extends CMSModule {}

2. Новый класс должен переопределить некоторые методы базового класса. Основные методы и их особенности.

GetName - возвращает название класса (ну или название модуля, что одно и тоже).

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

GetAuthor, GetAuthorEmail - возвращают имя и email автора модуля. Эти параметры выводятся в справке.

MinimumCMSVersion, MaximumCMSVersion - возвращают минимальную и максимальную версии системы на которых данный модуль должен работать. Система развивается, меняется архитектура и API взаимодействия модуля с системой. Это нужно контролировать.

IsPluginModule - возвращает булевское значение, которое говорит о том, что модуль можно вызывать в контенте или шаблонах при помощи тэга cms_module.

HasAdmin - возвращает булевское значение, которое говорит о том, есть ли у модуля административный интерфейс.

GetAdminSection - возвращает раздел административного интерфейса, в котором днаходится доступ к интерфейсу модуля. Возвращает одно из следующих значений:

• content - раздел Контент,
• layout - раздел Оформление,
• files - ?,
• usersgroups - раздел Пользователи и группы,
• extensions - раздел Расширения (если метод не переопределен - используется данное значение),
• preferences - ?,
• siteadmin - раздел Администрирование сайта,
• ecommerce - ?

SuppressAdminOutput - на входе массив $_REQUEST, на выходе булевское значение. Это интересный метод, который позволяет управлять генерацией административной страницы. По умолчанию страницы административного интерфейса выводятся с использованием текущей темы, тоесть не нужно специально подключать заголовок и нижнюю часть, достаточно сформировать только то, что необходимо для управления (форму, список и тп). Но иногда нужно вывести только дасть данных, например, результат выполнения аякс запроса (в котором, например, нужно вернуть json массив или часть контента). Данный метод позволяет определить - нужно ли выводить готовый контент полностью в шаблоне административного интерфейса (если метьод возвращает false) или вернуть только то, что сформировано соответствующим методом админки. Например, у нас есть основная страница административного интерфейса (action.defaultadmin.php), который выводит главную страницу административного интерфейса модуля. Мы хотим подгрузить часть контента аяксом из другого метода, например, action.adminajax.php. Для того, чтобы action.adminajax.php вернул не полностью страницу а только нужный контент можно сделать следующим образом:

1. переопределяем метод SuppressAdminOutput:

function SuppressAdminOutput($request) {
    // Из служебного параметра получаем префикс параметров модуля
    // - это нужно, чтобы найти нужный параметр в общем списке,
    // созданном стандартными средствами системы
    $p = explode(',', $request['mact']);
    // ищем, есть ли параметр с именем isajax, если есть, то говорим системе,
    // что данную страницу нужно отдать без шаблона 
    return isset($request[$p[1] . "isajax"]);
}

2. при создании AJAX ссылки используем стандартный метод, в котором добавляем нужный параметр:

$href = $this->CreateLink(
    $id,
    'adminajax',
    $returnid,
    '',
    array(
        'isajax'    => true,
    ),
    '',
    true);

$href Будет содержать адрес вызова метода adminajax, в результате выполнения которого будет возвращен только сгенерированный контент без шаблона. Если убрать параметр 'isajax' => true, - то ссылка будет вести на страницу которая будет сгенерирована с учетом шаблона.

Есть еще одна особенность: помимо метода, в котором мы сами можем указать, как определять - нужна ли нам полная страница или только контент, есть еще стандартный механизм - если в массиве $_REQUEST будет переменная suppressoutput, например, мы добавили к адресу ?suppressoutput=1, то эта страница так-же будет выведена без учета шаблона.

Установка, обновление, удаление модуля

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

Еще один момент - вместо переопределения методов (Install, Upgrade, Uninstall) можно создать файлы в корне модуля (соответственно method.install.php, method.upgrade.php, method.uninstall.php, в которые можно вписать соответствующий код.