Плагин Market Currency Switcher для Cotonti

Плагин Market Currency Switcher для Cotonti

Руководство пользователя и разработчика

Назначение плагина

Market Currency Switcher — это клиентский плагин для Cotonti Siena, предназначенный для отображения стоимости товаров модуля Market PRO в нескольких валютах по заранее заданным курсам.

Плагин не влияет на реальные расчёты, платежи или сохранение цен. Его задача — дать пользователю ориентировочное представление о цене товара в удобной для него валюте.

Основные возможности

• Отображение цены товара в нескольких валютах
• Переключение валюты без перезагрузки страницы
• Сохранение выбранной валюты в cookie
• Единая логика работы:
  • в карточке товара
  • в списках
  • на главной странице market
• Работа через стандартную систему тегов Cotonti
• Совместимость с Bootstrap 5
• Поддержка PHP 8.4+

Архитектура плагина

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

1. Серверная часть (PHP, Market hooks)

Плагин подключается к хуку markettags.main и аккуратно расширяет стандартный набор тегов Market PRO.

Он:

• получает базовую цену товара;
• формирует «сырое» числовое значение цены (без форматирования);
• рассчитывает альтернативные значения стоимости по заданным курсам;
• добавляет только собственные теги, не вмешиваясь в существующие.

Важный момент: переменные передаются в scope функции Cotonti, а не объявляются глобально. Это сделано осознанно, чтобы избежать конфликтов и ошибок обнуления.

Подробности — смотрите инструкцию по серверной логике плагина.

2. Клиентская часть (JavaScript)

Клиентская логика подключается через хук footer.tags и работает полностью на стороне браузера.

Функции скрипта:

• чтение текущей валюты из cookie;
• динамическое обновление всех цен на странице;
• обновление текстовых подписей («Цена в основной валюте» / «Цена в выбранной валюте»);
• форматирование чисел в локали ru-RU;
• установка cookie при смене валюты.

Все курсы и обозначения валют передаются из PHP в JS, что исключает дублирование конфигурации.

Подробности — смотрите инструкцию по клиентскому скрипту.

3. Интеграция в шаблоны

Плагин не навязывает собственную разметку, а встраивается в существующие шаблоны Market:

• market.tpl
• market.list.tpl
• market.index.tpl
• header.tpl

Используется единый подход:

• базовая цена хранится в data-атрибуте;
• отображаемое значение обновляется JavaScript-ом;
• при отключённом плагине шаблоны продолжают работать штатно.

Таким образом:

• плагин можно включать и отключать без правки логики сайта;
• fallback-поведение полностью сохранено.

Примеры разметки — смотрите инструкцию по шаблонам.

Настройки плагина

Все параметры задаются через админ-панель Cotonti.

Доступные настройки:

• базовая валюта товара;
• до трёх дополнительных валют;
• курс для каждой валюты.

Курсы задаются относительно базовой валюты, например:

• USD → EUR
• USD → RUB
• USD → UAH

Плагин не загружает курсы автоматически — это сделано намеренно:

• нет внешних API;
• нет зависимостей;
• предсказуемая и стабильная работа.

 Описание каждого поля — смотрите инструкцию по настройкам.

Локализация

Плагин полностью поддерживает систему языков Cotonti:

• все подписи вынесены в языковые файлы;
• тексты для JS передаются из PHP;
• поддержка мультиязычных сайтов.

В комплекте присутствует русская локализация, которую легко расширить или заменить.

Поведение для пользователя

1. Пользователь выбирает валюту в селекте в шапке сайта.
2. Цена товара мгновенно пересчитывается.
3. Выбранная валюта сохраняется в cookie.
4. При следующем визите сайт открывается уже в выбранной валюте.

При этом:

• исходная цена всегда остаётся базовой;
• расчёт прозрачен и обратим;
• никаких серверных запросов не выполняется.

Ограничения и философия плагина

Важно понимать, что Market Currency Switcher:

• не заменяет платёжную систему;
• не участвует в заказах;
• не влияет на реальные транзакции;
• не хранит альтернативные цены в БД.

Это визуальный, информационный инструмент, предназначенный для улучшения UX и повышения конверсии.

Требования

• Cotonti Siena 0.9.26
• Market PRO v.5+
• PHP 8.4+
• MySQL 8.0+

Итог

Market Currency Switcher — это:

• минималистичный;
• безопасный;
• предсказуемый;
• легко расширяемый плагин,

который аккуратно дополняет Market PRO, не нарушая его архитектуру и не создавая технического долга.

Если потребуется, плагин легко:

• расширяется до большего числа валют;
• адаптируется под другую локаль;
• интегрируется с реальными API курсов.

Для установки, примеров и деталей — смотрите инструкцию.

Скачать исходный код плагина бесплатно с github