nopCommerce Dokumentace

Použití DataTables

V tomto návodu se naučíme, jak rozšířit funkčnost nopCommerce o vlastní funkce pro administraci a vytvořit stránku obsahující tabulku s daty jako report. Než s tímto návodem začnete, měli byste mít určité předchozí znalosti a porozumění následujícím tématům.

Pokud výše uvedená témata neznáte, důrazně doporučujeme se s nimi nejprve seznámit.

Tento návod vám ukáže, jak vytvořit tabulku, která zobrazuje informace o rozložení uživatelů podle zemí (na základě fakturační adresy). Projděme si krok za krokem proces vytvoření této funkce.

Vytvoření projektu pluginu nopCommerce

Předpokládáme, že již víte, kde a jak vytvořit projekt pluginu nopCommerce a nakonfigurovat jej podle standardů nopCommerce. Pokud ne, navštivte tuto stránku, kde se dozvíte, jak projekt pluginu nopCommerce vytvořit a nakonfigurovat.

Pokud jste projekt pluginu vytvořili a nakonfigurovali podle výše uvedeného odkazu, měli byste mít strukturu složek podobnou této.

image1

Models/CustomersDistribution.cs

Nejprve vytvořme ve složce Models model s názvem CustomersDistribution.

public record CustomersDistribution : BaseNopModel
{
    /// <summary>
    /// Country based on the billing address.
    /// </summary>
    public string Country { get; set; }

    /// <summary>
    /// Number of customers from a specific country.
    /// </summary>
    public int NoOfCustomers { get; set; }
}

Do složky Models přidejme také vyhledávací model s názvem CustomersByCountrySearchModel.

public record CustomersByCountrySearchModel : BaseSearchModel
{
}

nopCommerce pro přístup k datům používá návrhový vzor repository, který je ideální pro mechanismus dependency injection.

Services/ICustomersByCountry.cs

Nyní vytvořme službu, která načítá potřebná data z databáze. Pro službu vytvoříme rozhraní a třídu služby, která toto rozhraní implementuje.

public interface ICustomersByCountry
{
    Task<List<CustomersDistribution>> GetCustomersDistributionByCountryAsync()
}

Services/CustomersByCountry.cs

Zde vytváříme třídu s názvem CustomersByCountry, která implementuje rozhraní ICustomersByCountry.

public class CustomersByCountry : ICustomersByCountry
{
    private readonly IAddressService _addressService;
    private readonly ICountryService _countryService;
    private readonly ICustomerService _customerService;

    public CustomersByCountry(IAddressService addressService, 
        ICountryService countryService,
        ICustomerService customerService)
    {
        _addressService = addressService;
        _countryService = countryService;
        _customerService = customerService;
    }

    public async Task<List<CustomersDistribution>> GetCustomersDistributionByCountryAsync()
    {
        return await _customerService.GetAllCustomersAsync()
            .Where(c => c.ShippingAddressId != null)
            .Select(c => new
            {
                await (_countryService.GetCountryByAddressAsync(_addressService.GetAddressById(c.ShippingAddressId ?? 0))).Name,
                c.Username
            })
            .GroupBy(c => c.Name)
            .Select(cbc => new CustomersDistribution { Country = cbc.Key, NoOfCustomers = cbc.Count() }).ToList();
    }
}

Implementovali jsme metodu rozhraní, která načítá data z databáze. Tento přístup jsme zvolili proto, abychom mohli tuto službu vložit do controlleru pomocí technik dependency injection.

Infrastructure/PluginNopStartup.cs

Abychom zaregistrovali naše rozhraní a jeho implementaci v kontejneru dependency injection (DI), musíme vytvořit třídu, která implementuje rozhraní INopStartup. Toto rozhraní obsahuje dvě metody a jednu vlastnost. Zaměříme se především na implementaci metody ConfigureServices, ve které naše rozhraní zaregistrujeme v DI kontejneru.

/// <summary>
/// Represents object for the configuring services on application startup
/// </summary>
public class PluginNopStartup : INopStartup
{
    /// <summary>
    /// Add and configure any of the middleware
    /// </summary>
    /// <param name="services">Collection of service descriptors</param>
    /// <param name="configuration">Configuration of the application</param>
    public void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        //register custom services
        services.AddScoped<ICustomersByCountry, CustomersByCountry>();
    }

    /// <summary>
    /// Configure the using of added middleware
    /// </summary>
    /// <param name="application">Builder for configuring an application's request pipeline</param>
    public void Configure(IApplicationBuilder application)
    {
    }

    /// <summary>
    /// Gets order of this startup configuration implementation
    /// </summary>
    public int Order => 3000;
}

Controllers/CustomersByCountryController.cs

Nyní vytvořme třídu controlleru. Osvědčeným postupem je pojmenovávat controllery pluginů ve tvaru Controller.cs. Například TutorialCustomersByCountryController, tedy Controller. Pamatujte však, že pojmenování controlleru ve tvaru není povinné, jde pouze o způsob pojmenování doporučený nopCommerce; část Controller v názvu je však požadavkem .Net MVC.

    [AutoValidateAntiforgeryToken]
    [AuthorizeAdmin] //confirms access to the admin panel
    [Area(AreaNames.Admin)] //specifies the area containing a controller or action
    public class DistOfCustByCountryPluginController : BasePluginController
    {
        private readonly ICustomersByCountry _service;
        public DistOfCustByCountryPluginController(ICustomersByCountry service)
        {
            _service = service;
        }

        [HttpGet]
        public IActionResult Configure()
        {
            CustomersByCountrySearchModel customerSearchModel = new CustomersByCountrySearchModel
            {
                AvailablePageSizes = "10"
            };
            return View("~/Plugins/Tutorial.DistOfCustByCountry/Views/Configure.cshtml", customerSearchModel);
        }

        [HttpPost]
        public async Task<IActionResult> GetCustomersCountByCountry()
        {
            try
            {
                return Ok(new DataTablesModel { Data = await _service.GetCustomersDistributionByCountryAsync() });
            }
            catch (Exception ex)
            {
                return BadRequest(ex);
            }
        }
    }

Do controlleru vkládáme dříve vytvořenou službu ICustomersByCountry, abychom získali data z databáze. Vytvořili jsme zde dvě akce, jednu typu HttpGet a druhou typu HttpPost. Akce Configure vrací view s názvem „Configure.cshtml“, které jsme zatím nevytvořili. Akce GetCustomersCountByCountry pomocí vložené služby načítá data a vrací je ve formátu JSON. Tuto akci bude volat datová tabulka, která očekává odpověď jako objekt DataTablesModel. Nastavujeme zde proto vlastnost data, což jsou data, která se v tabulce vykreslí.

Views/Configure.cshtml

Nyní vytvořme view s DataTables, ve kterém zobrazíme naše data, aby si je mohli prohlížet naši uživatelé.

@using Nop.Web.Framework.Models.DataTables
@{
    Layout = "_ConfigurePlugin";
}

@await Html.PartialAsync("Table", new DataTablesModel
{
    Name = "customersDistributionByCountry-grid",
    UrlRead = new DataUrl("GetCustomersCountByCountry", "TutorialCustomersByCountry"),
    Paging = false,
    ColumnCollection = new List<ColumnProperty>
    {
        new ColumnProperty(nameof(CustomersDistribution.Country))
        {
            Title = "Country",
            Width = "300"
        },
        new ColumnProperty(nameof(CustomersDistribution.NoOfCustomers))
        {
            Title = "Number Of Customers",
            Width = "100"
        }
    }
})

Views/_ViewImports.cshtml

Soubor _ViewImports.cshtml obsahuje kód pro import všech potřebných referencí pro naše soubory view.

@inherits Nop.Web.Framework.Mvc.Razor.NopRazorPage<TModel>
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, Nop.Web.Framework

@using Microsoft.AspNetCore.Mvc.ViewFeatures
@using Nop.Web.Framework.UI
@using Nop.Web.Framework.Extensions
@using System.Text.Encodings.Web
@using Nop.Plugin.Tutorial.DistOfCustByCountry.Models
@using Nop.Web.Framework.Models.DataTables;
@using Microsoft.AspNetCore.Routing;
  • V Configure.cshtml používáme částečné view (partial view) s názvem Table. Jde o implementaci JQuery DataTables v nopCommerce. Tento soubor najdeme v Nop.Web/Areas/Admin/Views/Shared/Table.cshtml. Tam uvidíte kód implementace DataTables. Tento view model přijímá pro konfiguraci DataTables třídu DataTablesModel. Vysvětleme si vlastnosti, které jsme pro třídu DataTablesModel nastavili.
  • Name: Nastaví se jako id pro DataTables.
  • UrlRead: URL, ze které bude DataTables načítat data k vykreslení v tabulce. Zde nastavujeme URL na akci GetCustomersCountByCountry controlleru TutorialCustomersByCountry, ze které získáváme data pro DataTables.
  • Paging: Tato vlastnost slouží k zapnutí nebo vypnutí stránkování pro DataTables.
  • ColumnCollection: Tato vlastnost obsahuje konfiguraci sloupců.

Existuje řada dalších vlastností, se kterými můžete experimentovat, abyste pochopili, k čemu každá z nich slouží.

Infrastructure/RouteProvider

Posledním krokem je registrace naší cesty (route) pro akci „GetCustomersCountByCountry“ controlleru „TutorialCustomersByCountry“. Cestu pro akci „Configure“ registrovat nemusíme, protože jsme ji již zaregistrovali ve třídě DistOfCustByCountryPlugin.

/// <summary>
/// Represents plugin route provider
/// </summary>
public class RouteProvider : IRouteProvider
{
    /// <summary>
    /// Register routes
    /// </summary>
    /// <param name="endpointRouteBuilder">Route builder</param>
    public void RegisterRoutes(IEndpointRouteBuilder endpointRouteBuilder)
    {
        //add route for the access token callback
        endpointRouteBuilder.MapControllerRoute("CustomersDistributionByCountry", "Plugins/Tutorial/CustomerDistByCountry/",
            new { controller = "TutorialCustomersByCountry", action = "GetCustomersCountByCountry" });
    }

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

Poznámka

Více o routingu v nopCommerce se dozvíte na této stránce

Nyní stačí projekt sestavit a spustit. Přihlaste se jako administrátor a přejděte do nabídky Lokální pluginy (Local plugins) v sekci Konfigurace (Configuration), kde uvidíte svůj nově vytvořený plugin. Nainstalujte jej. Po dokončení instalace uvidíte u svého pluginu tlačítko Konfigurovat (Configure). Pokud jste postupovali podle tohoto návodu správně, uvidíte výstup podobný obrázku níže:

image2