Создание плагинов для nopCommerce

Автор - Андрей Мазульницын

Введение

nopCommerce – это open source движок, написанный на ASP.NET MVC 3, для электронной коммерции. Плагины используются для расширения функционала nopCommerce. В nopCommerce существуются несколько типов плагинов. Например, платежный модуль, провайдер расчета налогов, провайдер рассчета стоимости доставки товаров и многие другие. nopCommerce распространяется с несколькими уже существующими плагинами, которые вы можете как рабочие примеры при разработке сових плагинов. Кстати, вы можете найти множество различных плагинов на официальном сайтеnopCommerce. Если же требуемого плагина вы найти не можете, то в этой статье вы узнаете о том, как написать свой плагин.

Структура плагинов, обязательные файлы и их расположение.

Первая вещь, которую вам необходимо сделать это добавить новый проект Class Library к основному солюшену. Правилом хорошего тона является сохранение всех плагинов в папке \Plugins в корне солюшена (не путать с подпапкой \Plugins, размещенной в внутри папки самого сайт \Nop.Web и которая используется для уже разработанных и скомпилированных плагинов).

JJ573022.86125BC5A45ADE530DBB0697004B6D74(ru-ru,MSDN.10).png

Хорошим именем для плагина будет “Nop.Plugin.{Group}.{Name}”, где {Group} - это тип вашего плагина (например, “Payment”), а {Name} – это название плагина (например, “Authorize.NET”). К примеру, платежный модуль для системы Authorize.NET будет иметь следующее имя “Nop.Plugin.Payment.AuthorizeNet”

Как только проект плагина (Class Library) добавлен надо установить правильный output path. Установите его в "..\..\Presentation\Nop.Web\Plugins\{Group}.{Name}\". Например, у вышеупомянутого платежного модуля Authorize.NET путь этот установлен в "..\..\Presentation\Nop.Web\Plugins\Payments.AuthorizeNet\". Как только это будет сделано, то соответветствующие сборки (DLL) плагина будут при компиляции автоматически копироваться в папку \Presentation\Nop.Web\Plugins\, которая используется для уже развернутых плагинов.

JJ573022.06397F1691D1B2B6FA24C936CAEA4530(ru-ru,MSDN.10).png

  1. В Visual Studio в контекстном меню проекта плагина выберите Properties.
  2. Выберите вкладку Build.
  3. Нажмите кнопку Browse напротив Output path и выберите необходимую папку.

Данные действия необходимо выполнить для всех сущетсвующих конфигураций вашей IDE ("Debug" и "Release").

Следующим шагом будет создание файла Description.txt, необходимого для работы любого плагина. Данный файл содержит мета-информацию, описывающую ваш плагин. Вы можете просто скопировать данный файл из любого уже существующего плагина и изменить его под свои требования. Например, вот как выглядит данный файл у плагина для платежной системы Authorize.NET:

Group: Payment methods
FriendlyName: Credit Card
SystemName: Payments.AuthorizeNet
Version: 1.00
SupportedVersions: 2.30
Author: nopCommerce team
DisplayOrder: 1
FileName: Nop.Plugin.Payments.AuthorizeNet.dll
  1. Предназначение данных полей интуитивно понятно из их названий. SystemName должен быть уникальным среди всех плагинов. Version – это версия вашего плагина (в принципе, любое значение, которое вы захотите установить). SupportedVersions должен содержать список версий nopCommerce, разделенный запятой, в которых данный плагин работает (не забудьте убедиться, что текущая версия nopCommerce включена в этот список, иначе плагин даже не будет загружен). FileName имеет следующий формат Nop.Plugin.{Group}.{Name}.dll (это имя файла вашего плагина). Также не забудьте убедиться, что значение свойства "Copy to Output Directory" у файла Description.txt установлено в "Copy if newer", как показано ниже.

    JJ573022.00EF53870E1DD4D7AD5E030A8C9CC932(ru-ru,MSDN.10).png

  2. И последним шагом, необходимым для создания плагина, будет добавление класса, который реализует интерфейс IPlugin (простанство имён Nop.Core.Plugins). Кстати, в nopCommerce уже есть класс BasePlugin, который реализует данный интерфейс и позволяет вам избежать ненужный повторений кода, так можете смело наследоваться от него. В nopCommerce также есть несколько специфичных интерфейсов, унаследованных от IPlugin. Например, интерфейс IPaymentMethod используется для создания платежных модулей. Он содержит несколько методов, которые используются только в платежных методах, например ProcessPayment(). Мы можете найти описание этих интерфейсов ниже:

    • IExternalAuthenticationMethod. Используется для создания внешних методов аутентификации, таких как Facebook, Twitter, OpenID и тому подобные.
    • IWidgetPlugin. Позволяет создавать виджеты. Виджеты отображаются в разлиных частях вашего сайта. Например, можно создать виджет "Live chat", который будет показан в левой колонке вашего сайта.
    • IExchangeRateProvider. Используется для получения курсов валют.
    • IDiscountRequirementRule. Используется для создания различных требований для скидок. Например, покупатель должен предварительно купить определнный товар, чтобы скидка стала активной.
    • ISMSProvider. СМС плагины позволяют отсылать СМС сообщения для таких событий как размещение заказа.
    • IPaymentMethod. Используются для создания платежных плагинов и приема платежей.
    • IPromotionFeed. Данный тип плагинов используется для генерации прайсов и прочих списков продуктов для различных сервисов сравнения цен и каталогов продуктов. Например, для Froogle (Google Product Search) или PriceGrabber
    • IShippingRateComputationMethod. Провайдеры рассчета стоимости и способов доставки товара (например, UPS, UPS, FedEx).
    • ITaxProvider. Используются для рассчета налоговых ставок.
  1. Если ваш плагин не относится не к одному и вышеописанных типов, то используйте интерфейс IMiscPlugin.
  2. Важно: После каждого изменения исходного кода плагина и перед его компиляцией, делайте у основного солюшена clean, потому что некоторые файлы могут остаться закешированы средой разработки.

Обработка запросов. Контроллеры, модели и представления.

Теперь вы можете увидеть созданный плагин в панели администрирования (меню Configuration > Plugins). Но как вы уже поняли, наш плагин еще пока ничего делать не умеет. У него даже нет пользователького интерфейса (страницы) для его настройки. Давайте создадим такую страницу. Для этого нам потребуется создать контроллер, модель и представление.

  1. Контроллеры отвечают за обработку запросов. Каждое открытие страницы на сайте соответствует контретному контроллеры и методу. Он контролирует ввод данных пользователем и использует модель и представление для реализации необходимой реакции.
  2. Представление содержит HTML код, то есть отвечает за отображение информации (визуализацию).
  3. Модель – это данные.

Больше о MVC вы можете узнать здесь.

Итак начнем.

  1. Создание модели. Добавьте папку Models к проекту плагина и затем добавьте класс модели, которая удовлетворяет вашим требониям.
  2. Создание представления. Добавьте папку View к проекту плагина. Затем подпапку {Name}, где {Name} – это название вашего плагина. Ну и наконец cshtml файл с представлением. Важным моментом является то, что этот файл должен быть помечен как Embedded resource.
  3. Создание контроллера. Добавьте папку Controllers к проекту плагина и сам класс контроллера. Правилом хорошего тона будет назвать этот файл {Group}{Name}Controller.cs (например, PaymentAuthorizeNetController.cs). Теперь добавьте в него метод Configure(), подготовьте в нем модель и передайте ее в представление с именем "Nop.Plugin.{Group}.{Name}.Views.{Group}{Name}.Configure" (это путь embedded ресурса, который мы создали на предыдущем шаге). Для того чтобы лучше понять, как правильно реализовать контроллер, вы можете взглянуть на реализацию PaymentAuthorizeNetController у платежного модуля для Authorize.NET.

Подсказка 1: Скопируйте файл web.config из любого уже существующего плагина, чтобы добавить поддержку IntelliSense при работе с представлениями.

Подсказка 2: Наиболее простым способом реализации описанных выше шагов будет копирование всех файлов из любого существующего плагина и затем простое переименование файлов и классов.

Подсказка 3: Если вы хотите ограничить доступ к определенным методам вашего плагина только для администраторов, то добавьте к соответствующему методу атрибут [AdminAuthorize]

Подсказка 4: С целью уменьшения размера плагина рекомендуется установить свойство "Copy local" у файлов сторонних сборок (DLL) в “False”.

Вот, например, как выглядит проект плагина Authorize.NET, на который мы часто ссылались ранее.

JJ573022.2840F3A308D738E73BA888567857DBAE(ru-ru,MSDN.10).png

Марштуры (Routes)

Теперь нам необходимо зарегистрировать маршруты (Routes) нашего плагина. Они отвечают за соответствие запрошенных пользователем страниц (URL) и методов существующих контроллеров. Более подробную информацию о маршрутах вы можете найти здесь.

  1. Создайте файл RouteProvider.cs, описывающий ваши маршруты (routes). Например, нижеописанный класс RouteProvider добавляет новый маршрут, который соответсвует адресу http://www.yourStore.com/Plugins/PaymentAuthorizeNet/Configure/

    public partial class RouteProvider : IRouteProvider
        {
            public void RegisterRoutes(RouteCollection routes)
            {
                routes.MapRoute("Plugin.Payments.AuthorizeNet.Configure",
                     "Plugins/PaymentAuthorizeNet/Configure",
                     new { controller = "PaymentAuthorizeNet", action = "Configure" },
                     new[] { "Nop.Plugin.Payments.AuthorizeNet.Controllers" }
                );
            }
            public int Priority
            {
                get
                {
                    return 0;
                }
            }
        }
    
  2. У некоторых из описанных выше интерфейсов (например, IPaymentMethod или IMiscPlugin) есть метод GetConfigurationRoute, который должен возвращать маршрут (route) к странице, где плагин настраивается. Так nopCommerce узнает, какой метод контроллера отвечает за настройку плагина. Если же настройка не требуется, то просто верните в этом методе null. Например,

    public void GetConfigurationRoute(out string actionName, 
                out string controllerName, 
                out RouteValueDictionary routeValues)
            {
                actionName = "Configure";
                controllerName = "PaymentAuthorizeNet";
                routeValues = new RouteValueDictionary()
                {
                    { "Namespaces", "Nop.Plugin.Payments.AuthorizeNet.Controllers" }, 
                    { "area", null }
                };
            }
    

Как только вышеописанные действия будет реализованы и плагин будет установлен, то в панели администрирования (Configuration > Plugin) вы увидете ссылку на страницу с настройкой плагина.

Реализация методов Install и Uninstall

Этот шаг не является обязательным и может быть пропущен. Некоторые плагины требует дополнительных действий во время установки, например добавление новых локальных ресурсов. Если вы тоже хотите добавить какие-то данные при установке, то откройте ваш класс, реализующий IPlugin (и возможно BasePlugin), и переопределите (override) следующие методы

  1. Install. Это метод будет вызван во время установки. Здесь вы можете добавить новые локальные ресурсы, сохранить какие-либо настройки или добавить новые таблицы в БД (если это необходимо).
  2. Uninstall. Это метод будет вызван во время удаления плагина.

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

Вот например как выглядит метод Install у платежного модуля AuthorizeNet:

public override void Install()
        {
            var settings = new AuthorizeNetPaymentSettings()
            {
                UseSandbox = true,
                TransactMode = TransactMode.Authorize,
                TransactionKey = "123",
                LoginId = "456"
            };
            _settingService.SaveSetting(settings);

            base.Install();
        }

Подсказка: Список всех установленных плагинов можно найти в файле \App_Data\InstalledPlugins.txt, который создается в процессе установки nopCommerce.

Обновление nopCommerce до последней версии может нарушить работу плагинов

Некоторые из плагинов могут устареть и не работать с последними версиями nopCommerce. Если у вас возникли проблемы с каким-либо плагином после обновления nopCommerce до более новой версии, то посетите официальный сайт, чтобы узнать не вышла ли обновленная версия этого плагина. Если же вы не можете найти плагин для новой версии, то в большинстве случае (если API не было изменено) пролема решается простым открытием файла Description.txt и обновление поля SupportedVersions.

Заключение

Надеемся, что данная статья поможет вам начать разрабатывать плагины для nopCommerce. В случае возникновения вопросов вы всегда можете обратиться за помощью на официальных форумах nopCommerce.

Предыдущая тема

| Главная | Технические статьи | Сообщество