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ů Wikimedia tak dostávají uživatelé oznámení téměř ze všech wiki, 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 wiki (a mít tak pro ně společný systém upozornění). Tenhle 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ý ji 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 tyhle 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 $1) 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   (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ě zč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
Event definitions happen in the method that responds to the  hook. That hook includes three variables:, , $icons.

Defining the event category
Users are generally allowed to check/uncheck the option of receiving notifications in web or email in the preferences. The preference category has a tooltip, and should be defined with. The category name is used as the key, and is what the event definition then refers to in the "category" parameter. You also need to define a message with the name, replacing   with the actual category name. This is used in  under the Notifications tab.

Defining the notification icon
Notifications appear with icons. If an icon is not set up, a default icon will appear. If the icon is a new one, it must be loaded and defined using $icons.

Define the icon using the full url of the icon:

Alternatively, you can use a file path that is relative to relative to :

Event creation details
When we create and trigger the event, we need to supply details as well:

Presentation model definition
Presentation models are meant to be very flexible, so as to allow the creation of notification types with specific displays. Unlike event definition and creation, the presentation model is a class on its own, and requires extending it and making the methods specific to the notification case. These are the definitions of the base  class:

Structure of secondary links
The secondary links information allows notifications to specify sub-links to actions that are extending the main primary link for the notification. For example, a notification about some revision edit can have its primary link point to the revision diff page, but also have secondary links pointing for the user page of the user who made the change, or a link to view the page that was changed.

Secondary links also allow API-directed actions ( actions) for actions like or others that require the front-end to request an AJAX request to the API directly from the notification. Further details about dynamic actions are outside the scope of this tutorial.

The general structure of secondary links:

Walkthrough: Creating a new notification type
Let's say we have an extension that keeps a list of users who are interested in new titles created with specific words in them. The extension allows users to add and remove themselves from a watch-list for a certain list of words in a title, and listens to the hook for creating new pages on the wiki to identify relevant pages. When a relevant page is created, the extension code will create an event with the relevant details, and notify the users that are on the list for that combination of words.

This section will demonstrate how to create this new notification type.

Defining the event
We need to make sure our event is defined in the system. This is done by listening to the hook  and defining the event definition:

You can see another example of this in the Thanks extension.

Identify relevant users to notify
The Notifications system will try to notify relevant users, but it can't guess who those are. 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
