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
Získáno z: change 500542: Pro nezrušitelné háčky (většina háčků) vracení true je od MediaWiki 1.22 (v roce 2015) nadbytečné. To bylo provedeno za účelem snížení pravděpodobnosti náhodného selhání, protože jsme zaznamenali několik výpadků a nefunkčních funkcí kvůli tichým selháním, kde např. jedno zpětné volání háčku někde omylem vrátilo non-bool nebo false místo true/void a tím zkratovalo celý systém.

(Vrácení non-true/non-void v MediaWiki Hook je ekvivalentní  a   v událostech JavaScript, likviduje ostatní používající stejnou událost).

Pokud by například háček  vrátil false v MobileFrontend, znamenalo by to, že se vyskakovací okna zastaví, protože jeho zpětné volání již nebude probíhat. Podívejte se na rozdíly níže, za předpokladu, že háček je.

Před MediaWiki 1.22

nebo

MediaWiki 1.22+

Dokumentace
V současné době musí být háčky v jádru MediaWiki zdokumentovány jak v rozhraní háčku (v úložišti zdrojového kódu), tak zde na MediaWiki.org. V některých případech nemusí být jeden z těchto kroků ještě dokončen, takže pokud se háček jeví jako nezdokumentovaný, zkontrolujte oba.

Každý háček poskytovaný MediaWiki Core je definován v rozhraní háčku. Rozhraní háku jsou obvykle umístěna v podjmenném prostoru "Hook" uvnitř jmenného prostoru volajícího. Například,. Seznam háčkových rozhraní můžete najít ve vygenerované dokumentaci PHP MediaWiki.

Chcete-li dokumentovat háček na wiki, použijte MediaWikiHook.

Šablona dokumentu rozhraní háčku

V rozhraních háčku určují komentáře k dokumentu stav, účel, parametry a chování háčku.



Využitelné háčky


Háčky seskupené podle funkce
Některé z těchto háčků lze seskupit do více funkcí.
 * Skupina: Správa článku - Úprava stránky - Zobrazování stránky - Uživatelské rozhraní - Správa souboru - Speciální stránky - Správa uživatele - Protokolování - Šablony zobrazování - API - Import/Export - Rozdíly - Různé



Abecední seznam háčků
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.

Poznámky pod čarou


Související odkazy

 * — specifikace systému háčků
 * Seznam háčkových rozhraní v MediaWiki Core
 * — obsahuje příklady háčků
 * — JavaScript/front-end systém háčků
 * — specifikace systému háčků
 * Seznam háčkových rozhraní v MediaWiki Core
 * — obsahuje příklady háčků
 * — JavaScript/front-end systém háčků