msMultiCurrency

Компонент добавляет мультивалютность в miniShop2, а также позволяет привязывать цену отдельного товара к одной из
валют.

Из коробки доступны следующие поставщики котировок валют:

• Центральный банк Российской Федерации (по умолчанию );
• Центральный банк Украины;
• Национальный банк Республики Беларусь;
• Национальный банк Республики Казахстан.

Для каждой котировки можно указать свой коэффициент, на которую она будет умножаться. Есть возможность обновления
котировок через крон.

Видео-обзор

Использование

После установки компонента в меню miniShop2 появится подменю “Валюты”.



В данном разделе вы можете выбрать/добавить своего поставщика котировок валют, а также настроить или добавить свои валюты.

В списке валют нужно указать основную валюту (валюта в которой указаны цены товаров), по умолчанию это российский рубль.

Для того, чтобы привязать цену конкретного товара к другой валюте, необходимо в карточки товара выбрать ее из выпадающего списка “Валюта” и указать стоимость товара в выбранной валюте.



Если не включена опция "Цена в корзине в валюте пользователя" то цена в заказе всегда сохраняется в базовой валюте, иначе в валюте которая была выбрана пользователем. В чанке сниппета msGetOrder вся информация о выбранной валюте хранится в свойстве {$order.properties.msmc}. Например символ валюты можно получить так:
левый — {$order.properties.msmc.symbol_left}
правый — {$order.properties.msmc.symbol_right}

Информация, о выбранной валюте пользователем, хранится в следующих плейсхолдерах:

• [[!+msmc.name]] — название валюты
• [[!+msmc.code]] — код валюты
• [[!+msmc.symbol_left]] -символ слева
• [[!+msmc.symbol_right]] — символ справа
• [[!+msmc.val]] — конечное значение котировки валюты ( котировка умноженная на коэффициент).

Для корректного вывода информации о заказе в письмах, необходимо в системной настройке miniShop2 (ключ ms2_order_handler_class) установить msmcOrder

Сниппеты

msMultiCurrencyCart — сниппет для вывода корзины покупателя. Данный сниппет по параметрам полностью идентичен сниппету msCart и всего лишь обеспечивает корректный вывод цены товара. В чанках данного сниппета нет необходимость в использовании сниппета msMultiCurrencyPrice. Название валюты в чанке доступно через плейсхолдер [[+currency]]

msMultiCurrencyGetOrder — сниппет для вывода заказа. Данный сниппет по параметрам полностью идентичен сниппету msGetOrder и всего лишь обеспечивает корректный вывод цены товара. В чанках данного сниппета нет необходимость в использовании сниппета msMultiCurrencyPrice. Название валюты в чанке доступно через плейсхолдер [[+currency]]

msMultiCurrency — сниппет для вывода списка валют.
Параметры:

1. tpl — Чанк оформления для вывода результата работы сниппета.
2. frontendCss — Стиль фронтенда. По умолчанию [[+assetsUrl]]css/web/default.min.css
3. frontendJs — Скрипт фронтенда. По умолчанию [[+assetsUrl]]js/web/default.min.js

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

[[!msMultiCurrency?
    tpl=``
    ]]

msMultiCurrencyPrice — сниппет для вывода цены в определенной валюте.
Параметры:

1. price — цена
2. cid — ID валюты в которой нужно вернуть цену. По умолчанию используется валюта, выбранная пользователем.
   

Пример использования:

Классический вариант

[[!msMultiCurrencyPrice? &price=`Цена товара`]]  [[!+msmc.symbol_right]]

Для шаблонизатора Fenom

{'!msMultiCurrencyPrice' | snippet : [
    'price' => `Цена товара,
    ]}

    {$_modx->getPlaceholder('msmc.symbol_right')}

msMultiCurrencyPrices — сниппет для вывода цены товара во всех валютах.
Параметры:

1. price — цена товара в базовой валюте (не обязательный).
2. old_price — старая цена товара в базовой валюте (не обязательный).
3. pid — id товара цену которого необзодимо вывести. Параметр игнорируется если задан парамтер price. Если не задан pid и price то будет использован id страницы на которой вызван данный сниппет.
4. symbol — название колонки из которой следует взять символ валюты. Может принимать два значения right и left. По умолчанию right.
5. tpl — чанк оформления результата. По умолчанию msMultiCurrencyPrices.

Важно! Если вы используете дополнения, которые каким-то образом манипулируют ценой, то убедитесь, что они корректно работают с msMultiCurrency, особенно если у вас будет товар, привязанный к одной из валют.

Обновление котировок по крон

Для обновления котировок по крон необходимо в него добавить задание на выполнения скрипта core/components/msmulticurrency/cron/course.php
Очень часто в день дергать этот скрипт не стоит, т.к. некоторые поставщики котировок лимитируют количество обращений к API в сутки да и котировка, как правило, обновляется 1-2 раза в сутки.

Работа с контекстами

Для каждого контекста можно указать валюту которая будет выбрана по умолчанию. Для этого в системных настройках контекста нужно создать параметр с ключем «msmulticurrency.selected_currency_default» в котором указать в качестве значения ID валюты которая должна быть выбрана по умолчанию на сайте.

mFilter2

Для отображение в слайдере цены в выбранной валюте следует выполнить следующие действия:

1. скопировать файл в директорию /core/components/msearch2/custom/filters/ (данный шаг можно пропустить если mSearch2 был установлен до msMultiCurrency)


2. в системных настройках /manager/?a=system/settings для ключа mse2_filters_handler_class указать msmcFiltersHandler
3. заменить для слайдера цены фильтр number на price
4. очистить кэш modx.

Пример вызова сниппета mFilter2

[[!mFilter2?
    &class=`msProduct`
    &element=`msProducts`
    &parents=`0`
    &filters=`ms|price:price`
    &tplFilter.outer.ms|price=`tpl.mFilter2.filter.slider`
    &tplFilter.row.ms|price=`tpl.mFilter2.filter.number`
    ]]

Вывод цен и валюты в категории товаров

Для того что бы поля “Валюта”, “Цена в выбранной валюте” или “Старая цена в выбранной валюте” вывести в категории товара, необходимо в системных настройках minishop2 для опцию “Поля таблицы товаров” (ключ ms2_category_grid_fields) добавить название нужных полей.

• currency_id — название валюты
• msmc_price — цена в выбранной валюте
• msmc_old_price — старая цена в выбранной валюте

Пример

id,menuindex,pagetitle,article,price,msmc_price,currency_id,thumb,new,favorite,popular

Передача кода валюты в платежную систему

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

Ниже приведен код плагина для события msOnChangeOrderStatus который устанавливает для дополнения mspUP в его параметр ms2_payment_unitpay_currency код выбранной валюты.

<?php
/**
 * @var modX $modx
 * @var msOrder $order
 */
switch ($modx->event->name) {
    case 'msOnChangeOrderStatus':
    $properties = $order->get('properties');
    $msmcData = $modx->getOption('msmc', $properties);
    if ($msmcData) {
    $currencyCode = $modx->getOption('code', $msmcData);
    if ($currencyCode) {
    $modx->setOption('ms2_payment_unitpay_currency', $currencyCode);
    }
    }
    break;
    }

Разработка

Создание своего поставщика валют

Для создания своего поставщика валют необходимо поместить в директорию core/components/msmulticurrency/providers php файл с вашим классом, являющимся наследников базового класса поставщика MsMCProvider и определить его методы getCodes, getCourse и run по аналогии с уже имеющимися поставщиками. После всего этого добавьте информацию о вашем поставщике в разделе поставщиков

Системные события

msmcOnToggleCurrency — изменение пользователем валюты, содержит следующие переменные:

1. $currency — массив данных выбранной валюты

msmcOnGetPrice — конвертация цены, содержит следующие переменные:

1. $price — цена
2. $newPrice — цена после конвертации
3. $currencyId — ID валюты
4. $course — коэффициент, на который может делиться цена

msmcOnBeforeUpdateProductPrice — пересчет цены в базовой валюте на основании привязанной валюты:

1. $price — цена в базовой валюте
2. $oldPrice — старая цена в базовой валюте
3. $product — массив данных товара
4. $setId — ID набора валют
5. $currencyId — ID валюты

Полезные функции

getPrice — конвертация цены

/**
        * @param float $price  - Цена
        * @param int $productId   - ID товара (проверяется, привязан ли товар к одной из валют). По умолчанию  0
        * @param int $currencyId  -  ID Валюты, в которой нужно вернуть цену.  По умолчанию  0
        * @param float $course  - Коэффициент, на который  следует  поделить цену (если его указать, то функция сразу вернет результат деления).  По умолчанию  0
        * @param bool $isFormat - Выводить цену отформатированной согласно параметру miniShop2 ms2_price_format. По умолчанию true
        */
        public function getPrice($price = 0, $productId = 0, $currencyId = 0, $course = 0.0, $isFormat = true);

Пример использования функции getPrice в своем скрипте

/** @var MsMC $msmc */
        $msmc = $modx->getService('msmulticurrency', 'MsMC');
        $msmc->getPrice($price, $pid, $cid, $course, $isFormat);