diff --git a/docs/cs/AspNetCore/Widgets.md b/docs/cs/AspNetCore/Widgets.md index 9dfcddfa6d..c885da9c62 100644 --- a/docs/cs/AspNetCore/Widgets.md +++ b/docs/cs/AspNetCore/Widgets.md @@ -2,16 +2,16 @@ ABP poskytuje model a infastrukturu k vytváření **znovu použitelných widgetů**. Systém widgetů je rozšíření pro [ASP.NET Core pohledové komponenty](https://docs.microsoft.com/en-us/aspnet/core/mvc/views/view-components). Widgety jsou zvláště užitečné, když chcete; -* Definovat widgety v znovu použitelných **[modulech](../Module-Development-Basics.md)**. * Mít závislosti na **skriptech & stylech** ve vašem widgetu. -* Vytvářet **[řídící panely](Dashboards.md)** za použítí widgetů. +* Vytvářet **řídící panely** za použítí widgetů. +* Definovat widgety v znovu použitelných **[modulech](../Module-Development-Basics.md)**. * Spolupráci widgetů s **[authorizačními](../Authorization.md)** a **[svazovacími](Bundling-Minification.md)** systémy. ## Základní definice widgetu ### Tvorba pohledové komponenty -Jako první krok, vytvoříme běžnou ASP.NET Core pohledovou komponentu: +Jako první krok, vytvořte běžnou ASP.NET Core pohledovou komponentu: ![widget-basic-files](../images/widget-basic-files.png) @@ -33,7 +33,9 @@ namespace DashboardDemo.Web.Pages.Components.MySimpleWidget } ```` -Dědění z `AbpViewComponent` není vyžadováno. Můžeme dědit ze standardního ASP.NET Core `ViewComponent`. `AbpViewComponent` pouze definuje pár základních a užitečných vlastnosti. +Dědění z `AbpViewComponent` není vyžadováno. Můžete dědit ze standardního ASP.NET Core `ViewComponent`. `AbpViewComponent` pouze definuje pár základních a užitečných vlastnosti. + +Můžete vložit službu a pomocí metody `Invoke` z ní získat některá data. Možná budete muset provést metodu Invoke jako asynchronní `public async Task InvokeAsync()`. Podívejte se na dokument [ASP.NET Core ViewComponents](https://docs.microsoft.com/en-us/aspnet/core/mvc/views/view-components) pro všechna další použítí. **Default.cshtml**: @@ -46,7 +48,7 @@ Dědění z `AbpViewComponent` není vyžadováno. Můžeme dědit ze standardn ### Definice widgetu -Přidáme atribut `Widget` k třídě `MySimpleWidgetViewComponent` pro označení této pohledové komponenty jako widgetu: +Přidejte atribut `Widget` k třídě `MySimpleWidgetViewComponent` pro označení této pohledové komponenty jako widgetu: ````csharp using Microsoft.AspNetCore.Mvc; @@ -68,7 +70,7 @@ namespace DashboardDemo.Web.Pages.Components.MySimpleWidget ## Vykreslení widgetu -Vykreslení widgetu je vcelku standardní. Použijeme metodu `Component.InvokeAsync` v razor pohledu/stránce jako s kteroukoliv jinou pohledovou komponentou. Příklady: +Vykreslení widgetu je vcelku standardní. Použijte metodu `Component.InvokeAsync` v razor pohledu/stránce jako s kteroukoliv jinou pohledovou komponentou. Příklady: ````xml @await Component.InvokeAsync("MySimpleWidget") @@ -77,11 +79,61 @@ Vykreslení widgetu je vcelku standardní. Použijeme metodu `Component.InvokeAs První přístup používá název widgetu, zatímco druhý používá typ pohledové komponenty. +### Widgety s argumenty + +Systém ASP.NET Core pohledových komponent umožňuje přijímat argumenty pro pohledové komponenty. Níže uvedená pohledová komponenta přijímá `startDate` a `endDate` a používá tyto argumenty k získání dat ze služby. + +````csharp +using System; +using System.Threading.Tasks; +using Microsoft.AspNetCore.Mvc; +using Volo.Abp.AspNetCore.Mvc; +using Volo.Abp.AspNetCore.Mvc.UI.Widgets; + +namespace DashboardDemo.Web.Pages.Shared.Components.CountersWidget +{ + [Widget] + public class CountersWidgetViewComponent : AbpViewComponent + { + private readonly IDashboardAppService _dashboardAppService; + + public CountersWidgetViewComponent(IDashboardAppService dashboardAppService) + { + _dashboardAppService = dashboardAppService; + } + + public async Task InvokeAsync( + DateTime startDate, DateTime endDate) + { + var result = await _dashboardAppService.GetCountersWidgetAsync( + new CountersWidgetInputDto + { + StartDate = startDate, + EndDate = endDate + } + ); + + return View(result); + } + } +} +```` + +Nyní musíte předat anonymní objekt k předání argumentů tak jak je ukázáno níže: + +````xml +@await Component.InvokeAsync("CountersWidget", new +{ + startDate = DateTime.Now.Subtract(TimeSpan.FromDays(7)), + endDate = DateTime.Now +}) +```` + ## Název widgetu Výchozí název pohledových komponent je vypočítán na základě názvu typu pohledové komponenty. Pokud je typ pohledové komponenty `MySimpleWidgetViewComponent` potom název widgetu bude `MySimpleWidget` (odstraní se `ViewComponent` postfix). Takto ASP.NET Core vypočítává název pohledové komponenty. -Chceme-li přizpůsobit název widgetu, stačí použít standardní atribut `ViewComponent` z ASP.NET Core: +Chcete-li přizpůsobit název widgetu, stačí použít standardní atribut `ViewComponent` z ASP.NET Core: ```csharp using Microsoft.AspNetCore.Mvc; @@ -108,7 +160,7 @@ ABP bude respektovat přizpůsobený název při zpracování widgetu. ### Zobrazovaný název -Můžeme také definovat čitelný & lokalizovatelný zobrazovaný název pro widget. Tento zobrazovaný název může být využít na uživatelském rozhraní kdykoliv je to potřeba. Zobrazovaný název je nepovinný a lze ho definovat pomocí vlastností atributu `Widget`: +Můžete také definovat čitelný & lokalizovatelný zobrazovaný název pro widget. Tento zobrazovaný název může být využít na uživatelském rozhraní kdykoliv je to potřeba. Zobrazovaný název je nepovinný a lze ho definovat pomocí vlastností atributu `Widget`: ````csharp using DashboardDemo.Localization; @@ -222,6 +274,181 @@ Systém přispěvatelů balíků je velmi schopný. Pokud váš widget použív Podívejte se na dokumentaci [svazování & minifikace](Bundling-Minification.md) pro více informací o tomto systému. +## RefreshUrl + +Widget může navrhnout `RefreshUrl`, který se používá vždy, když je potřeba widget aktualizovat. Je-li definován, widget se při každé aktualizaci znovu vykreslí na straně serveru (viz refresh `methoda` u `WidgetManager` níže). + +````csharp +[Widget(RefreshUrl = "Widgets/Counters")] +public class CountersWidgetViewComponent : AbpViewComponent +{ + +} +```` + +Jakmile pro svůj widget definujete `RefreshUrl`, musíte poskytnout koncový bod pro jeho vykreslení a vrátit ho: + +````csharp +[Route("Widgets")] +public class CountersWidgetController : AbpController +{ + [HttpGet] + [Route("Counters")] + public IActionResult Counters(DateTime startDate, DateTime endDate) + { + return ViewComponent("CountersWidget", new {startDate, endDate}); + } +} +```` + +Trasa `Widgets/Counters` předchozímu `RefreshUrl`. + +> Widget lze obnovit dvěma způsoby: Prvním způsobem je použití `RefreshUrl`, kdy se znovu vykreslí na serveru a nahradí HTML vrácené tím ze serveru. Druhým způsobem widget získá data (obvykle JSON objekt) ze serveru a obnoví se sám u klienta (viz refresh metoda v sekci Widget JavaScript API). + +## JavaScript API + +Možná bude potřeba vykreslit a obnovit widget na straně klienta. V takových případech můžete použít ABP `WidgetManager` a definovat API pro vaše widgety. + +### WidgetManager + +`WidgetManager` se používá k inicializaci a aktualizaci jednoho nebo více widgetů. Vytvořte nový `WidgetManager` jako je ukázáno níže: + +````js +$(function() { + var myWidgetManager = new abp.WidgetManager('#MyDashboardWidgetsArea'); +}) +```` + +`MyDashboardWidgetsArea` může obsahovat jeden nebo více widgetů. + +> Použíti `WidgetManager` uvnitř document.ready (jako nahoře) je dobrá praktika jelikož jeho funkce používají DOM a potřebují, aby byl DOM připraven. + +#### WidgetManager.init() + +`init` jednoduše inicializuje `WidgetManager` a volá metody `init` v souvisejících widgetech pokud je obsahují (podívejte se na sekci Widget JavaScript API section níže) + +```js +myWidgetManager.init(); +``` + +#### WidgetManager.refresh() + +`refresh` metoda obnoví všechny widgety související s tímto `WidgetManager`: + +```` +myWidgetManager.refresh(); +```` + +#### WidgetManager možnosti + +WidgetManager má několik dalších možností. + +##### Filtrační formulář + +Pokud vaše widgety vyžadují parametry/filtry pak budete obvykle mít formulář pro filtrování widgetů. V takových případech můžete vytvořit formulář, který obsahuje prvky formuláře a oblast řídicího panelu s nějakými widgety uvnitř. Příklad: + +````xml +
+ ...prvky formuláře +
+ +
+ ...widgety +
+```` + +`data-widget-filter` atribut propojuje formulář s widgety. Kdykoli je formulář odeslán, všechny widgety jsou automaticky aktualizovány pomocí polí formuláře jako filtru. + +Místo atributu `data-widget-filter`, můžete použít parametr `filterForm` v konstruktoru `WidgetManager`. Příklad: + +````js +var myWidgetManager = new abp.WidgetManager({ + wrapper: '#MyDashboardWidgetsArea', + filterForm: '#MyDashboardFilterForm' +}); +```` + +##### Zpětné volání filtru + +Možná budete chtít mít lepší kontrolu nad poskytováním filtrů při inicializaci a aktualizaci widgetů. V tomto případě můžete použít volbu `filterCallback`: + +````js +var myWidgetManager = new abp.WidgetManager({ + wrapper: '#MyDashboardWidgetsArea', + filterCallback: function() { + return $('#MyDashboardFilterForm').serializeFormToObject(); + } +}); +```` + +Tento příklad ukazuje výchozí implementaci `filterCallback`. Pomocí polí můžete vrátit jakýkoli JavaScript objekt. Příklad: + +````js +filterCallback: function() { + return { + 'startDate': $('#StartDateInput').val(), + 'endDate': $('#EndDateInput').val() + }; +} +```` + +Vrácené filtry jsou předávány všem widgetům na `init` a` refresh`. + +### Widget JavaScript API + +Widget může definovat rozhraní API jazyka JavaScript, které je v případě potřeby vyvoláno přes `WidgetManager`. Ukázku kódu níže lze použít k definování API pro widget. + +````js +(function () { + abp.widgets.NewUserStatisticWidget = function ($wrapper) { + + var getFilters = function () { + return { + ... + }; + } + + var refresh = function (filters) { + ... + }; + + var init = function (filters) { + ... + }; + + return { + getFilters: getFilters, + init: init, + refresh: refresh + }; + }; +})(); +```` + +`NewUserStatisticWidget` je tady název widgetu. Měl by odpovídat názvu widgetu definovanému na straně serveru. Všechny funkce jsou volitelné. + +#### getFilters + +Pokud má widget vlastní interní filtry, měla by tato funkce vrátit objekt filtru. Příklad: + +````js +var getFilters = function() { + return { + frequency: $wrapper.find('.frequency-filter option:selected').val() + }; +} +```` + +Tuto metodu používá `WidgetManager` při vytváření filtrů. + +#### init + +Slouží k inicializaci widgetu kdykoli je potřeba. Má argument filtru, který lze použít při získávání dat ze serveru. Metoda `init` je použita když je volána funkce `WidgetManager.init()`. Použita je i v případě že váš widget vyžaduje úplné obnovení při aktualizaci. Viz `RefreshUrl` v možnostech widgetu. + +#### refresh + +Slouží k aktualizaci widgetu kdykoli je potřeba. Má argument filtru, který lze použít při získávání dat ze serveru. Metoda `refresh` se používá kdykoliv je volána funkce `WidgetManager.refresh()`. + ## Autorizace Některé widgety budou pravděpodobně muset být dostupné pouze pro ověřené nebo autorizované uživatele. V tomto případě použijte následující vlastnosti atributu `Widget`: @@ -249,7 +476,7 @@ namespace DashboardDemo.Web.Pages.Components.MySimpleWidget } ```` -## Možnosti widgetu +## WidgetOptions Jako alternativu k atributu `Widget` můžete ke konfiguraci widgetů použít `WidgetOptions`: @@ -271,4 +498,8 @@ Configure(options => }); ```` -> Tip: `WidgetOptions` lze také použít k získání existujícího widgetu a ke změně jeho konfigurace. To je obzvláště užitečné, pokud chcete změnit konfiguraci widgetu uvnitř modulu používaného vaší aplikací. Použíjte `options.Widgets.Find` k získání existujícího `WidgetDefinition`. \ No newline at end of file +> Tip: `WidgetOptions` lze také použít k získání existujícího widgetu a ke změně jeho konfigurace. To je obzvláště užitečné, pokud chcete změnit konfiguraci widgetu uvnitř modulu používaného vaší aplikací. Použíjte `options.Widgets.Find` k získání existujícího `WidgetDefinition`. + +## Podívejte se také na + +* [Příklad projektu (zdrojový kód)](https://github.com/abpframework/abp/tree/dev/samples/DashboardDemo). \ No newline at end of file diff --git a/docs/cs/images/widget-basic-files.png b/docs/cs/images/widget-basic-files.png new file mode 100644 index 0000000000..bf5f122d42 Binary files /dev/null and b/docs/cs/images/widget-basic-files.png differ