nopCommerce Dokumentace

Jak napsat plugin pro nopCommerce 4.00

V informatice je plug-in (nebo plugin) sada softwarových komponent, které rozšiřují větší softwarovou aplikaci o konkrétní schopnosti (Wikipedie).

Pluginy slouží k rozšíření funkčnosti nopCommerce. nopCommerce má několik typů pluginů. Například platební metody (jako PayPal), poskytovatele daní, metody výpočtu ceny 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. Na oficiálním webu nopCommerce můžete také vyhledávat různé pluginy a zjistit, zda již 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 umisťovat všechny pluginy do adresáře \Plugins v kořeni řešení (nezaměňujte s podadresářem \Plugins v adresáři \Nop.Web, který slouží pro již nasazené pluginy). Je dobrým zvykem umisťovat 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 nejde o povinnost. Pro plugin si můžete zvolit libovolný název. Například „MyGreatPlugin“.

    p1

  2. Jakmile je projekt pluginu vytvořen, otevřete jeho soubor .csproj v libovolném textovém editoru a nahraďte jeho obsah následujícím:

    <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <TargetFramework>net461</TargetFramework>
     </PropertyGroup>
     <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
       <OutputPath>..\..\Presentation\Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY</OutputPath>
       <OutDir>$(OutputPath)</OutDir>
     </PropertyGroup>
     <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
       <OutputPath>..\..\Presentation\Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY</OutputPath>
       <OutDir>$(OutputPath)</OutDir>
     </PropertyGroup>
     <!-- This target execute after "Build" target -->
     <Target Name="NopTarget" AfterTargets="Build">
       <!-- Delete unnecessary libraries from plugins path -->
       <MSBuild Projects="$(MSBuildProjectDirectory)\..\..\Build\ClearPluginAssemblies.proj"    Properties="PluginPath=$(MSBuildProjectDirectory)\$(OutDir)" Targets="NopClear" />
     </Target>
    </Project>
    

    Kde PLUGIN_OUTPUT_DIRECTORY je třeba nahradit názvem pluginu, například Payments.PayPalStandard.

    Děláme to takto, abychom mohli využít nový způsob přidávání referencí třetích stran, který byl zaveden v .NET Core. Není to však povinné. Navíc reference z již referencovaných knihoven se načtou automaticky. Je to tedy velmi pohodlné.

  3. Dalším krokem je vytvoření souboru plugin.json, 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. Informace o souboru plugin.json najdete v části soubor plugin.json.

  4. 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 vám 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 specifické pouze pro platební metody, například ProcessPayment() nebo GetAdditionalHandlingFee(). V současnosti má nopCommerce následující specifická rozhraní pluginů:

    • IPaymentMethod. Tyto pluginy slouží ke zpracování plateb.
    • IShippingRateComputationMethod. Tyto pluginy slouží k získání přípustných způsobů doručení a odpovídajících cen dopravy. Například UPS, UPS, FedEx atd.
    • IPickupPointProvider. Tyto pluginy slouží k poskytování výdejních míst.
    • ITaxProvider. Poskytovatelé daní slouží k získávání daňových sazeb.
    • IExchangeRateProvider. Slouží k získávání směnného kurzu měn.
    • IDiscountRequirementRule. Umožňuje vytvářet nová pravidla slev, například „Fakturační země zákazníka musí být…“
    • IExternalAuthenticationMethod. Slouží k vytváření metod externího ověřování, jako je Facebook, X (Twitter), OpenID atd.
    • IWidgetPlugin. Umožňuje vytvářet widgety. Widgety se vykreslují v určitých částech vašeho webu. Může to být například blok „Live chat“ v levém sloupci 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 se ukládají do cache a mohou vývojáře přivést k šílenství.

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

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

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

  • MVC controllery odpovídají na požadavky odeslané na web 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. View je při práci s aplikací ASP.NET MVC ekvivalentem stránky.
  • MVC model obsahuje veškerou logiku aplikace, která není obsažena ve view ani v controlleru.

Více informací najdete o návrhovém vzoru MVC.

Začněme tedy:

  • Vytvořte model. Do nového 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. Do nového pluginu přidejte složku Views a poté přidejte soubor cshtml s názvem Configure.cshtml. U souboru view nastavte vlastnost „Build Action“ na „Content“ a vlastnost „Copy to Output Directory“ na „Copy if newer“. Upozorňujeme, že konfigurační stránka by měla používat layout _ConfigurePlugin. Ujistěte se také, že máte v adresáři \Views soubor _ViewImports. Můžete jej jednoduše zkopírovat z jakéhokoli jiného existujícího pluginu.

  • Vytvořte controller. Do nového 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 PaymentPayPalStandardController. Pojmenovávat controllery tímto způsobem samozřejmě není povinné (jde jen o doporučení). Poté vytvořte odpovídající akční metodu pro konfigurační stránku (v administraci). Pojmenujme ji „Configure“. Připravte třídu modelu a předejte ji následujícímu view pomocí fyzické cesty k view: - ~/Plugins/{PluginOutputDirectory}/Views/Configure.cshtml.

  • U své akční metody použijte následující atributy:

    [AuthorizeAdmin] //confirms access to the admin panel
    [Area(AreaNames.Admin)] //specifies the area containing a controller or action
    

    Otevřete například platební plugin PayPalStandard a podívejte se na jeho implementaci PaymentPayPalStandardController.

Poté byste pro každý plugin, který má konfigurační stránku, měli zadat konfigurační URL. Základní třída s názvem BasePlugin obsahuje metodu GetConfigurationPageUrl, která vrací konfigurační URL:

return $"{_webHelper.GetStoreLocation()}Admin/ControllerName/ActionName";

Kde ControllerName je název vašeho controlleru a ActionName je název akce (obvykle „Configure“).

Jakmile plugin nainstalujete a přidáte konfigurační metodu, najdete odkaz pro konfiguraci pluginu v Administrace → Konfigurace → Pluginy.

Tip

Nejsnazší způsob, jak dokončit výše popsané kroky, je otevřít jakýkoli jiný plugin a zkopírovat tyto soubory do projektu svého pluginu. Poté stačí přejmenovat příslušné třídy a adresáře.

Struktura projektu pluginu PayPalStandard vypadá například jako na obrázku níže:

p3

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

Tento krok je volitelný. Některé pluginy mohou během instalace vyžadovat další logiku. Plugin může například vkládat nové lokalizační řetězce. 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 se zavolá během instalace pluginu. Zde můžete inicializovat libovolná nastavení, vložit nové lokalizační řetězce nebo vytvořit nové databázové tabulky (je-li to potřeba).
  • Uninstall. Tato metoda se zavolá během odinstalace pluginu.

Důležité

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

Například přepsaná metoda „Install“ by měla obsahovat následující volání metody: base.Install(). Metoda „Install“ pluginu PayPalStandard vypadá jako kód níže

public override void Install()
{
    var settings = new PayPalStandardPaymentSettings()
    {
        UseSandbox = true
    };
    _settingService.SaveSetting(settings);
    base.Install();
}

Tip

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

Routy

Zde se podíváme, jak registrovat routy pluginu. Routování v ASP.NET Core zajišťuje mapování příchozích požadavků prohlížeče na konkrétní akce MVC controllerů. Více informací najdete o routování. Postupujte tedy podle následujících kroků:

  • Pokud potřebujete přidat 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(IRouteBuilder routeBuilder)
        {
             routeBuilder.MapRoute("Plugin.Payments.PayPalStandard.PDTHandler", "Plugins/   PaymentPayPalStandard/PDTHandler",
             new { controller = "PaymentPayPalStandard", action = "PDTHandler" });
        }
        public int Priority
        {
            get
            {
                return -1;
            }
        }
    }
    

Aktualizace nopCommerce může pluginy rozbít

Některé pluginy mohou zastarat a přestat fungovat s novější verzí nopCommerce. Pokud máte po aktualizaci na novější verzi problémy, plugin odstraňte 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 můžete jednoduše 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ů.