Manual:Developing extensions/cs



Každé rozšíření se skládá ze tří částí:


 * 1) Nastavení
 * 2) Provedení
 * 3) Lokalizace

Minimalistická struktura rozšíření bude vypadat takto:


 * MyExtension/extension.json
 * Ukládá instrukce nastavení. Název souboru musí být extension.json. (Před verzí MediaWiki 1.25 byly pokyny k nastavení v souboru  pojmenovaném podle přípony. Mnoho rozšíření má v tomto souboru PHP stále podložky zpětné kompatibility.)


 * MyExtension/includes/ (or MyExtension/src/)
 * Ukládá kód provedení PHP pro rozšíření.


 * MyExtension/resources/ (or MyExtension/modules/)
 * Ukládá prostředky na straně klienta, jako je JavaScript, CSS a LESS pro rozšíření.


 * MyExtension/i18n/*.json
 * Pro uložení souborů s překlady, pro lokalizaci vašeho rozšíření.

Při vývoji rozšíření nahraďte MyExtension výše názvem svého rozšíření. Použijte názvy UpperCamelCase pro jeho adresář a soubor(y) PHP. Toto je obecná konvence pojmenování souborů. (Při zakládání nového repozitáře můžete začít úpravou rozšíření .)

Nastavení
Vaším cílem při psaní části nastavení je co nejvíce usnadnit instalaci rozšíření, takže uživatelé musí do LocalSettings.php přidat pouze tento řádek:

Pokud chcete, aby bylo vaše rozšíření uživatelsky konfigurovatelné, musíte definovat a zdokumentovat některé konfigurační parametry a nastavení vašich uživatelů by mělo vypadat nějak takto:

K dosažení této jednoduchosti musí váš instalační soubor provést řadu úkolů (podrobně popsaných v následujících částech):


 * zaregistrovat jakýkoli obslužný program médií, funkci analyzátoru, speciální stránku, vlastní značku XML a proměnnou používané vaším rozšířením.
 * definovat a/nebo ověřit jakékoli konfigurační proměnné, které jste definovali pro své rozšíření.
 * připravit třídy používané vaším rozšířením pro automatické načítání
 * určit, které části vašeho nastavení by měly být provedeny okamžitě a co je třeba odložit, dokud nebude inicializováno a nakonfigurováno jádro MediaWiki
 * definovat jakékoli další háčky potřebné pro vaše rozšíření
 * vytvořit nebo zkontrolovat jakékoli nové databázové tabulky požadované vaším rozšířením.
 * nastavit lokalizaci pro vaše rozšíření



Registrace funkcí na MediaWiki
MediaWiki uvádí všechna rozšíření, která byla nainstalována na stránce. Všechna rozšíření nainstalovaná na této wiki můžete například vidět na Special:Version.

Chcete-li to provést, přidejte podrobnosti rozšíření na extension.json. Záznam bude vypadat nějak takto:

Mnoho polí je volitelných, ale přesto je dobré je vyplnit. odkazuje na verzi schématu, do které je zapsán soubor. Dostupné verze jsou 1 a 2. Dokumentaci k této funkci najdete zde. Pokud nepotřebujete podporovat starší verzi MediaWiki, vyberte nejnovější verzi.

Kromě výše uvedené registrace musíte svou funkci také "zaháčkovat" do MediaWiki. Výše uvedené pouze nastaví stránku Special:Version. Způsob, jakým to uděláte, závisí na typu vašeho rozšíření. Podrobnosti naleznete v dokumentaci pro každý typ rozšíření:



Konfigurace uživatele vašeho rozšíření
Pokud chcete, aby váš uživatel mohl konfigurovat vaše rozšíření, budete muset zadat jednu nebo více konfiguračních proměnných. Je dobré dát těmto proměnným jedinečný název. Měli by také dodržovat konvence pro názvy MediaWiki (např. globální proměnné by měly začínat $wg).

Pokud se například vaše rozšíření jmenuje "MyExtension", možná budete chtít pojmenovat všechny konfigurační proměnné tak, aby začínaly. Je důležité, aby žádné jádro MediaWiki nezačínalo své proměnné tímto způsobem a vy jste odvedli rozumnou práci, abyste zjistili, že žádné z publikovaných rozšíření nezačíná své proměnné tímto způsobem. Uživatelé nebudou ochotni volit mezi vaším rozšířením a některými dalšími rozšířeními, protože jste zvolili překrývající se názvy proměnných.

Je také dobré zahrnout do poznámek k instalaci rozsáhlou dokumentaci všech konfiguračních proměnných.

Zde je příklad boiler plate, kterou lze použít pro začátek:

Všimněte si, že po volání  globální proměnná   neexistuje. Pokud proměnnou nastavíte např. v, pak se výchozí hodnota uvedená v extension.json nepoužije. If you set the variable, e.g. in  then the default value given in extension.json will not be used.

Další podrobnosti o tom, jak používat globální proměnnou uvnitř vlastních rozšíření, naleznete v.



Příprava kurzů pro automatické načítání
Pokud se rozhodnete pro implementaci svého rozšíření používat třídy, MediaWiki poskytuje zjednodušený mechanismus, který pomáhá PHP najít zdrojový soubor, kde se nachází vaše třída. Ve většině případů by to mělo eliminovat potřebu psát vlastní metodu.

Chcete-li použít mechanismus automatického načítání MediaWiki, přidejte položky do pole. Klíčem každé položky je název třídy. Hodnota je soubor, ve kterém je uložena definice třídy. U jednoduchého rozšíření jedné třídy má třída obvykle stejný název jako rozšíření, takže vaše sekce automatického načítání může vypadat takto (rozšíření se jmenuje MyExtension):

Název souboru je relativní k adresáři, ve kterém je soubor extension.json.

U složitějších rozšíření je třeba zvážit jmenné prostory. Podrobnosti viz Příručka:Extension.json/Schema#AutoloadNamespaces.



Definování dalších háčků
Podívejte se na stránku.



Přidávání databázových tabulek
Ujistěte se, že rozšíření nemění základní databázové tabulky. Místo toho by rozšíření mělo vytvořit nové tabulky s cizími klíči k příslušným tabulkám MW.

Pokud vaše rozšíření potřebuje přidat vlastní databázové tabulky, použijte háček. Další informace o použití naleznete na stránce s příručkou.



Nastavit lokalizaci
Více vám řekneː
 * Lokalizace (souhrn)



Přidat protokoly
V rámci MediaWiki se zaznamenávají veškeré akce uživatelů realizované v rámci wiki, neboť cílem je spolupráce a transparentnost. Podívejte se na stránku jak se to dělá.



Zpracování závislostí
Předpokládejme, že rozšíření vyžaduje přítomnost dalšího rozšíření, například proto, že mají být použity funkce nebo databázové tabulky a v případě neexistence je třeba se vyhnout chybovým hlášením.

Například rozšíření vyžaduje přítomnost rozšíření  pro určité funkce.

Jedním ze způsobů, jak to určit, by bylo použití klíče  v extension.json.

Jinak pár nápadů, jak to vyřešit:

To by mělo fungovat alespoň od 1.23 do 1.35.

Lokalizace
Pokud chcete, aby bylo vaše rozšíření používáno na wiki, které mají vícejazyčnou čtenářskou obec, budete muset do svého rozšíření přidat podporu lokalizace.



Ukládat zprávy v &lt;language-key>.json
Uložte definice zpráv do lokalizačního souboru JSON, jednu pro každý jazykový klíč, do kterého je vaše rozšíření přeloženo. Zprávy se ukládají pomocí message key a zprávy samotné pomocí standardního formátu JSON. Každé ID zprávy by mělo být malé a může neobsahovat mezery. Každý klíč by měl začínat malým názvem rozšíření. Příklad najdete v rozšíření MobileFrontend. Zde je příklad minimálního souboru JSON (v tomto případě en.json):

en.json



Dokumentaci zpráv uložte do souboru qqq.json
Dokumentace ke klíčům zpráv může být uložena v souboru JSON pro pseudojazyk s kódem qqq. Dokumentace k výše uvedenému příkladu může být:

qqq.json:



Načtěte lokalizační soubor
V souboru extension.json definujte umístění souborů zpráv (např. v adresáři i18n/):



Použijte wfMessage v PHP
V kódu nastavení a implementace nahraďte každé doslovné použití zprávy voláním. Ve třídách, které implementují (stejně jako některé další, jako jsou podtřídy SpecialPage), můžete místo toho použít. Příklad:



Použijte mw.message v JavaScriptu
V JavaScriptu je možné používat i funkce i18n. Podrobnosti najdete na.



Typy rozšíření
Rozšíření lze kategorizovat na základě technik programování použitých k dosažení jejich účinku. Většina složitých rozšíření bude používat více než jednu z těchto technik:


 * Podtřída: MediaWiki očekává, že určité druhy rozšíření budou implementovány jako podtřídy základní třídy poskytované MediaWiki:
 *  – Podtřídy třídy se používají k vytváření stránek, jejichž obsah je dynamicky generován pomocí kombinace aktuálního stavu systému, vstupních parametrů uživatele a databázových dotazů. Lze generovat zprávy i formuláře pro zadávání dat. Používají se jak pro reportovací, tak pro administrativní účely.
 *  – Vzhledy mění vzhled a dojem z MediaWiki změnou kódu, který zobrazuje stránky podtřídou třídy MediaWiki.
 *  – Technika pro vkládání vlastního kódu PHP do klíčových bodů zpracování MediaWiki. Jsou široce používány analyzátorem MediaWiki, jeho lokalizačním jádrem, systémem správy rozšíření a systémem údržby stránek.
 *  – XML značky stylu, které jsou spojeny s funkcí php, která vydává HTML kód. Nemusíte se omezovat na formátování textu uvnitř značek. Nemusíte to ani zobrazovat. Mnoho rozšíření značek používá text jako parametry, které řídí generování HTML, které vkládá objekty Google, formuláře pro zadávání dat, kanály RSS, úryvky z vybraných článků wiki.
 *  – Technika mapování různých textových řetězců wiki na jediné id, které je spojeno s funkcí. Tuto techniku používají jak proměnné, tak funkce parseru. Veškerý text namapovaný na toto id bude nahrazen návratovou hodnotou funkce. Mapování mezi textovými řetězci a id je uloženo v poli $magicWords. Interpretace id je poněkud složitý proces – více informací najdete na stránce.
 *  – Proměnné jsou něco jako nesprávné pojmenování. Jsou to kousky wikitextu, které vypadají jako šablony, ale nemají žádné parametry a byly jim přiřazeny pevně zakódované hodnoty. Standardní značky wiki jako  nebo   jsou příklady proměnných. Své jméno získávají ze zdroje své hodnoty: Proměnná php nebo něco, co by bylo možné přiřadit k proměnné, např. řetězec, číslo, výraz nebo návratová hodnota funkce.
 *  – .  Podobně jako u rozšíření značek zpracovávají funkce analyzátoru argumenty a vrací hodnotu. Na rozdíl od rozšíření značek je výsledkem funkcí analyzátoru wikitext.
 *  – do api|action API MediaWiki můžete přidat vlastní moduly, které mohou být vyvolány JavaScriptem, roboty nebo klienty třetích stran.
 *  – Pokud potřebujete ukládat data v jiných formátech než wikitext, JSON atd., můžete vytvořit nový.



Podpora dalších základních verzí
Existují dvě rozšířené konvence pro podporu starších verzí jádra MediaWiki:


 * Master: Hlavní větev rozšíření je kompatibilní s co největším počtem starých verzí jádra. To má za následek zátěž na údržbu (hacky se zpětnou kompatibilitou je třeba udržovat po dlouhou dobu a změny rozšíření je třeba testovat na několika verzích MediaWiki), ale weby se starými verzemi MediaWiki těží z funkcí, které byly nedávno přidány do rozšíření.
 * Uvolněné větve: Uvolněné větve nástavby jsou kompatibilní s odpovídajícími větvemi jádra, např. stránky používající MediaWiki musí používat  větev rozšíření. (U rozšíření hostovaných na gerrit jsou tyto větve automaticky vytvořeny, když jsou vydány nové verze MediaWiki.) Výsledkem je čistší kód a rychlejší vývoj, ale uživatelé na starých základních verzích nemají prospěch z oprav chyb a nových funkcí, pokud nejsou backported ručně.

Správci rozšíření by měli pomocí parametru  šablony Extension deklarovat, jakou konvenci dodržují.

Publikování
Chcete-li autokategorizovat a standardizovat dokumentaci vašeho stávajícího rozšíření, přečtěte si prosím. Chcete-li přidat nové rozšíření do této Wiki:



Nasazení a registrace
Pokud máte v úmyslu své rozšíření nasadit na stránky Wikimedie (včetně případně Wikipedie), je zaručena další kontrola z hlediska výkonu a zabezpečení. Konzultujte.

Pokud vaše rozšíření přidává jmenné prostory, možná budete chtít zaregistrovat jeho výchozí jmenné prostory. Podobně, pokud přidá databázové tabulky nebo pole, možná je budete chtít zaregistrovat v.

Uvědomte si prosím, že kontrola a nasazení nových rozšíření na stránkách Wikimedie může být extrémně pomalé a v některých případech trvalo více než dva roky.

<span id="Help_documentation">

Dokumentace nápovědy
Měli byste poskytnout dokumentaci nápovědy k veřejné doméně pro funkce poskytované vaším rozšířením. je dobrým příkladem. Měli byste uživatelům poskytnout odkaz na dokumentaci prostřednictvím funkce.

<span id="Providing_support_/_collaboration">

Poskytování podpory / spolupráce
Vývojáři rozšíření by si měli otevřít účet na Wikimedii a požádat o nový projekt pro rozšíření. To poskytuje veřejné místo, kde mohou uživatelé odesílat problémy a návrhy, a vy můžete spolupracovat s uživateli a dalšími vývojáři na třídění chyb a plánování funkcí vašeho rozšíření.

<span id="See_also">

Související odkazy

 * – implementuje některé ukázkové funkce s rozsáhlou inline dokumentací
 * – fungující standardní rozšíření, užitečné jako výchozí bod pro vaše vlastní rozšíření
 * Přečtěte si rozšíření Příklad, založte svůj vlastní kód na rozšíření BoilerPlate.
 * cookiecutter-mediawiki-extension – šablonu cookiecutter, která generuje standardní rozšíření (s proměnnými atd.)
 * Umožňuje vám rychle začít s vaším vlastním rozšířením.
 * Může také vygenerovat rozšíření BoilerPlate.
 * - zkopírovat z nich konkrétní kód
 * – vysvětluje, jak může vaše rozšíření poskytovat klientům rozhraní API
 * Doporučené postupy pro rozšíření
 * Doporučené postupy pro rozšíření
 * Doporučené postupy pro rozšíření
 * Doporučené postupy pro rozšíření