"Классные" процессоры в MODX 2.2

Предлагаю вам свой очень вольный перевод записи из блога Mark Hamstra о новых процессорах, основанных на классах. Я буду называть их «классными» процессорами — так короче и точнее отражает их суть.

Одно из изменений в MODX 2.2 это новая, полностью переделанная система процессоров, основанных на классах («классные» процессоры), позволяющие вам cущественно упростить создание процессоров для компонентов. Как и любая обновка — эта позволяет вам использовать несколько новых фокусов.

Я использовал эти процессоры в своем новом проекте, и теперь хочу распространить эти наработки где только можно.

Что такое «классные» процессоры?
Если вы уже создавали компоненты для MODX, то вы знаете, что такое процессор — это php файл, который запускается AJAX коннектором (или modX::runProcessor), делает, все что от него требуется и возвращает ответ в виде JSON строки.

«Классные» процессоры упрощают эту работу. Например, вы можете использовать подобный код для обновления какого-то элемента:

<?php
class fdmPriceCodeUpdateProcessor extends modObjectUpdateProcessor {
    public $classKey = 'fdmPriceCode';
    public $languageTopics = array('frontdeskman:pricing');
    public $objectType = 'fdmp';
}
return 'fdmPriceCodeUpdateProcessor';

… и MODX сделает всю работу за вас.

Что делает modObjectUpdateProcessor?
Несмотря на минимум кода, который мы использовали, для его корректого выполнения происходит много всяких неочевидных процессов.

Разбираясь в классе modProcessor, я нашел 14 этапов для выполнения modObjectUpdateProcessor

1. Стартует ваш процессор, устанавливаются его свойства.
2. Запускается функция checkPermissions(), который вы можете использовать для проверки любых прав доступа.
3. Запускается функция getLanguageTopics(), который возвращает массив языковых словарей, затем они загружаются.
4. Стартует функция initialize(): она берет первичный ключ (из публичной переменной primaryKeyField, обычно это «id»), затем достает объект нужного класса по этому ключу, и, если это наследник modAccessibleObject, проверяет юзера на соответствие политике «save». Если initialize() не возвращает true — запрос отменяется, с ошибкой.
5. Стартует beforeSet(): по умолчанию он просто проверяет, не установлено ли ошибок (например, так — $this->addFieldError('fieldname','error')). Если эта функция не возвращает true — запрос завершается с ошибкой.
6. Вызывается fromArray() из объекта (он доступен через $this->object) для присвоения поученных при запуске свойств.
7. Запускается beforeSave(). Как и beforeSet(), этот метод проверяет наличие ошибок. Если он не возвращает true — запрос возвращает сообщение об ошибке.
8. Объект вызывает validate(). Если эта функция не возвращает положительное значение — выставляются ошибки в соответствие с проверенными значениями.
9. Если вы выставили переменную beforeSaveEvent в своем классе, вызывается выставленное событие (invoke event) и если не возвращается true — сохранение не происходит. Учитывая, что fireBeforeSaveEvent() отмечена как публичная, обычно вам не нужно выставлять эту переменную.
10. Вызывается saveObject(), которая просто делает save() объекта. В соответствии с комменариями в коде, эта функция может быть переназначена для каких-то особенных изменений объекта.
11. Запускается fireAfterSaveEvent(), которая вызывает событие, указанное в переменной afterSaveEvent класса.
12. Срабатывает logManagerAction(), для записи стандартного сообщения в Журнал системы MODX (вы его найдете в «Отчеты» → «Журнал системы управления»).
13. Возвращается сообщение об успешном завершении процесса через функцию cleanup(). Она, на самом деле, просто оборачивает $modx->error->success/failure, который использовался в процессорах до версии 2.2.
14. Ответ (успех или ошибка) парсится в объект modProcessorResponse и возвращается вам.

Обратите внимание, как много в списке жирного текста. Это функции, или переменные, которые доступны вам для переназначения и расширения, чтобы вы могли сделать, что вам нужно. Запомните, что каждый «классный» процессор (create, update, getlist, remove и get) имеет собственные методы. Если вы используете IDE типа PhpStorm — вы получите подсказки в коде. Если нет — погружайтесь в исходник.

Расширяем наш процессор для обработки чекбоксов
Когда вы сделали замечательное окно на modExt/ExtJS и прилепили туда активный чекбокс (xtype: 'checkbox') — оно может работать не так, как вы задумали. Возможно, ваша схема БД ожидает булево true или false (я знаю — у меня так!), которое будет сохранено в БД в поле с типом tinyint 1 или 0. А вот форма вам отправит поле чекбокса как «on», если он отмечен, или пустоту — если нет. Оба-на…

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

Посмотрите снова на список из 14 шагов. Метод fromArray() запускается на 6м этапе, значит, нам надо поменять значение чекбокса до него. Как вы смотрите на «BeforeSet», в 5м этапе? По моему, должно сработать!

Если вы не особо знакомы с объектно-ориентированным программированием (ООП), то вся эта писанина может показаться вам непонятной фигней. На самом деле, мы просто переписываем родные методы стандартного процессора своими, чтобы изменить его как нам надо. В интернете навалом книжек по ООП в PHP, которые вы можете почитать, если интересно.

Итак, теперь мы меняем наш первый пример, чтобы изменить значение чекбокса при помощи «beforeSet»:

class fdmPriceCodeUpdateProcessor extends modObjectUpdateProcessor {
    public $classKey = 'fdmPriceCode';
    public $languageTopics = array('frontdeskman:pricing');
    public $objectType = 'fdmp';
 
    public function beforeSet() {
        $this->setProperty('active',($this->getProperty('active') == 'on'));
        return parent::beforeSet();
    }
}
return 'fdmPriceCodeUpdateProcessor';

Здесь мы использовали тернарный оператор вместе с функциями getProperty и setProperty от процессора. Но если вам нравится более подробный код — можно написать иначе, на результат это никак не влияет:

/* ... */
    public function beforeSet() {
        $active = $this->getProperty('active');
        if ($active == 'on') { $active = true; }
        else  { $active = false; }
        $this->setProperty('active',$active);
        return parent::beforeSet();
    }
/* ... */

Мы можем сделать что-то подобное и с процессором remove, для предотвращения удаления элемента, если он все еще связан с другим элементом.
Например, следующий процессор не удалит объект «fdmCharacteristic», если тот еще связан с объектами «fdmRoomTypeCharacteristic».

<?php
class CharacteristicRemoveProcessor extends modObjectRemoveProcessor {
    public $classKey = 'fdmCharacteristic';
    public $languageTopics = array('frontdeskman:property');
    public $objectType = 'rtc';
     
    public function beforeRemove() {
        $chars = $this->modx->getCount('fdmRoomTypeCharacteristic',array('characteristic' => $this->getProperty('id')));
        if ($chars > 0) {
            return $this->modx->lexicon('rtc.remove.roomtypesStillLinked');
        }
        return parent::beforeRemove();
    }
}
return 'CharacteristicRemoveProcessor';

Последний пример на сегодня расширяет modObjectGetListProcessor для присоединения (join) таблицы и фильтрации по ее свойствам. Мы этого добиваемся изменением функции prepareQueryBeforeCount(). Так же, мы присваиваем еще немного переменных.

<?php
class RoomTypeGetListProcessor extends modObjectGetListProcessor {
    public $classKey = 'fdmRoomType';
    public $languageTopics = array();
    public $defaultSortField = 'name';
    public $defaultSortDirection = 'ASC';
    public $objectType = 'fdmRoomType';
 
    /**
     * @param xPDOQuery $c
     * @return \xPDOQuery
     */
    public function prepareQueryBeforeCount(xPDOQuery $c) {
        $query = $this->getProperty('property');
        if (!empty($query) && is_numeric($query)) {
            $c->innerJoin('fdmRoomTypeProperty','RTP','fdmRoomType.id = roomtype');
            $c->where(array(
                'RTP.property' => (int)$query
            ));
        }
        return $c;
    }
}
return 'RoomTypeGetListProcessor';

Замечание про чекбоксы в modExt
Я использовал тип «checkbox», хотя в MODX с версии 2.1 есть тип «xcheckbox», который присылает значение (1 или 0, если мне не изменяет память). Не знаю, почему я не использовал его, но наверняка «классный» процессор будет работать и с ним. Просто не проверял, и я люблю все контролировать.

«Просто интересно… Вы работаете над компонентом по управлению недвижимостью?»
Как вы догадались?! :)

Что меня выдало: объект «fdmRoomType», «fdmRoomTypeCharacteristic» или «fdmProperty»? :)

Супер-пупер компонент, над которым я сейчас работаю называется FrontDeskMan и я надеюсь закончить его в течении нескольких недель. Он не будет доступен как Open Source, но наверняка мы будем продавать на енго лицензии и поддерживать его, как расширение для индустрии туризма и развлечений в моем совместном проекте с Jared Loman.
Вы уже можете готовить клиентов местных отелей к новому вебсайту с интегрированным управлением комнатами и бронированием, когда мы стартуем!