Manual:Hooks/cs



Háčky umožňují spuštění vlastního kódu, když dojde k nějaké definované události (jako je uložení stránky nebo přihlášení uživatele). Například následující fragment kódu spustí volání funkce při každém spuštění háčku   a předá mu argumenty funkce specifické pro.

Háčky lze zaregistrovat namapováním názvu háčku na zpětné volání v souboru rozšíření:

MediaWiki poskytuje mnoho háčků podobných tomuto k rozšíření funkčnosti softwaru MediaWiki. Přiřazení funkce (známé jako obslužný program háčku) v háčku způsobí, že tato funkce bude volána v příslušném bodě hlavního kódu MediaWiki, aby se provedly jakékoli další úkoly, o kterých si vývojář myslí, že by byly v tomto okamžiku užitečné. Každému háčku může být přiřazeno více obslužných rutin, v takovém případě bude volat funkce v pořadí, v jakém jsou přiřazeny, s případnými úpravami provedenými jednou funkcí, která se přenese na následující funkce v řetězci.

Přiřaďte funkce háčkům na konci nebo ve vašem vlastním příponovém souboru v rozsahu souboru (ne ve funkci  nebo háčku ). U rozšíření platí, že pokud je chování funkce zavěšení podmíněno nastavením v LocalSettings.php, mělo by být přiřazeno zavěšení a funkce by se měla předčasně ukončit, pokud podmínka nebyla splněna.

Můžete si také vytvořit nové háčky ve svém vlastním prodloužení. Registruje se v extension.json stejným způsobem, jako kdybyste registrovali vestavěný háček MediaWiki pro použití ve vašem rozšíření. Poté můžete svůj háček spustit v rámci svého rozšíření zavoláním. Nakonec je nezapomeňte přidat ke.

Pozadí
Háček je spuštěn voláním na HookContainer::run, obvykle pomocí metody v HookRunner. HookContainer najde ovladače háčku, které se mají spustit, a zavolá je s parametry danými HookContainer::run. Ovladače háčků jsou registrovány prostřednictvím.

Více na stránce.

V tomto příkladu z funkce  v, doPurge volá HookRunner::onArticlePurge ke spuštění háčku  a předá   jako argument:

volá mnoho háčků, ale může také volat háčky.



Psaní handleru
Obsluha háčku je funkce, kterou zaregistrujete a která bude volána při každém spuštění příslušného háčku.

Pro rozšíření zaregistrujte své ovladače háčků v :

Manipulátory háčků lze také zaregistrovat prostřednictvím globálního pole. Nejčastěji se to používá pro přizpůsobení specifické pro web na nebo ve starších rozšířeních, která jsou starší než. Následují platné způsoby, jak definovat obslužný program háčku pro háček EventName se dvěma předávanými parametry:

Všimněte si, že když je objekt přiřazen a neurčíte metodu, zavolá se metoda "onEventName". Například "onArticleSave", "onUserLogin" atd.

Volitelné údaje jsou užitečné, pokud chcete použít stejnou funkci nebo objekt pro různé účely. Například:

Tento kód by vedl k tomu, že  se při uložení stránky spustí dvakrát: Jednou pro 'TimStarling' a jednou pro 'brion'.



Obslužná rutina háčku vrací hodnoty
Obslužné rutiny háčků mohou vrátit jednu ze tří možných hodnot:


 * (žádná návratová hodnota nebo null) – obslužná rutina háčku úspěšně fungovala. (Před MediaWiki 1.23 bylo vyžadováno vrácení .)
 * "nějaký řetězec" - došlo k chybě. Zpracování by se mělo zastavit a chyba by se měla zobrazit uživateli
 * - obslužná rutina háčku provedla veškerou potřebnou práci nebo nahradila běžnou manipulaci. To zabrání spuštění dalších obslužných rutin a v některých případech říká volající funkci, aby vynechala normální zpracování.

Vrácení false má menší smysl pro háčky, které se spouštějí po dokončení akce. V těchto případech je vrácená hodnota často ignorována.

Handling hooks in MediaWiki 1.35 and later
MediaWiki 1.35 introduces the HookHandlers system. This includes per-hook interfaces for improved static validation and discovery of parameter documentation. It also enables dependency injection by introducing an intermediary class instance that accepts a number of specified services (instead of static callbacks that explicitly access services from global state).

The approach from MediaWiki 1.34 and earlier, of registering hook handlers directly as static methods, remains supported and is not deprecated. Extension authors may opt-in to the new system are welcome to do so. To learn more, see the MediaWiki core: Hook specification and the announcement on wikitech-l.

Changes to hook names

Prior to MediaWiki 1.35, hooks sometimes included characters that could not be used in a class or method name, such as colons and dashes. With the introduction of per-hook interfaces, the canonical names of these hooks have been changed to use underscores instead. For example, the interface for ApiFeedContributions::feedItem is. Hook handlers that are registered with the old names remain supported.

Registering hooks using HookHandlers

To adopt the new system, change your Hooks class to have regular methods instead of static methods and to be constructible. This class is then registered once, via the HookHandlers attribute in extension.json, using the  option as part of an ObjectFactory description where you can use the   option.

For example, to register the BeforePageDisplay hook:

Handling hooks using interfaces

To use hook interfaces, extensions should define a Hooks class in their namespace and implement one or more hook interfaces. Hook interfaces are named with the hook name followed by the word "Hook".

Convert an extension to the new hook system:

Follow these steps for each hook handling method:
 * identify the hook handler interface, and make the Hooks class implement this interface.
 * update the method name and signature to be exactly the same as in the interface.
 * change the "Hooks" section of extension.json to refer to the handler you specified in the "HookHandlers" section.

The process was demonstrated at the Wikimedia Hackathon 2021:
 * Example patch for an extension
 * Recording on YouTube



Srovnání chování háčků před a po realizaci změn u MediaWiki 1.22
Extracted from: change 500542: for non-abortable hooks (most hooks) returning true has been redundant since MediaWiki 1.22 (in 2015). This was done to reduce chances of accidental failure because we had experienced several outages and broken features due to silent failures where e.g. one hook callback somewhere accidentally returned a non-bool or false instead of true/void and thus short-circuits the whole system.

(Returning non-true/non-void in a MediaWiki Hook is equivalent to  and   in JavaScript events, it kills other listeners for the same event).

For example, if  hook were to return false in MobileFrontend, it would mean Popups stops because its callback would no longer run. See differences below, assuming the hook.

 Before MediaWiki 1.22 

or

MediaWiki 1.22+

Dokumentace
Currently, hooks in MediaWiki core have to be documented both in hook interface (in the source code repository) and here on MediaWiki.org. In some cases, one of these steps may not yet have been completed, so if a hook appears undocumented, check both.

Each hook provided by MediaWiki Core is defined in a hook interface. Typically, hook interfaces are located in a "Hook" sub-namespace inside the caller namespace. For example,. You can find a list of hook interfaces in the generated MediaWiki PHP documentation.

To document a hook on-wiki, use MediaWikiHook.

 Hook interface doc template 

In hook interfaces, doc comments specify the status, purpose, parameters, and behavior of the hook.



Hooks grouped by function
Some of these hooks can be grouped into multiple functions.
 * Sections: Article Management  -  Edit Page  -  Page Rendering  -  User Interface  -  File Management  -  Special Pages  -  User Management  -  Logging  -  Skinning Templates  -  API  -  Import/Export  -  Diffs  -  Miscellaneous

Alphabetical list of hooks
Pro kompletní seznam všech háčků se podívejte seznam stránek v příslušné, na nich jsou informace mnohem aktuálnější než zde.

Viz též

 * — specification of the hooks system
 * List of hook interfaces in MediaWiki Core
 * — contains examples of hooks
 * — the JavaScript/front-end system of hooks
 * — specification of the hooks system
 * List of hook interfaces in MediaWiki Core
 * — contains examples of hooks
 * — the JavaScript/front-end system of hooks