nopCommerce Dokumentace

Jak napsat widget pro nopCommerce

K rozšíření funkcionality nopCommerce se používají widgety. Existují různé typy widgetů, například Swiper a Google Analytics, které jsou již součástí repozitáře nopCommerce. Marketplace nopCommerce již obsahuje různé widgety (bezplatné i placené), které mohou splňovat vaše požadavky. Pokud jste žádný vhodný nenašli, jste na správném místě, protože tento článek vás provede procesem vytvoření widgetu podle vašich potřeb.

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

  1. Začněte vytvořením nového projektu Class Library (knihovna tříd) v řešení. Doporučujeme umístit widget do adresáře Plugins v kořenové složce zdrojového kódu, kde se již nacházejí ostatní widgety a pluginy.

    image1

    Poznámka

    Nezaměňujte tento adresář s adresářem, který existuje v adresáři Presentation\Nop.Web. Adresář Plugins v adresáři Nop.Web obsahuje zkompilované soubory pluginů.

    Doporučený název projektu widgetu je Nop.Plugin.Widgets.{Name}. {Name} je název vašeho widgetu (například „GoogleAnalytics“). Například widget Google Analytics má následující název: Nop.Plugin.Widgets.GoogleAnalytics. Upozorňujeme však, že to není povinné a pro widget můžete zvolit libovolný název. Například „MyFirstNopWidget“. Struktura adresáře Plugins v řešení vypadá následovně.

    image2

  2. Po vytvoření projektu widgetu je třeba upravit obsah souboru .csproj pomocí libovolného dostupného textového editoru. Nahraďte 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\WIDGET_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.csproj" />
        </ItemGroup>
        <!-- This target execute after "Build" target -->
        <Target Name="NopTarget" AfterTargets="Build">
            <!-- Delete unnecessary libraries from plugins path -->
            <MSBuild Projects="@(ClearPluginAssemblies)" Properties="PluginPath=$(OutDir)" Targets="NopClear" />
        </Target>
    </Project>
    

    Poznámka

    Hodnotu WIDGET_OUTPUT_DIRECTORY je třeba nahradit názvem pluginu, například Widgets.GoogleAnalytics.

  3. Po úpravě souboru .csproj je třeba přidat soubor plugin.json, který je pro widget povinný. Tento soubor obsahuje metainformace popisující váš widget. Stačí tento soubor zkopírovat z jakéhokoli jiného existujícího pluginu/widgetu a upravit jej podle svých potřeb. Informace o souboru plugin.json naleznete v článku Soubor plugin.json.

    Posledním povinným krokem je vytvoření třídy, která implementuje BasePlugin (jmenný prostor Nop.Core.Plugins) a rozhraní IWidgetPlugin (jmenný prostor Nop.Services.Cms). 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 živého chatu v pravém dolním rohu webu.

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

Nyní můžete widget zobrazit přechodem na Administrace → Konfigurace → Lokální pluginy (Admin area → Configuration → Local Plugins).

image4

Když je plugin/widget nainstalován, uvidíte tlačítko Odinstalovat (Uninstall). Pro zlepšení výkonu je dobrým zvykem odinstalovat pluginy/widgety, které nejsou potřeba.

image5 Pokud plugin/widget není nainstalován nebo byl odinstalován, zobrazí se tlačítka Instalovat (Install) a Smazat (Delete). Smazáním se ze serveru odstraní fyzické soubory.

Jak jste ale jistě uhodli, náš widget nic nedělá. Nemá ani uživatelské rozhraní pro svou konfiguraci. Vytvořme tedy stránku pro konfiguraci widgetu.

Nyní potřebujeme vytvořit controller, model, view a komponentu view (view component).

  • 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 značky HTML a obsah, který se odesílá do prohlížeče. Při práci s aplikací ASP.NET MVC je view ekvivalentem stránky.
  • Komponenta view, která implementuje NopViewComponent a obsahuje logiku a kód pro vykreslení view.
  • MVC model obsahuje veškerou logiku aplikace, která není obsažena ve view ani v controlleru.

Pojďme tedy začít:

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

  2. Vytvořte view. Do nového widgetu 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“.

    @{
        Layout = "_ConfigurePlugin";
    }
    
  3. 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 nebo widgetu.

    image7

  4. Vytvořte controller. Do nového widgetu přidejte složku Controllers a poté přidejte novou třídu controlleru. Dobrým zvykem je pojmenovávat controllery pluginů Widgets{Name}Controller.cs. Například WidgetsGoogleAnalyticsController. Pojmenovávat controllery tímto způsobem samozřejmě není povinné, jde pouze 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.

    public async Task<IActionResult> Configure()
    {
        if (!await _permissionService.AuthorizeAsync(StandardPermissionProvider.ManageWidgets))
            return AccessDeniedView();
    
        //load settings for a chosen store scope
        var storeScope = await _storeContext.GetActiveStoreScopeConfigurationAsync();
        var myWidgetSettings = await _settingService.LoadSettingAsync<MyWidgetSettings>(storeScope);
    
        var model = new ConfigurationModel
        {
            // configuration model settings here
        };
    
        if (storeScope > 0)
        {
            // override settings here based on store scope
        }
    
        return View("~/Plugins/Widgets.MyFirstNopWidget/Views/Configure.cshtml", model);
    }
    
  5. Pro metodu akce 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
    [AdminAntiForgery] //Helps prevent malicious scripts from submitting forged page requests.
    

    Otevřete například widget GoogleAnalytics a podívejte se na jeho implementaci WidgetsGoogleAnalyticsController. Poté byste pro každý widget, 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 {CONTROLLER_NAME} je název vašeho controlleru a {ACTION_NAME} je název akce (obvykle „Configure“). Každý widget by měl určit seznam zón widgetů. Základní třída s názvem IWidgetPlugin má metodu GetWidgetZones, která vrací seznam zón widgetů, ve kterých se bude vykreslovat.

    public Task<IList<string>> GetWidgetZonesAsync()
    {
        return Task.FromResult<IList<string>>(new List<string> {PublicWidgetZones.HeadHtmlTag });
    }
    

    Seznam veřejných zón widgetů najdete na tomto odkazu a zóny widgetů administrace na tomto odkazu. Kromě GetWidgetZonesAsync má IWidgetPlugin metodu GetWidgetViewComponentName, která vrací název ViewComponent. Jako parametr přijímá název „widgetZone“ a lze ji použít k vykreslení různých view v závislosti na zvolené zóně widgetu.

    public string GetWidgetViewComponentName(string widgetZone)
    {
        return "MyFirstWidget";
    }
    

Struktura projektu widgetu Google Analytics

image11

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

Tento krok je volitelný. Některé widgety mohou během instalace vyžadovat další logiku. Widget může například vložit nové lokalizační zdroje nebo hodnoty nastavení. Otevřete tedy svou implementaci IWidgetPlugin (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. Můžete zde inicializovat libovolná nastavení, vložit nové lokalizační zdroje nebo vytvořit nové databázové tabulky (je-li to potřeba).

    public override async Task InstallAsync()
    {
        // custom logic like adding settings, locale resources, and database table(s) here
    
        await base.InstallAsync();
    }
    
  2. UninstallAsync. Tato metoda se volá během odinstalace pluginu. Můžete zde odstranit nastavení, lokalizační zdroje nebo databázové tabulky, které widget vytvořil během instalace.

    public override async Task UninstallAsync()
    {
        // custom logic like removing settings, locale resources, and database table(s) which was created during widget installation
    
        await base.UninstallAsync();
    }
    

    Důležité

    Pokud jednu z těchto metod přepíšete, neskrývejte její základní implementaci – base.InstallAsync() a base.UninstallAsync(), které jsou vyznačeny na obrázcích výše.