nopCommerce Dokumentace

Jak napsat plugin pro nopCommerce 3.90 (a předchozí verze)

V informatice je plug-in (neboli plugin) sada softwarových komponent, které přidávají specifické schopnosti větší softwarové aplikaci (Wikipedie).

Pluginy se používají k rozšíření funkčnosti nopCommerce. nopCommerce má několik typů pluginů. Například platební metody (jako PayPal), poskytovatele daní, metody výpočtu dopravy (jako UPS, USP, FedEx), widgety (jako blok „live chat“) a mnoho dalších. nopCommerce je již distribuován s mnoha různými pluginy. Můžete také vyhledávat různé pluginy na oficiálním webu nopCommerce a zjistit, zda už někdo nevytvořil plugin, který vyhovuje vašim potřebám. Pokud ne, tento článek vás provede procesem vytvoření vlastního pluginu.

Struktura pluginu, požadované soubory a umístění

  1. Nejprve musíte v řešení (solution) vytvořit nový projekt typu „Class Library“. Je dobrým zvykem umístit všechny pluginy do adresáře \Plugins v kořeni vašeho řešení (nezaměňujte s podadresářem \Plugins umístěným v adresáři \Nop.Web, který slouží pro již nasazené pluginy). Je dobrým zvykem umístit všechny pluginy do složky řešení „Plugins“ (více informací o složkách řešení).

    Doporučený název projektu pluginu je „Nop.Plugin..“. je skupina vašeho pluginu (například „Payment“ nebo „Shipping“). je název vašeho pluginu (například „PayPalStandard“). Například platební plugin PayPal Standard má následující název: Nop.Plugin.Payments.PayPalStandard. Upozorňujeme však, že to není povinné. Pro plugin můžete zvolit libovolný název. Například „MyGreatPlugin“.

    p1

  2. Jakmile je projekt pluginu vytvořen, aktualizujte výstupní cestu sestavení projektu. Nastavte ji na ..\..\Presentation\Nop.Web\Plugins\{Group}.{Name}. Například platební plugin Authorize.NET má následující výstupní cestu: ..\..\Presentation\Nop.Web\Plugins\Payments.AuthorizeNet. Poté budou příslušné knihovny DLL pluginu automaticky kopírovány do adresáře \Presentation\Nop.Web\Plugins, ve kterém jádro nopCommerce hledá platné pluginy. Upozorňujeme však, že ani to není povinné. Pro plugin můžete zvolit libovolný název výstupního adresáře.

    p1

    • V nabídce Project klikněte na Properties.
    • Klikněte na kartu Build.
    • Klikněte na tlačítko Browse vedle pole Output path a vyberte nový výstupní adresář sestavení.

    Výše popsané kroky byste měli provést pro všechny existující konfigurace („Debug“ a „Release“).

  3. Dalším krokem je vytvoření souboru Description.txt, který je vyžadován pro každý plugin. Tento soubor obsahuje metainformace popisující váš plugin. Stačí tento soubor zkopírovat z jakéhokoli jiného existujícího pluginu a upravit jej podle svých potřeb. Například platební plugin PayPal Standard má následující soubor Description.txt:

    Group: Payment methods
    FriendlyName: PayPal Standard
    SystemName: Payments.PayPalStandard
    Version: 1.28
    SupportedVersions: 3.90
    Author: nopCommerce team
    DisplayOrder: 1
    FileName: Nop.Plugin.Payments.PayPalStandard.dll
    Description: This plugin allows paying with PayPal Standard
    

    Všechna pole jsou samovysvětlující, ale zde je několik poznámek. Pole SystemName by mělo být jedinečné. Pole Version je číslo verze vašeho pluginu; můžete jej nastavit na libovolnou hodnotu. Pole SupportedVersions může obsahovat seznam podporovaných verzí nopCommerce oddělených čárkami (ujistěte se, že aktuální verze nopCommerce je v tomto seznamu zahrnuta, jinak se plugin nenačte). Pole FileName má formát Nop.Plugin...dll (jde o název souboru sestavení vašeho pluginu). Ujistěte se, že vlastnost „Copy to Output Directory“ tohoto souboru je nastavena na „Copy if newer“.

    p2

  4. Měli byste také vytvořit soubor web.config a zajistit, aby byl kopírován na výstup. Stačí jej zkopírovat z jakéhokoli existujícího pluginu.

    Důležité

    Do budoucna se ujistěte, že vlastnosti „Copy local“ všech referencí na sestavení třetích stran (včetně základních knihoven, jako jsou Nop.Services.dll nebo Nop.Web.Framework.dll) jsou nastaveny na „False“ (nekopírovat)

  5. Posledním povinným krokem je vytvoření třídy, která implementuje rozhraní IPlugin (jmenný prostor Nop.Core.Plugins). nopCommerce obsahuje třídu BasePlugin, která již implementuje některé metody IPlugin a umožňuje vyhnout se duplikaci zdrojového kódu. nopCommerce vám také poskytuje některá specifická rozhraní odvozená od IPlugin. Máme například rozhraní „IPaymentMethod“, které se používá k vytváření nových pluginů platebních metod. Obsahuje některé metody, které jsou specifické pouze pro platební metody, jako ProcessPayment() nebo GetAdditionalHandlingFee(). V současné době má nopCommerce následující specifická rozhraní pluginů:

    • IPaymentMethod. Tyto pluginy se používají ke zpracování plateb.
    • IShippingRateComputationMethod. Tyto pluginy se používají k získání přijatelných způsobů doručení a příslušných cen dopravy. Například UPS, UPS, FedEx atd.
    • IPickupPointProvider. Tyto pluginy se používají k poskytování výdejních míst.
    • ITaxProvider. Poskytovatelé daní se používají k získání daňových sazeb.
    • IExchangeRateProvider. Používá se k získání směnného kurzu měny.
    • IDiscountRequirementRule. Umožňuje vytvářet nová pravidla slev, například „Fakturační země zákazníka musí být…“
    • IExternalAuthenticationMethod. Používá se k vytváření metod externího ověřování, jako jsou Facebook, X (Twitter), OpenID atd.
    • IWidgetPlugin. Umožňuje vytvářet widgety. Widgety se vykreslují v některých částech vašeho webu. Může jít například o blok „Live chat“ v levém sloupci vašeho webu.
    • IMiscPlugin. Pokud váš plugin neodpovídá žádnému z výše uvedených rozhraní.

Důležité

Po každém sestavení projektu vyčistěte řešení, než provedete změny. Některé prostředky budou uloženy v cache a mohou vývojáře přivést k šílenství.

Zpracování požadavků. Controllery, modely a views

Nyní můžete plugin vidět v Administrace → Konfigurace → Pluginy (Admin area → Configuration → Plugins). Jak ale jistě tušíte, náš plugin nic nedělá. Nemá ani uživatelské rozhraní pro svou konfiguraci. Vytvořme stránku pro konfiguraci pluginu.

Nyní musíme vytvořit controller, model a view.

  • MVC controllery jsou zodpovědné za odpovídání na požadavky vůči webu ASP.NET MVC. Každý požadavek prohlížeče je namapován na konkrétní controller.
  • View obsahuje HTML značky a obsah, který se odesílá do prohlížeče. Při práci s aplikací ASP.NET MVC je view ekvivalentem stránky.
  • MVC model obsahuje veškerou logiku vaší aplikace, která není obsažena ve view ani v controlleru.

Více informací o vzoru MVC.

Pojďme tedy začít:

  • Vytvořte model. V novém pluginu přidejte složku Models a poté přidejte novou třídu modelu, která odpovídá vašim potřebám.

  • Vytvořte view. V novém pluginu přidejte složku Views, poté složku (kde je název vašeho pluginu) a nakonec přidejte soubor cshtml s názvem Configure.cshtml. Důležitá poznámka: pro verze 2.00–3.30 by mělo být view označeno jako vložený prostředek (embedded resource). A od verze 3.40 se u views ujistěte, že vlastnost „Build Action“ souboru view je nastavena na „Content“ a vlastnost „Copy to Output Directory“ je nastavena na „Copy if newer“.

  • Vytvořte controller. V novém pluginu přidejte složku Controllers a poté přidejte novou třídu controlleru. Je dobrým zvykem pojmenovávat controllery pluginů {Group}{Name}Controller.cs. Například PaymentAuthorizeNetController. Takové pojmenování controllerů samozřejmě není povinné (jde jen o doporučení). Poté vytvořte příslušnou metodu akce pro konfigurační stránku (v administraci). Pojmenujme ji „Configure“. Připravte třídu modelu a předejte ji následujícímu view. Pro verze nopCommerce 2.00–3.30 byste měli předat cestu k vloženému view – „Nop.Plugin...Views. .Configure“. A od verze nopCommerce 3.40 byste měli předat fyzickou cestu k view – ~/Plugins/{PluginOutputDirectory}/Views/{ControllerName}/Configure.cshtml. Otevřete například platební plugin Authorize.NET a podívejte se na jeho implementaci PaymentAuthorizeNetController.

    Tip

    • Nejjednodušší způsob, jak výše popsané kroky provést, je otevřít jakýkoli jiný plugin a zkopírovat tyto soubory do projektu vašeho pluginu. Poté stačí přejmenovat příslušné třídy a adresáře.

    • Pokud chcete omezit přístup k určité metodě akce controlleru pouze na administrátory (majitele obchodu), stačí ji označit atributem [AdminAuthorize].

    Například struktura projektu pluginu Authorize.NET vypadá jako na obrázku níže

    p3

Routy

Nyní musíme zaregistrovat příslušné routy pluginu. Směrování (routing) ASP.NET je zodpovědné za mapování příchozích požadavků prohlížeče na konkrétní akce MVC controllerů. Více informací o směrování. Postupujte tedy podle následujících kroků:

  • Některá specifická rozhraní pluginů (popsaná výše) a rozhraní „IMiscPlugin“ obsahují metodu „GetConfigurationRoute“. Ta by měla vracet routu k akci controlleru, která se používá pro konfiguraci pluginu. Implementujte metodu „GetConfigurationRoute“ rozhraní svého pluginu. Tato metoda informuje nopCommerce o tom, jaká routa se používá pro konfiguraci pluginu. Pokud váš plugin nemá konfigurační stránku, měla by metoda „GetConfigurationRoute“ vracet null. Viz například níže uvedený kód:

    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 }
        };
    }
    
  • (volitelné) Pokud potřebujete přidat nějakou vlastní routu, vytvořte soubor RouteProvider.cs. Ten informuje systém nopCommerce o routách pluginu. Například následující třída RouteProvider přidává novou routu, ke které lze přistoupit otevřením webového prohlížeče a přechodem na URL http://www.yourStore.com/Plugins/PaymentPayPalStandard/PDTHandler (používá ji plugin PayPal):

    public partial class RouteProvider : IRouteProvider
    {
        public void RegisterRoutes(RouteCollection routes)
        {
             routes.MapRoute("Plugin.Payments.PayPalStandard.PDTHandler",
                 "Plugins/PaymentPayPalStandard/PDTHandler",
                 new { controller = "PaymentPayPalStandard", action = "PDTHandler" },
                 new[] { "Nop.Plugin.Payments.PayPalStandard.Controllers"  }
            );
        }
    
        public int Priority
        {
            get
            {
                return 0;
            }
        }
    }
    

    Jakmile plugin nainstalujete a přidáte konfigurační metodu, najdete odkaz na konfiguraci pluginu v Administrace → Konfigurace → Pluginy (Admin → Configuration → Plugins).

Zpracování metod „Install“ a „Uninstall“

Tento krok je volitelný. Některé pluginy mohou během instalace vyžadovat dodatečnou logiku. Plugin může například vložit nové lokalizační prostředky. Otevřete tedy svou implementaci IPlugin (ve většině případů bude odvozena od třídy BasePlugin) a přepište následující metody:

  • Install. Tato metoda bude vyvolána během instalace pluginu. Zde můžete inicializovat libovolná nastavení, vložit nové lokalizační prostředky nebo vytvořit nové databázové tabulky (je-li to potřeba).
  • Uninstall. Tato metoda bude vyvolána během odinstalace pluginu.

Důležité

Pokud přepíšete jednu z těchto metod, neskrývejte její základní implementaci.

Například struktura projektu pluginu Authorize.NET vypadá jako na obrázku níže

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

Tip

Seznam nainstalovaných pluginů se nachází v \App_Data\InstalledPlugins.txt. Seznam se vytváří během instalace.

Aktualizace nopCommerce může pluginy rozbít

Některé pluginy mohou zastarat a s novější verzí nopCommerce přestat fungovat. Pokud máte po aktualizaci na novější verzi potíže, odstraňte plugin a navštivte oficiální web nopCommerce, abyste zjistili, zda je k dispozici novější verze. Mnoho autorů pluginů své pluginy aktualizuje, aby vyhovovaly novější verzi, někteří to však neudělají a jejich plugin se s vylepšeními nopCommerce stane zastaralým. Ve většině případů však stačí otevřít příslušný soubor plugin.json a aktualizovat pole SupportedVersions.

Závěr

Doufáme, že vám to pomůže začít s nopCommerce a připraví vás na vytváření propracovanějších pluginů.