Jak napsat plugin pro nopCommerce
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 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 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í
Nejprve je potřeba v solution vytvořit nový projekt typu „Class Library“. Je dobrým zvykem umístit všechny pluginy do adresáře
\Pluginsv kořeni solution (nezaměňujte s podadresářem \Plugins umístěným v adresáři\Nop.Web, který se používá pro již nasazené pluginy). Je dobrým zvykem umístit všechny pluginy do složky solution „Plugins“.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í podmínkou. Pro plugin můžete zvolit libovolný název. Například „MyGreatPlugin“.

Po vytvoření projektu pluginu musíte otevřít jeho soubor
.csprojv libovolném textovém editoru a nahradit jeho obsah následujícím:<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>netcoreapp3.1</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>..\..\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> </PropertyGroup> <ItemGroup> <ProjectReference Include="..\..\Presentation\Nop.Web.Framework\Nop.Web.Framework.csproj" /> <ClearPluginAssemblies Include="$(MSBuildProjectDirectory)\..\..\Build\ClearPluginAssemblies.proj" /> </ItemGroup> <!-- This target execute after "Build" target --> <Target Name="NopTarget" AfterTargets="Build"> <!-- Delete unnecessary libraries from plugins path --> <MSBuild Projects="@(ClearPluginAssemblies)" Properties="PluginPath=$(MSBuildProjectDirectory)\$(OutDir)" Targets="NopClear" /> </Target> </Project>Tip
PLUGIN_OUTPUT_DIRECTORY nahraďte 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 se reference z již odkazovaných knihoven načtou automaticky. Je to tedy velmi pohodlné.
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 souboruplugin.jsonnaleznete v části Soubor plugin.jsonPosledním povinným krokem je vytvoření třídy, která implementuje rozhraní IPlugin (jmenný prostor Nop.Services.Plugins). nopCommerce má 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á pro vytváření nových pluginů platebních metod. Obsahuje některé metody specifické pouze pro platební metody, například 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í podporovaných způsobů doručení a odpovídajících sazeb za dopravu. Například UPS, UPS, FedEx apod.
- 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 jsou Facebook, X (Twitter), OpenID apod.
- 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é
Důležitá poznámka: Po každém sestavení projektu vyčistěte solution, než provedete změny. Některé prostředky se ukládají do mezipaměti a mohou vývojáře přivést k šílenství.
Po přidání pluginu může být nutné solution znovu sestavit. Pokud ve složce Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY nevidíte DLL svého pluginu, musíte solution znovu sestavit. nopCommerce nezobrazí váš plugin na stránce Místní 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, když přejdete do Administrace → Konfigurace → Místní pluginy (Admin area → Configuration → Local Plugins). Jak jste ale jistě uhodli, náš plugin nic nedělá. Nemá dokonce ani uživatelské rozhraní pro svou konfiguraci. Vytvořme tedy stránku pro konfiguraci pluginu.
Nyní potřebujeme vytvořit controller, model a view.
- MVC controllery jsou zodpovědné za odpovídání na požadavky zaslané 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 aplikace, která není obsažena ve view ani v controlleru.
Více informací naleznete o vzoru MVC.
Pojďme tedy začít:
Vytvořte model. Do nového pluginu přidejte složku Models a poté přidejte novou třídu modelu, která vyhovuje 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. 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 layout „_ConfigurePlugin“.Ujistěte se také, že máte v adresáři \Views soubor
_ViewImports.cshtml. 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. Takové pojmenování controllerů samozřejmě není povinné (jde jen o doporučení). Poté vytvořte odpovídající 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 pomocí fyzické cesty k view:~/Plugins/{PluginOutputDirectory}/Views/Configure.cshtml.Pro metodu akce použijte následující atributy:
[AuthorizeAdmin] //confirms access to the admin panel [Area(AreaNames.Admin)] //specifies the area containing a controller or actionOtevř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 má metodu GetConfigurationPageUrl, která vrací konfigurační URL:
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 pro konfiguraci pluginu v Administrace → Konfigurace → Místní 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. Pak už jen stačí přejmenovat příslušné třídy a adresáře.
Struktura projektu pluginu PayPalStandard vypadá například jako na obrázku níže:

Zpracování metod „Install“, „Uninstall“ a „Update“
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 (pokud je to potřeba).
- Uninstall. Tato metoda bude vyvolána během odinstalace pluginu.
- Update. Tato metoda bude vyvolána během aktualizace pluginu (když se změní jeho verze v souboru
plugin.json).
Důležité
Důležitá poznámka: Pokud přepíšete některou z těchto metod, 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 \App_Data\plugins.json. Seznam se vytváří během instalace.
Routy
Nyní se podíváme, jak registrovat routy pluginu. Routing v ASP.NET Core je zodpovědný za mapování příchozích požadavků prohlížeče na konkrétní akce MVC controllerů. Více informací naleznete o routingu. 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(IEndpointRouteBuilder endpointRouteBuilder)
{
//PDT
endpointRouteBuilder.MapControllerRoute("Plugin.Payments.PayPalStandard.PDTHandler", "Plugins/PaymentPayPalStandard/PDTHandler",
new { controller = "PaymentPayPalStandard", action = "PDTHandler" });
}
public int Priority => -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 odpovídaly 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 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 úvodní kroky. Například vytváření složek (Controllers, Views, Models atd.), dalších požadovaných souborů (DependencyRegistrar.cs, _ViewImports.cshtml, ObjectContex, plugin.json atd.), konfiguraci, reference projektů atd.