msMultiCurrency

Мультивалютность для miniShop2
Автор дополнения
Prihod
Пакетов
35
Закачек
11 333
Обычно отвечает в течение суток
Автор дополнения
Пакетов
35
Закачек
11 333
Обычно отвечает в течение суток
Версия 1.2.8-pl
Дата выпуска 25.10.2023
Загрузки 555
Просмотры 9 687
Внимание, этот компонент требует версию PHP 7.3 или выше! Если ваш сайт использует PHP ниже требуемого, установка этого дополнения может его сломать.
Внимание, этот компонент требует версию MODX не ниже 2.3 !

Компонент добавляет мультивалютность в 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);

[1.2.8-pl] - 2023-10-25

Исправлено

  • Кэширование в Firefox при переключении валюты

[1.2.7-pl] - 2023-04-06

Исправлено

  • Ошибка 'Uncaught Error: Call to undefined method msmcOrder::invokeEvent()'

[1.2.6-pl] - 2023-01-16

Исправлено

  • Ошибка 'Fatal error: require_once(): Failed opening required /model/minishop2/msorderhandler.class.php' в miniShop2 >= 3.0.0-pl

Последние обсуждения в сообществе MODX.pro