Extension:Echo/Creating a new notification type/cs

Notifikační systém umožňuje přihlášeným uživatelům přijímat upozornění a oznámení i z jiných instancí MediaWiki, pokud jsou do tohoto systému zapojeny. U všech projektů Wikimedie tak dostávají uživatelé oznámení téměř ze všech wikinách, provozovaných v rámci jejího clusteru. Ovšem tento notifikační systém mohou využívat i třetí strany, které do něj zapojeny nejsou. Tzv. "třetí strany" ho mohou používat v rámci jedné wiki, ale i celé skupiny vzájemně propojených wikin (a mít tak pro ně společný systém upozornění). Tento systém umožňuje vývojářům rozšíření generovat nové typy oznámení, které pak mohou za splnění určitých podmínek dostávat ostatní uživatelé. Tento dokument popisuje jakým způsobem se takové oznámení tvoří, vysvětluje osvědčené postupy a upozorňuje na úskalí, kterým je při tom potřeba se vyhnout.



Jak notifikace fungují - úvod
Upozornění, velmi obecně řečeno, je založeno na dvou konceptech - události (Event) a prezentačním modelu (PresentationModel), který jej zpracuje do nějaké akce. Událost ukládá detaily spojené s událostí a prezentační model definuje, jakým způsobem se má tato událost prezentovat v prostředí uživatelského rozhraní.

EchoEvent
Třída  definuje obecné události, shromažďuje informace o související stránce, uživateli a wiki a vkládá je do databáze. Události jsou obecné a reagovat lze na ně i několika různými způsoby, pokud jsou nadefinovány. Dejme tomu, že zmíníte 4 osoby, což vytvoří jednu událost, na kterou ale budou odkazovat (a přes 'trigger' svázaná) oznámení pro tyto čtyři zmíněné uživatele. Všechny tyto jejich individuální notifikace však budou odkazovat na jednu a tu samou událost.

EchoPresentationModel
Každý typ notifikace tak vyžaduje svůj prezentační model. Způsob, který bude definovat, co se v oznámení zobrazí, kam se bude odkazovat a jaké další sekundární akce s tím mají být spojeny. Front-endové komponenty notifikačního systému (vyskakovací okno s oznámením a stránka ) tyto informace načtou a na jejich základě vygenerují příslušné oznámení.

Typ notifikace pokaždé vychází z výchozí definice ve třídě. Tato třída definuje základní chování všech oznámení a každé podřízené oznámení ji nejprve musí rozšířit a následně přizpůsobit detaily svým potřebám.



Jak fungují události
Pokud chcete vytvořit nový typ oznámení, měli byste nejprve vyvolat příslušnou událost. Logický postup je následující:


 * 1) Pokud je to na místě, vytvoří váš kód událost prostřednictvím
 * 2) V rámci definice události byste měli podrobně popsat, kteří uživatelé mají obdržet oznámení o této události. To je definováno parametrem  . (Na příklad toho, jak je to uděláno se podívejte do metody 'user-locators' u rozšíření Flow, která slouží k vyhledávání uživatelů, kteří sledují článek s konkrétním názvem).
 * 3) Příslušná událost se uloží do databáze a příslušným uživatelům se následně začne zobrazovat odpovídající oznámení.
 * 4) Když si uživatelé vyžádají seznam oznámení z rozhraní API, systém vyhledá příslušný model prezentace a vytvoří data - název, primární odkaz, sekundární odkazy, příslušného uživatele atd.
 * 5) Ke zobrazení příslušného oznámení použije front-end následně uložená strukturovaná data.

Definice


Definice události
Definice událostí se vyskytují v metodě, která reaguje na háček. Tento hák obsahuje tři proměnné:, , $icons.



Definování kategorie události
Uživatelé mají obecně povoleno zaškrtnout/zrušit zaškrtnutí možnosti dostávat upozornění na web nebo e-mail v předvolbách. Kategorie předvoleb má nápovědu a měla by být definována jako. Název kategorie se používá jako klíč a je tím, na co pak odkazuje definice události v parametru "category". Musíte také definovat zprávu s názvem  a nahradit   skutečným názvem kategorie. Toto se používá v  na kartě Oznámení.



Definování ikony oznámení
Upozornění se zobrazují s ikonami. Pokud ikona není nastavena, zobrazí se výchozí ikona. Pokud je ikona nová, musí být načtena a definována pomocí $icons.

Definujte ikonu pomocí celé adresy URL ikony:

Případně můžete použít cestu k souboru, která je relativní vzhledem k :



Definování informací o události


Podrobnosti o vytvoření události
Když vytváříme a spouštíme událost, musíme také poskytnout podrobnosti:



Definice prezentačního modelu
Prezentační modely mají být velmi flexibilní, aby umožňovaly vytváření typů upozornění se specifickými displeji. Na rozdíl od definice a vytvoření události je prezentační model samostatnou třídou a vyžaduje jeho rozšíření a vytvoření metod specifických pro případ oznámení. Toto jsou definice základní třídy :



Struktura sekundárních odkazů
Informace o sekundárních odkazech umožňují oznámením specifikovat dílčí odkazy na akce, které rozšiřují hlavní primární odkaz pro oznámení. Například oznámení o nějaké úpravě revize může mít svůj primární odkaz ukazovat na stránku s rozdílem revize, ale také mít sekundární odkazy směřující na uživatelskou stránku uživatele, který provedl změnu, nebo odkaz na zobrazení stránky, která byla změněna.

Sekundární odkazy také umožňují akce řízené API (akce ) pro akce jako nebo jiné, které vyžadují, aby front-end požádal o požadavek AJAX na API přímo z oznámení. Další podrobnosti o dynamických akcích jsou mimo rozsah tohoto kurzu.

Obecná struktura sekundárních odkazů:



Návod: Vytvoření nového typu oznámení
Řekněme, že máme rozšíření, které vede seznam uživatelů, kteří mají zájem o nové tituly vytvořené s konkrétními slovy. Rozšíření umožňuje uživatelům přidávat a odebírat se ze seznamu sledovaných pro určitý seznam slov v názvu a poslouchá háček pro vytváření nových stránek na wiki, aby identifikoval relevantní stránky. Když je vytvořena relevantní stránka, kód rozšíření vytvoří událost s relevantními podrobnostmi a upozorní uživatele, kteří jsou na seznamu pro tuto kombinaci slov.

Tato část ukáže, jak vytvořit tento nový typ oznámení.



Definování události
Musíme se ujistit, že naše událost je definována v systému. To se provádí poslechnutím háčku  a definováním definice události:

Další příklad tohoto můžete vidět v Thanks extension.



Identifikujte příslušné uživatele, které chcete upozornit
Systém oznámení se pokusí upozornit relevantní uživatele, ale nemůže uhodnout, kdo to jsou. The code that creates the event needs to supply that information. To do that, we should create a function that is then inserted into the definition of the new event.

In this case, we will want to go over the list of users and add them all:

Adding code to trigger the event
Now that we have a way to identify who we want to notify, we need to actually trigger this event. Our hypothetical extension listens to page creation hook and then checks to see if the new title has words that fit the list. However the extension code does this, once it identifies a title that fits a list, it will create an event and notify the relevant users.

The code below skips the actual operation of listening to new page creation and checking the words, and jumps straight into defining the new event:

You can see an example of filtering out mentioned users in Flow's event for flow-new-topic.

Creating a presentation model
Now that everything is set up, we can create our presentation model. We will have to extend  and implement our methods. You can see a few examples of these type of models in several extensions like   ,  and inside    itself.

Here's an example of a presentation model for our hypothetical extension:

And that's it! Our new notification is now active and will be displayed to the relevant users with the header and body messages and the primary and secondary links we defined.

How to bundle notifications

 * Make sure your bundle config is set to true in the echo event definition:
 * Add a hook for bundling rules:


 * Hook up the function in extension.json:


 * You can use  in your presentation model code to check if you're in a bundled notification, and vary the header and body messages accordingly:
 * When an expandable bundle is expanded, each sub-notification is rendered individually. By default is displayed, but it is recommended that you supply a shorter message in your presentation model code for this case using :

And you're done! Don't forget to add your messages. Also note that bundles may or may not be expandable.

Pitfalls and warnings
