nopCommerce Dokumentace

Jak napsat plugin pro nopCommerce

Pluginy slouží k rozšíření funkcí 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. Na oficiálním webu nopCommerce můžete také vyhledat různé pluginy 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, povinné soubory a umístění

  1. Nejprve je potřeba vytvořit v řešení nový projekt typu Class Library. Je dobrou praxí umístit všechny pluginy do adresáře \Plugins v kořeni řešení (nezaměňujte s podadresářem \Plugins v adresáři \Nop.Web, který se používá pro již nasazené pluginy). Je dobrou praxí umístit všechny pluginy do složky řešení Plugins.

    Doporučený název projektu pluginu je Nop.Plugin.{Group}.{Name}. {Group} je skupina vašeho pluginu (například Payment nebo Shipping). {Name} je název vašeho pluginu (například PayPalCommerce). Například platební plugin PayPal Commerce má název Nop.Plugin.Payments.PayPalCommerce. Upozorňujeme však, že to není povinné. Pro plugin můžete zvolit libovolný název. Například MyGreatPlugin.

    p1

  2. Po vytvoření projektu pluginu 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>net9.0</TargetFramework>
            <Copyright>SOME_COPYRIGHT</Copyright>
            <Company>YOUR_COMPANY</Company>
            <Authors>SOME_AUTHORS</Authors>
            <PackageLicenseUrl>PACKAGE_LICENSE_URL</PackageLicenseUrl>
            <PackageProjectUrl>PACKAGE_PROJECT_URL</PackageProjectUrl>
            <RepositoryUrl>REPOSITORY_URL</RepositoryUrl>
            <RepositoryType>Git</RepositoryType>
            <OutputPath>$(SolutionDir)\Presentation\Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY</OutputPath>
            <OutDir>$(OutputPath)</OutDir>
            <!--Set this parameter to true to get the dlls copied from the NuGet cache to the output of your    project. You need to set this parameter to true if your plugin has a nuget package to ensure that   the dlls copied from the NuGet cache to the output of your project-->
            <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
            <ImplicitUsings>enable</ImplicitUsings>
        </PropertyGroup>
        <ItemGroup>
            <ProjectReference Include="$(SolutionDir)\Presentation\Nop.Web.Framework\Nop.Web.Framework.csproj" />
            <ClearPluginAssemblies Include="$(SolutionDir)\Build\ClearPluginAssemblies.proj" />
        </ItemGroup>
        <!-- This target executes after "Build" target -->
        <Target Name="NopTarget" AfterTargets="Build">
            <!-- Delete unnecessary libraries from plugins path -->
            <MSBuild Projects="@(ClearPluginAssemblies)" Properties="PluginPath=$(OutDir)" Targets="NopClear" />
        </Target>
    </Project>
    

    Tip

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

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

  3. Dalším krokem je vytvoření souboru plugin.json, který je povinný pro každý plugin. Tento soubor obsahuje metainformace popisující váš plugin. Stačí jej zkopírovat z jakéhokoli jiného existujícího pluginu a upravit podle svých potřeb. Informace o souboru plugin.json najdete v článku Soubor plugin.json

  4. Posledním povinným krokem je vytvoření třídy, která implementuje rozhraní IPlugin (jmenný prostor Nop.Services.Plugins). nopCommerce obsahuje třídu BasePlugin, která již implementuje některé metody IPlugin a umožňuje vyhnout se duplicitě zdrojového kódu. nopCommerce poskytuje také některá specifická rozhraní odvozená od IPlugin. Například rozhraní IPaymentMethod se používá k vytváření nových pluginů platebních metod. Obsahuje některé metody specifické pouze pro platební metody, jako je ProcessPaymentAsync() nebo GetAdditionalHandlingFeeAsync(). 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í podporovaných způsobů doručení a odpovídajících sazeb za dopravu. 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í externích metod ověřování, jako je Facebook, X (Twitter), OpenID atd.

    • IMultiFactorAuthenticationMethod. Používá se k vytváření metod vícefaktorového ověřování, jako je GoogleAuthenticator atd.

      Poznámka

      Jde o nové rozhraní; od verze 4.40 poskytujeme odpovídající infrastrukturu pro integrace MFA přímo v základu.

    • 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, což může vývojáře přivést k šílenství.

Po přidání pluginu může být nutné řešení znovu sestavit. Pokud nevidíte DLL svého pluginu v Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY, musíte řešení znovu sestavit. nopCommerce nezobrazí váš plugin na stránce Lokální pluginy (Local Plugins), pokud vaše DLL neexistují ve správné složce v Nop.Web.

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

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

Nyní je potřeba vytvořit controller, model a view.

  1. Controllery MVC odpovídají na požadavky odeslané na web ASP.NET Core MVC. Každý požadavek prohlížeče je namapován na konkrétní controller.
  2. 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 Core MVC ekvivalentem stránky.
  3. Model MVC obsahuje veškerou logiku aplikace, která není obsažena ve view nebo controlleru.

Více informací najdete v popisu vzoru MVC.

Pojďme tedy na to:

  • Vytvořte model. Přidejte do nového pluginu složku Models a poté do ní přidejte novou třídu modelu podle svých potřeb.

  • Vytvořte view. Přidejte do nového pluginu složku Views a poté do ní přidejte soubor *.cshtml s názvem Configure.cshtml. Nastavte vlastnost „Build Action“ souboru view na „Content“ a vlastnost „Copy to Output Directory“ na „Copy always“. Upozorňujeme, že konfigurační stránka by měla používat rozvržení _ConfigurePlugin.

  • Ujistěte se také, že máte v adresáři \Views soubor _ViewImports.cshtml. Stačí jej zkopírovat z jakéhokoli jiného existujícího pluginu.

  • Vytvořte controller. Přidejte do nového pluginu složku Controllers a poté do ní přidejte novou třídu controlleru. Je dobrou praxí pojmenovávat controllery pluginů {Group}{Name}Controller.cs. Například PaymentPayPalStandardController. Takové pojmenování samozřejmě není povinné (jde pouze 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.

  • Pro svou akční metodu použijte následující atributy:

    [AutoValidateAntiforgeryToken]
    [AuthorizeAdmin] //confirms access to the admin panel
    [Area(AreaNames.ADMIN)] //specifies the area containing a controller or action
    public class PayPalCommerceController : BasePluginController
    {
        public async Task<IActionResult> Configure(bool showtour = false)
        {
            return View("~/Plugins/Payments.PayPalCommerce/Views/Configure.cshtml");
        }
    }
    

    Tip

    Tyto atributy můžete přidat také přímo na controller. V takovém případě není nutné jimi označovat každou metodu.

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

Poté pro každý plugin, který má konfigurační stránku, musíte zadat konfigurační URL. Základní třída BasePlugin má metodu GetConfigurationPageUrl, která vrací konfigurační URL:

protected readonly IWebHelper _webHelper;

public PaymentPayPalStandardProvider(IWebHelper webHelper)
{
    _webHelper = webHelper;
}

public override string GetConfigurationPageUrl()
{
    return $"{_webHelper.GetStoreLocation()}Admin/{CONTROLLER_NAME}/{ACTION_NAME}";
}

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

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

Tip

Nejjednodušší způsob, jak provést 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.

Například struktura projektu pluginu PayPalCommerce vypadá jako na obrázku níže:

p3

Zpracování metod „InstallAsync“, „UninstallAsync“ a „UpdateAsync“

Tento krok je volitelný. Některé pluginy mohou během instalace vyžadovat dodatečnou logiku. Plugin může například vkládat 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:

  1. InstallAsync. Tato metoda se volá 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).
  2. UninstallAsync. Tato metoda se volá během odinstalace pluginu.
  3. UpdateAsync. Tato metoda se volá během aktualizace pluginu (když se změní jeho verze v souboru plugin.json).

Důležité

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

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

public override async Task InstallAsync()
{
    await _settingService.SaveSettingAsync(new PayPalStandardPaymentSettings
    {
        UseSandbox = true
    });
    
    await _localizationService.AddOrUpdateLocaleResourceAsync(new Dictionary<string, string>
    {
        ...
    });
    await base.InstallAsync();
}

Tip

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

Routy

Zde se podíváme, jak registrovat routy pluginu. Routing v ASP.NET Core odpovídá za mapování příchozích požadavků prohlížeče na konkrétní akce controllerů MVC. Více informací o routingu najdete v dokumentaci. Postupujte 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é se dostanete otevřením webového prohlížeče a přechodem na URL http://www.yourStore.com/Plugins/PayPalCommerceWebhook/WebhookHandler :

public class RouteProvider : IRouteProvider
    {
        /// <summary>
        /// Register routes
        /// </summary>
        /// <param name="endpointRouteBuilder">Route builder</param>
        public void RegisterRoutes(IEndpointRouteBuilder endpointRouteBuilder)
        {
            endpointRouteBuilder.MapControllerRoute(PayPalCommerceDefaults.ConfigurationRouteName,
                "Admin/PayPalCommerce/Configure",
                new { controller = "PayPalCommerce", action = "Configure" });

            endpointRouteBuilder.MapControllerRoute(PayPalCommerceDefaults.WebhookRouteName,
                "Plugins/PayPalCommerce/Webhook",
                new { controller = "PayPalCommerceWebhook", action = "WebhookHandler" });
        }

        /// <summary>
        /// Gets a priority of route provider
        /// </summary>
        public int Priority => 0;
    }

Aktualizace nopCommerce může pluginy rozbít

Některé pluginy mohou zastarat a s novější verzí nopCommerce přestat fungovat. Pokud po aktualizaci na novější verzi narazíte na problémy, plugin smažte a na oficiálním webu nopCommerce zjistěte, zda je k dispozici jeho novější verze. Mnoho autorů pluginů své pluginy pro novější verzi aktualizuje, někteří to však neudělají a jejich pluginy se s vylepšeními nopCommerce stanou zastaralými. 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 tvorbu propracovanějších pluginů.

Šablona pluginu

Pro nové pluginy nopCommerce můžete použít naši šablonu pro Visual Studio. Vývojářům může ušetřit spoustu času, protože již nemusí ručně provádět všechny počáteční kroky, jako je vytváření složek (Controllers, Views, Models atd.), dalších povinných souborů (PluginNopStartup.cs, _ViewImports.cshtml, ObjectContex, plugin.json atd.), konfigurace, referencí projektu atd.

Přispěvatelé: DmitriyKulagin
Upravit na GitHubu