Серверні події

Серверні події

Commerce встановлює на сайт додаткові події, які можна перехоплювати за допомогою плагінів і тим самим додавати свою логіку в процеси магазину.

В основному в подіях використовується передача параметрів по посиланню, тобто щоб змінити щось, не потрібно повертати результат - досить змінити значення параметра. Невеликий приклад:

switch ($modx->event->name) {
    case 'OnBeforeCartItemAdding': {
        $params['item']['price'] += 100;
        break;
    }
}

Тут видно два важливих моменти:

• Використовується саме $modx->event->name замість сформованої практики збереження посилання на $modx->Event, так як Commerce активно використовує вкладені події (http://modx.im/blog/docs/5933.html).
• Змінюється саме елемент масиву $params, а не змінна $item, так як посилання є тільки в масиві.

Опис подій

OnInitializeCommerce

Старт ініціалізації основного плагіна. Параметрів немає.

Може використовуватися для реєстрації клієнтських скриптів, які залежать від Commerce, для реєстрації додаткових корзин, сховищ, додавання елементів в контейнер залежностей та ін.

switch ($modx->event->name) {
    case 'OnInitializeCommerce': {
        ci()->set('myCustomClass', function($ci) use ($params) {
            require_once MODX_BASE_PATH . 'path/to/CustomClass.php';
            return new CustomClass($params);
        });

        $modx->regClientScript('path/to/custom-commerce-script.js');
        break;
    }
}

OnInitializeOrderProcessor

Викликається в момент отримання обробника замовлень. Можна зареєструвати свій обробник. Параметрів немає.

class CustomOrdersProcessor implements \Commerce\Interfaces\Processor {
    ...
}

switch ($modx->event->name) {
    case 'OnInitializeOrderProcessor': {
        $processor = new CustomOrdersProcessor($modx);
        $modx->commerce->setProcessor($processor);
        break;
    }
}

OnCollectSubtotals

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

Параметри:

Ім'я параметра	Передається по посиланню	Опис
rows	Так	Масив рядків, кожен рядок являє собою масив з ключами title і price - назва і ціна відповідно.
total	Да	Підсумкова вартість замовлення
realonly	Ні	Приймає значенняtrue, якщо збираються тільки елементи, які реально змінюють вартість замовлення. Це має сенс, щоб не зберігати із замовленням суто інформативні елементи.

switch ($modx->event->name) {
    case 'OnCollectSubtotals': {
        $params['total'] += 100;
        $params['rows']['fee'] = [
            'title' => 'Комісія магазину',
            'price' => 100,
        ];
        break;
    }
}

Щоб виводити додатковий збір тільки після переходу покупця до оформлення замовлення, можна використовувати метод обробника замовлень isOrderStarted():

if ($modx->commerce->loadProcessor()->isOrderStarted()) {
    // додаємо вартість доставки
}

Якщо висновок також залежить від обраного способу доставки або оплати, можна використовувати методи обробника getCurrentDelivery() і getCurrentPayment():

$processor = $modx->commerce->loadProcessor();
if ($processor->getCurrentDelivery() == 'mydelivery' && $processor->getCurrentPayment() == 'mypayment') {
    // додаємо вартість доставки
}

OnRegisterDelivery

Збір всіх доступних покупцеві способів доставки замовлення.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
rows	Так	Масив рядків<псевдонім> => <параметри>, де <псевдонім> це символьний ідентифікатор способу доставки, а <параметри> - це масив масив з наступними ключами: title назва способу доставки price ціна markup додатковий html-код

switch ($modx->event->name) {
    case 'OnRegisterDelivery': {
        $params['rows']['mydelivery'] = [
            'title' => 'Доставка',
            'price' => 100,
        ];
        break;
    }
}

OnRegisterPayments

Збір всіх доступних покупцеві способів оплати. Параметрів немає.

class CustomPayment implements \Commerce\Interfaces\Payment {
    ...
}

switch ($modx->event->name) {
    case 'OnRegisterPayments': {
        $class = new CustomPayment($modx, $params);
        $modx->commerce->registerPayment('mypayment', 'Мій спосіб платежу', $class);
        break;
    }
}

Часто буває так, що способи оплати замовлення залежать від обраного способу доставки. У такому випадку можна використовувати метод обробника замовлення getCurrentDelivery() для організації умов:

if ($modx->isBackend() || $modx->commerce->loadProcessor()->getCurrentDelivery() == 'mydelivery') {
    // реєструємо оброблювач платежу
}

Важливо також зауважити, що в цьому прикладі використовується перевірка $modx->isBackend(),щоб призначені для користувача умови не впливали на доступність методу оплати при редагуванні і перегляді замовлень в панелі адміністрування.

OnBeforeOrderAddonsRender

Викликається перед виведенням способів доставки і оплати, після їх реєстрації. Можна змінити обраний спосіб, змінити їх склад. Зручно, коли доставка залежить від оплати, або навпаки.

Через те, що кошики виводяться окремо від форми замовлення, і зазвичай раніше її, зміна способів доставки ніяк не вплине на додаткові збори, встановлені даними способами доставки і на загальну суму замовлення.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
payments	Так	Масив способів оплати
delivery	Так	Масив способів доставки
current_payment	Так	Обраний спосіб оплати
current_delivery	Так	Обраний спосіб доставки

switch ($modx->event->name) {
    case 'OnBeforeOrderAddonsRender': {
        if (isset($params['delivery']['pickup'])) {
        // додаємо пояснення для самовивозу
            $params['delivery']['pickup']['markup'] .= '<p>Дочекайтеся дзвінка оператора для узгодження часу самовивозу!</p>';
    }

    if (isset($params['payments']['cash']) && $params['current_delivery'] != 'pickup') {
        // якщо доставка - не самовивезення, прибираємо спосіб оплати готівкою
        unset($params['payments']['cash']);
    }

    break;
    }
}

OnCommerceAjaxResponse

Викликається перед відправкою відповіді сервера при ajax-запиті, наприклад при додаванні в кошик або оновленні кошиків. Дозволяє модифікувати відповідь.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
response	Так	Масив елементів, з яких складається відповідь сервера. Ключ status є в будь-якому випадку, він може приймати значення success або failed і означає, успішний запит чи ні. Інші елементи в різних запитах розрізняються.

switch ($modx->event->name) {
    case 'OnCommerceAjaxResponse': {
        $url = trim($_GET['q'], '/');
        if ($url == 'commerce/action' && $_POST['action'] == 'cart/add') {
            $params['response']['myparam'] = 'myresponse';
        }
    break;
    }
}

OnBeforeCartItemAdding

Викликається перед додаванням товару в кошик. Дозволяє скасувати дію, або модифікувати атрибути додається товару.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
instance	Ні	Тип кошика
prevent	Так	Прапор скасування дії. Якщо переключити в true, товар не буде додано.
item	Так	Масив з атрибутами товару, що додається. Елементи наступні: id Ідентифікатор товару name Назва count Кількість price Ціна однієї одиниці товару options Масив додаткових опцій meta Масив додаткових даних

switch ($modx->event->name) {
    case 'OnBeforeCartItemAdding': {
        if ($params['item']['price'] < 100) {
            $params['prevent'] = true;
            $modx->event->stopPropagation();
        }
        break;
    }
}

OnBeforeCartItemUpdating

Викликається перед зміною товару в кошику. Дозволяє модифікувати змінювані атрибути.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
instance	Ні	Тип кошика
row	Так	Ідентифікатор змінного рядка кошика
item	Так	Масив з уже зміненими атрибутами товару
wasadded	Ні	Прапор, який означає, що першою дією було додавання товару
prevent	Так	Прапор скасування дії. Якщо переключити в true, товар не буде змінений

OnCartChanged

Викликається після будь-якої зміни кошика.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
instance	Ні	Тип кошика

switch ($modx->event->name) {
    case 'OnCartChanged': {
        if ($params['instance'] == 'products') {
            $cart = ci()->carts->getCart($params['instance']);

            if ($cart) {
                $items = $cart->getItems();

                if (count($items)) {
            // для прикладу збільшимо кількість товару в першому рядку
                    $row = key($items);
                    $items[$row]['count'] += 1;
                    $cart->setItems($items);
                }
            }
        }
        break;
    }
}

OnOrderRawDataChanged

Викликається при зміні даних в процесі оформлення замовлення.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
data	Ні	Дані замовлення

OnBeforeOrderProcessing

Викликається після валідації даних замовлення, до створення самого замовлення. Дозволяє модифікувати як дані покупця, так і склад кошика замовлення.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
FL	Так	FormLister
items	Так	Масив з товарами кошика

switch ($modx->event->name) {
    case 'OnBeforeOrderProcessing': {
        $FL->setField('name', 'Вася');
        break;
    }
}

OnBeforePaymentProcess

Викликається перед створенням платежу - після створення замовлення (якщо був обраний будь-який спосіб платежу), або при оплаті раніше створеного замовлення по спеціальному посиланню.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order	Так	Масив із даними замовлення
payment	Ні	Масив з описом і класом обробника платежу
FL	Так	FormLister. Присутній тільки в процесі оформлення замовлення
instant_redirect	Так	Якщо 1 - покупець відразу буде перенаправлений в платіжну систему, 0 - буде показаний шаблон redirect_template
redirect_text	Так	Текст повідомлення про перенаправлення на оплату. Присутній тільки в процесі оформлення замовлення
redirect_template	Так	Шаблон тексту повідомлення про оформлення замовлення і перенаправлення на оплату

switch ($modx->event->name) {
    case 'OnBeforePaymentProcess': {
        if (isset($FL) && $order['fields']['payment_method'] == 'mypayment') {
        $params['redirect_text'] = 'Перенаправлення!';
    }
        break;
    }
}

OnBeforePaymentCreate

Викликається при створенні і збереженні платежу, дозволяє змінити суму.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order_id	Ні	Ідентифікатор замовлення, який оплачується
order_amount	Ні	Вартість замовлення
amount	Так	Сума платежу, за вирахуванням суми сплачених раніше траншей
hash	Так	Хеш платежу, для формування посилань

switch ($modx->event->name) {
    case 'OnBeforePaymentCreate': {
        // отримуємо дані форми замовлення
        $data = ci()->commerce->loadProcessor()->getRawData();

        // якщо включена передоплата, зменшуємо суму вполовину
        if (!empty($data['partial'])) {
            $params['amount'] = $params['amount'] * 0.5;
        }

        break;
    }
}

OnBeforeOrderSaving

Викликається перед самим збереженням замовлення в базу даних, коли всі дані зібрані, при створенні, або оновленні замовлення. Дозволяє повністю змінити замовлення. Скасувати збереження не можна.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order_id	Ні	Ідентифікатор замовлення, null якщо замовлення нове
values	Так	Значення полів для збереження в таблицю commerce_orders
items	Так	Масив товарів, підготовлений для збереження в таблицю commerce_order_products
subtotals	Так	Масив доп. зборів, зберігається також в commerce_order_products в полегшеній формі

OnBeforeOrderSending

Викликається після збереження замовлення, перед відправкою повідомлення менеджеру.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
FL	Так	FormLister
order	Так	Дані замовлення
cart	Так	Дані збереженого кошика

OnOrderSaved

Викликається після збереження замовлення в базу даних.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order_id	Ні	Ідентифікатор замовлення
values	Так	Значення полів з таблиці commerce_orders
items	Так	Масив товарів з таблиці commerce_order_products
subtotals	Так	Масив дод.зборів із таблиці commerce_order_products

OnOrderProcessed

Викликається після закінчення обробки замовлення.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
FL	Так	FormLister
order	Ні	Дані замовлення
cart	Ні	Дані збереженого кошика

OnBeforeCurrencyChange

Викликається перед зміною поточної валюти. Дозволяє підмінити нову валюту на іншу. Параметри:

Ім'я параметра	Передається по посиланню	Опис
old	Ні	Символьний ідентифікатор поточної валюти
new	Так	Символьний ідентифікатор встановленої валюти

OnOrderPlaceholdersPopulated

Викликається після призначення плейсхолдерів з даними замовлення на сторінці переадресації після успішного оформлення замовлення або здійснення оплати.

Ім'я параметра	Передається по посиланню	Опис
order	Ні	Дані замовлення

OnBeforeOrderHistoryUpdate

Викликається перед додаванням історії замовлення. Дозволяє змінити статус і коментар, або скасувати додавання або повідомлення покупця.

Ім'я параметра	Передається по посиланню	Опис
order_id	Ні	ідентифікатор замовлення
status_id	Так	Ідентифікатор призначеного статусу замовлення
comment	Так	Коментар
notify	Так	Чи потрібно повідомляти покупця про зміну статусу, true або false
prevent	Так	Скасувати зміни історії, true або false

switch ($modx->event->name) {
    case 'OnBeforeOrderHistoryUpdate': {
        if ($status_id == 4) {
        $params['prevent'] = true;
            $modx->event->stopPropagation();
    }

    if ($status_id == 10) {
        $params['comment'] = 'Мій коментар';
    }
    }
}

OnBeforeCustomerNotifySending

Викликається перед повідомленням покупця при зміні історії замовлення або зміні даних замовлення. Дозволяє змінити повідомлення або скасувати відправку.

Ім'я параметра	Передається по посиланню	Опис
reason	Ні	Тип події: order_changed - додавання історії замовлення status_changed - зміна даних замовлення
order	Так	Дані замовлення
subject	Так	Шаблон теми листа-повідомлення
body	Так	Шаблон тексту листа-повідомлення
data	Так	Дані, які будуть використовуватися при парсінгу шаблонів листа
prevent	Так	Скасувати відправку повідомлення, true або false

Події панелі адміністратора

Ці події викликаються при роботі менеджера з замовленнями в панелі адміністрування магазином.

OnManagerBeforeOrdersListRender

Викликається перед виведенням списку замовлень. Дозволяє модифікувати висновок.

Ім'я параметра	Передається по повідомленню	Опис
config	Так	Конфігурація DocLister. Висновок формується його контролером onetable
columns	Так	Конфігурація колонок - массив пар ідентифікатор колонки => параметри колонки
filters	Так	Конфігурація фільтрів

Параметри конфігурації DocLister за замовчуванням:

[
    'orderBy'         => 'created_at DESC',
    'display'         => 10,
    'paginate'        => 'pages',
    'TplWrapPaginate' => '@CODE:<ul class="[+class+]">[+wrap+]</ul>',
    'TplCurrentPage'  => '@CODE:<li class="page-item active"><span class="page-link">[+num+]</span></li>',
    'TplPage'         => '@CODE:<li class="page-item"><a href="[+link+]" class="page-link page" data-page="[+num+]">[+num+]</a></li>',
    'TplNextP'        => '@CODE:',
    'TplPrevP'        => '@CODE:',
];

У параметрах колонок можна використовувати такі параметри:

Ім'я параметра	Опис
title	Тема колонки
content	Вміст. Може бути рядком - ім'ям поля з замовлення, або анонімної функцією з наступними параметрами: $data - дані замовлення $DL - посилання на об'єкт $_DocLister $eDL - посилання на об'єкт $_extDocLister
sort	Індекс для сортування
style	Css-стиль колонки, додається до кожної клітинки

Конфігурація колонок за замовчуванням:

[
    'id' => [
        'title'   => '#',
        'content' => 'id',
        'sort'    => 0,
        'style'   => 'width: 1%; text-align: center;',
    ],
    ...
    'name' => [
        'title'   => $lang['order.name_field'],
        'content' => 'name',
        'sort'    => 20,
    ],
    ...
    'email' => [
        'title'   => $lang['order.email_field'],
        'content' => function($data, $DL, $eDL) {
            if (!empty($data['email']) && filter_var($data['email'], FILTER_VALIDATE_EMAIL)) {
                return '<a href="mailto:' . $data['email'] . '">' . $data['email'] . '</a>';
            }
            return '';
        },
        'sort'    => 40,
        'style'   => 'white-space: nowrap;',
    ],
    ...
];

Приклад:

switch ($modx->event->name) {
    case 'OnManagerBeforeOrdersListRender': {
        $params['config']['display'] = 50;

        $params['columns']['lastname'] = [
            'title'   => 'Прізвище',
            'content' => function($data, $DL, $eDL) {
                if (!empty($data['fields']['lastname'])) {
                    return htmlentities($data['fields']['lastname']);
                }
                return '';
            },
            'sort' => 23,
        ];
    }
}

OnManagerOrdersListRender

Це стандартна подія Modx, розрахована на отримання рядка, яка буде виведена в кінці сторінки зі списком замовлень. Для установки значення потрібно використовувати метод $modx->event->setOutput().

Параметри:

Ім'я параметра	Передається по посиланню	Опис
orders	Ні	Масив замовлень для виведення

OnManagerBeforeOrderRender

Викликається перед виведенням детальної інформації про замовлення

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order	Так	Дані замовлення
groups	Так	Конфігурація груп з інформацією про замовлення
config	Так	Конфігурація DocLister для виведення товарів з замовлення
columns	Так	Конфігурація колонок для виведення товарів замовлення
subcolumns	Так	Конфігурація колонок для виведення додаткових зборів

Приклад:

switch ($modx->Event->name) {
    case 'OnManagerBeforeOrderRender': {
        $params['groups']['order_info']['fields']['msg'] = [
            'title' => 'Коментар',
            'content' => function($data) {
                return !empty($data['fields']['msg']) ? htmlentities($data['fields']['msg']) : '';
            },
            'sort' => 40,
        ];
    unset($params['columns']['options']);
    break;
    }
}

OnManagerOrderRender

Це стандартне подія Modx, розраховане на отримання рядка, яка буде виведена в кінці сторінки детального перегляду замовлення. Для установки значення потрібно використовувати метод $modx->event->setOutput().

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order	Ні	Масив з даними замовлення
products	Ні	Масив з товарами замовлення
subtotals	Ні	Масив з дод.зборами замовлення

OnManagerBeforeOrderEditRender

Викликається перед виведенням сторінки редагування замовлення.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order	Так	Дані замовлення
fields	Так	Конфігурація полів замовлення
config	Так	Конфігурація DocLister для виведення товарів з замовлення
columns	Так	Конфігурація колонок для виведення полів редагування товарів замовлення
subcolumns	Так	Конфігурація колонок для виведення полів редагування додаткових зборів

OnManagerOrderRender

Ця стандартна подія Modx, розрахована на отримання рядка, яка буде виведена в кінці сторінки редагування замовлення. Для установки значення потрібно використовувати метод $modx->event->setOutput().

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order	Ні	Масив з даними замовлення
products	Ні	Масив товарів замовлення
subtotals	Ні	Масив дод.зборів замовлення

OnManagerBeforeOrderValidating

Викликається при збереженні відредагованого замовлення перед валідацією нових значень.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
order	Ні	Оригінальні дані замовлення
data	Так	Масив з новими даними і правилами їх перевірки. Для перевірки правил використовується валідатор з комплекту FormLister.

Структура масиву з новими даними:

[
    'order' => [
        'data'  => [
            // дані замовлення
            'name' => 'Вася',
            'email' => 'test@test.test',
            ...
        ],
        'rules' => [
            // правила перевірки, наприклад:
            '!name' => [
                'lengthBetween' => [
                    'params' => [2, 255],
                    'message' => $lang['module.error.name_length'],
                ],
            ],
            'email' => [
                'email' => $lang['module.error.email_incorrect'],
            ],
            ...
        ],
    ],
    'cart' => [
        'data'  => [
            // дані кошика замовлення
        ],
        'rules' => [
            // правила перевірки
        ],
    ],
    'subtotals' => [
        'data'  => [
            // дані додаткових зборів замовлення
        ],
        'rules' => [
            // правила перевірки
        ],
    ],
];

OnManagerOrderValidated

Викликається після перевірки даних замовлення, незалежно від того, пройдена перевірка чи ні.

Параметри:

Имя параметра	Передается по ссылке	Опис
order	Ні	Дані замовлення
data	Так	Дані з події OnManagerBeforeOrderValidating
errors	Так	Масив з помилками.Якщо масив порожній - валідація пройде успішно, якщо немає - редагування замовлення буде скасовано, а помилки будуть виведені на екран

OnManagerStatusesListRender

Это стандартное событие Modx, рассчитанное на получение строки, которая будет выведена в конце страницы со списком статусов заказов. Для установки значения нужно использовать метод $modx->event->setOutput().

Параметри:

Ім'я параметра	Передається по посиланню	Описание
list	Ні	Масив зі статусами замовлень

OnManagerStatusRender

Це стандартна подія Modx, розрахована на оримання рядка, яка буде виведена в кінці сторінки редагування статусу замовлень. Для установки значення потрібно використовувати метод $modx->event->setOutput().

Параметри:

Ім'я параметра	Передається по посиланню	Опис
status	Ні	Масив з даними статусу замовлень

OnManagerCurrencyListRender

Це стандартна подія Modx, розрахована на отримання рядка, яка буде виведена в кінці сторінки зі списком валют. Для установки значення потрібно використовувати метод $modx->event->setOutput().

Параметри:

Ім'я параметра	Передається по посиланню	Опис
list	Ні	Масив зі списком валют

OnManagerCurrencyRender

Це стандартна подія Modx, розрахована на отримання рядка, яка буде виведена в кінці сторінки редагування валюти. Для установки значення потрібно використовувати метод $modx->event->setOutput().

Параметри:

Ім'я параметра	Передається по посиланню	Опис
status	Ні	Масив з даними валюти

OnManagerBeforeDefaultCurrencyChange

Викликається при збереженні валюти, в разі, якщо редагована валюта призначається валютою за умовчанням.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
old	Ні	Дані валюти, яка була встановлена за замовчуванням першою
new	Так	Дані валюти, що призначається за умовчанням

OnManagerRegisterCommerceController

Викликається перед обробкой шляху при роботі в модулі в панелі адміністрування. Дає можливість зареєструвати свій контролер.

Параметри:

Ім'я параметра	Передається по посиланню	Опис
module	Так	Посилання на класс-менеджер модуля \Commerce\Module\Manager

class MyController extends \Commerce\Module\Controllers\Controller implements \Commerce\Module\Interfaces\Controller
{
    ...
}

switch ($modx->Event->name) {
    case 'OnManagerRegisterCommerceController': {
        $module->registerController('customroute', new MyController($modx, $module));
    break;
    }
}