View source for Manual:Extension registration/cs

<languages />
{{hatnote|1=''extension.json přesměrovává sem. Seznam specifikací naleznete přímo na [[Special:MyLanguage/Manual:Extension.json/Schema|Extension.json/Schema]].''}}
{{MW version|version=1.25|comment=and after|gerrit change=166705}}

'''Registrace rozšíření''' je mechanismus, který používá MediaWiki pro načítání [[Special:MyLanguage/Manual:Extensions|rozšíření]] (''extensions'') a [[Special:MyLanguage/Manual:Skins|vzhledů]] (''skins'').
[[Special:MyLanguage/Manual:Extension.json/Schema|Konfigurační data]] se zapisují do souboru s názvem <code>extension.json</code>, či v případě  grafického vzhledu <code>skin.json</code>, který by měl být umístěn v kořenovém adresáři vašeho rozšíření nebo vzhledu. A ten MediaWiki použije k registraci vašeho rozšíření, či grafického vzhledu (''skinu'').

Pokud jste místo toho hledali dokumentaci k ''instalaci'' rozšíření, [[Special:MyLanguage/Manual:Extensions/Installation and upgrade|podívejte se na tuto příručku]]. 

<span id="Features"></span>
== Funkce ==

<span id="Attributes"></span>
=== Atributy ===

"Atributy" vám umožňují zaregistrovat cokoli, například modul, s jinou příponou.
Například rozšíření VisualEditor (VE) nabízí háček {{phpi|$wgVisualEditorPluginModules}}, který mohou ostatní rozšíření použít k registraci modulu s VE.
Pokud by rozšíření Math registrovalo modul u VE, mělo by ve svém <code>extension.json</code> něco jako následující:
{| class="wikitable"
|-
! manifest version 2
! manifest version 1
|-
| Uzel <code>attributes</code> musí být objekt s názvem rozšíření jako klíčem a objektem párů atribut/hodnota jako hodnotou. Pamatujte, že klíč v podobjektu nesmí obsahovat název rozšíření!

<syntaxhighlight lang="json">
{
	"attributes": {
		"VisualEditor": {
			"PluginModules": [
				"ext.math.visualEditor"
			]
		}
	},
	"manifest_version": 2
}
</syntaxhighlight>
| Provedení verze 1 nemá samostatnou sekci pro <code>attributes</code>:

<syntaxhighlight lang="json">
{
	"VisualEditorPluginModules": [
		"ext.math.visualEditor"
	]
}
</syntaxhighlight>
|}
Když chce VisualEditor získat přístup k tomuto atributu, použije:

<syntaxhighlight lang="php">
ExtensionRegistry::getInstance()->getAttribute( 'VisualEditorPluginModules' );
</syntaxhighlight>


<span id="Requirements_(dependencies)"></span>
=== Požadavky (závislosti) ===
Registrace rozšíření má sekci <code>requires</code> (vyžaduje), která funguje podobně jako sekce <code>require</code> [[Special:MyLanguage/Composer|Composeru]].
Umožňuje vývojáři rozšíření specifikovat několik požadavků na rozšíření, jako je konkrétní verze MediaWiki (nebo vyšší/menší než) nebo jiné rozšíření/vzhled.
Chcete-li například přidat závislost na verzi MediaWiki, která je větší než 1.26.0, můžete do <code>extension.json</code> přidat následující kód: <ref>https://github.com/wikimedia/mediawiki/blob/78091899db2315916502421fdd2972f1d73237b3/docs/extension.schema.json#L273-L282</ref>

<syntaxhighlight lang="json">
{
	"requires": {
		"MediaWiki": ">= 1.26.0"
	}
}
</syntaxhighlight>

Klíč objektu <code>requires</code> je název závislosti (před MediaWiki 1.29.0 byla podporována pouze <code>MediaWiki</code>), hodnota je platné omezení verze (formát je [https://getcomposer.org/doc/articles/versions.md podle volby autora]).

V MediaWiki 1.29.0 a vyšší můžete také přidat závislosti na vzhledech a dalších rozšířeních, jako jsou:

<syntaxhighlight lang="json">
{
	"requires": {
		"MediaWiki": ">= 1.29.0",
		"extensions": {
			"ExampleExtension": "*"
		},
		"skins": {
			"ExampleSkin": "*"
		}
	}
}
</syntaxhighlight>

{{Note|1=<nowiki/>
* Rozšíření a vzhledy uvedené zde, aby fungovaly, musí také používat systém registrace rozšíření popsaný na této stránce.
* Řetězec přidaný k určení přípony nebo vzhledu musí být shodný s řetězcem uvedeným v poli "name" příslušného souboru "extension.json" nebo "skin.json".
* Pro rozšíření využívající [[Special:MyLanguage/Continuous integration|kontinuální integrace]] Wikimedie, je také třeba přidat závislosti do {{git file|project=integration/config |file=zuul/parameter_functions.py}}
}}

V MediaWiki 1.33.0 (?!??) a výše můžete také přidat závislosti na PHP, jako je:

<syntaxhighlight lang="json">
{
	"requires": {
		"MediaWiki": ">= 1.33.0",
		"platform": {
			"php": ">= 7.0.3"
		}
	}
}
</syntaxhighlight>

<span id="Check_if_an_extension_is_loaded_without_actually_requiring_it"></span>
=== Zkontrolujte, zda je rozšíření načteno, aniž by bylo ve skutečnosti vyžadováno ===
Mnoho rozšíření může poskytovat funkce, které fungují pouze v případě, že je načteno i jiné rozšíření, aniž by tuto funkci skutečně potřebovali pro fungování základní funkce rozšíření.
Jako příklad: Pokud je načteno rozšíření B, může rozšíření A poskytovat skutečný WYSIWYG editor, jinak bude používat jednoduchou textovou oblast.
Rozšíření A může těžit z rozšíření B (pokud je načteno), ale ke správnému fungování nevyžaduje, aby bylo načteno.
Za tímto účelem obvykle zkontrolujete, zda je rozšíření načteno, spíše než jej přidáte jako ''tvrdou'' závislost.

Pro implementaci standardizovaného způsobu kontroly, zda je rozšíření načteno nebo ne (bez nutnosti práce navíc v rozšíření, která je v jiném rozšíření měkkou závislostí), lze použít registraci rozšíření.
Implementuje metodu <code>isLoaded</code>, která vrací jednoduchý boolean, pokud je rozšíření načteno nebo ne (aby to fungovalo, musí být rozšíření načteno s registrací rozšíření).
Příklad:

<syntaxhighlight lang="php">
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB' ) ) {
	// používejte pouze v případě, že je načteno rozšíření B
}
</syntaxhighlight>

{{MW version|version=1.32|comment=and after|gerrit change=455752}}
Od [[Special:MyLanguage/MediaWiki 1.32|MediaWiki 1.32]] je také možné zkontrolovat, zda je rozšíření načteno a zda splňuje dané omezení verze:

<syntaxhighlight lang="php">
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB', '>=1.2' ) ) {
	// používejte pouze v případě, že je načteno rozšíření B a má verzi 1.2 nebo vyšší.
}
</syntaxhighlight>

Pokud byste chtěli zkontrolovat, zda je v dřívějších verzích MediaWiki načtena konkrétní verze rozšíření, lze podobné informace extrahovat pomocí metody <code>getAllThings</code>, která vrací informace o kreditu pro všechna načtená rozšíření. Příklad:

<syntaxhighlight lang="php">
$bVersion = ExtensionRegistry::getInstance()->getAllThings()['ExtensionB']['version'] ?? null;
if ( $bVersion !== null && version_compare( $bVersion, '2.1.0', '>=' ) ) {
	// používejte pouze v případě, že je načteno rozšíření B a má číslo verze větší nebo rovné 2.1.0
}
</syntaxhighlight>

Alternativně, pokud rozšíření B definuje speciální konstantu určenou pro tento účel během načítání, je možné zkontrolovat, zda je definována:

<syntaxhighlight lang="php">
if ( defined( 'ExtensionBVersion' ) ) { // You could also check for a version, if the constant holds the version
	// používejte pouze v případě, že je načteno rozšíření B
}
</syntaxhighlight>

Křehčím způsobem, kterému je třeba se vyhnout, je zkontrolovat, zda specifická třída rozšíření B existuje nebo ne, např. pomocí tohoto kódu:

<syntaxhighlight lang="php">
if ( class_exists( 'ExtensionBHooks' ) ) {
	// používejte pouze v případě, že existují třídy rozšíření B
}
</syntaxhighlight>

To může přestat fungovat, pokud přípona existuje v systému souborů, ale není načtena, např. pokud byl pro automatické načítání použit composer.
Pokud byla třída přejmenována nebo přestane existovat (např. protože není balíček public), dojde také k přerušení.

Obecně je upřednostňováno sdílení kódu prostřednictvím komponent pro composer namísto rozšíření. Pokud třídy rozšíření potřebují pouze existovat, ale rozšíření nemusí být konfigurováno ani načteno, pro to, co chcete dělat, je to silný indikátor toho, že by tento kód měl být rozdělen na komponentu composer, na kterou byste se měli spolehnout. namísto.

<span id="Configs_(Your_extension/skins_settings)"></span>
=== Configs (Vaše nastavení rozšíření/vzhledů) ===
{{See also|Special:MyLanguage/Manual:Configuration for developers|label 1=Příručka:Konfigurace pro vývojáře}}
{{See also|Special:MyLanguage/Manual:Extension.json/Schema#config|label 1=Příručka:Extension.json/Schema#config}}
Ve výchozím nastavení <code>extension.json</code> předpokládá, že vaše konfigurační nastavení začíná předponou "wg".

Pokud tomu tak není, můžete předponu přepsat pomocí speciálního klíče:

<syntaxhighlight lang="json">
{
	"config": {
		"_prefix": "eg",
		"MyExtSetting": true
	}
}
</syntaxhighlight>

To by použilo předponu "eg" a nastavilo globální proměnnou {{phpi|$egMyExtSetting}} na hodnotu true.

Počínaje zveřejněním verze 2 poskytuje konfigurační sekce registrace rozšíření mnohem více funkcí a umožňuje vám popsat možnosti konfigurace mnohem podrobněji. Namísto jediného klíče -> úložiště hodnot pro možnosti konfigurace můžete také přidat následující informace.

Obecná struktura <code>config</code> se mírně mění na následující, více objektově orientovanou verzi:

<syntaxhighlight lang="json">
{
	"config_prefix": "eg",
	"config": {
		"MyExtSetting": {
			"value": true,
			"path": false,
			"description": "Popis konfigurace",
			"descriptionmsg": "myextension-config-myextsetting",
			"public": true
		}
	},
	"manifest_version": 2
}
</syntaxhighlight>

==== value ==== <!--protected -->
Hodnota konfigurace se přesunula na toto místo.
Toto je jediný požadovaný klíč pro konfigurační objekt.

==== path ==== 
Booleovská hodnota klíče <code>path</code> identifikuje, zda má být hodnota konfigurační volby interpretována jako cesta souborového systému vzhledem ke kořenu adresáře rozšíření.
Pokud je například hodnota konfigurace <code>myFile.png</code> a <code>path</code> je pravdivá, skutečná hodnota bude <code>/path/to/the/wiki/extensions/MyExtension/myFile.png</code>.

==== description ==== 
Klíč <code>description</code> pro možnost konfigurace může obsahovat nelokalizovaný řetězec, který lze použít k vysvětlení možnosti konfigurace dalším vývojářům nebo uživatelům (správcům systému) vašeho rozšíření.
Může být také použit jako popisný text v sekci parametrů informačního pole rozšíření na stránce popisu rozšíření MediaWiki.org.
Hodnota klíče popisu obvykle není vystavena frontendu wiki, ale podívejte se do přehledu, kde najdete další informace, jak by se tato funkce mohla v budoucnu používat!

==== descriptionmsg ====
Existuje také možnost přidat klíč zprávy interního lokalizačního systému MediaWiki jako popis (<code>descriptionmsg</code>), který bude v budoucnu použit k odhalení popisu v rozhraní instalace MediaWiki.

==== public / private ====
Tato volba je booleovská, jejíž výchozí hodnota je <code>false</code>, což znamená, že konfigurační volba a hodnota jsou označeny jako "private".
Tato hodnota se momentálně nikde nepoužívá, podívejte se do přehledu, kde se o této možnosti dozvíte více.

<span id="Outlook"></span>
==== Výhled ====
{{tracked|T155155}}
Výše uvedené změny jsou také přípravnými kroky pro vylepšenou správu konfigurace v MediaWiki. Výše uvedené změny nám umožňují např. odhalit možnosti konfigurace rozšíření v uživatelském rozhraní MediaWiki. K tomu je zapotřebí zpráva s lokalizovaným popisem (<code>descriptionmsg</code> a <code>description</code>) a indikace, zda má být konfigurační volba (<code>public</code>) veřejná nebo ne.

<span id="Unit_tests_auto-discovery"></span>
=== Automatické zjišťování testů jednotek ===
MediaWiki umožňuje libovolné rozšíření pro [[Special:MyLanguage/Manual:PHP unit testing/Writing unit tests for extensions|registraci testů phpunit]].
Bez registrace rozšíření byste museli zaregistrovat obslužný program pro háček {{ll|Manual:Hooks/UnitTestsList|UnitTestsList}}, který by vypadal asi takto:

<syntaxhighlight lang="php">
public static function onUnitTestsList( array &$paths ) {
	$paths[] = __DIR__ . '/tests/phpunit/';
}
</syntaxhighlight>

(jak je popsáno v příručce). Tento kód však vypadá stejně pro mnoho rozšíření, takže byste to mohli nazvat zbytečnou duplikací kódu.
Pokud vaše rozšíření používá registraci rozšíření a vaše testy phpunit jsou umístěny v podadresáři <code>tests/phpunit/</code> vašeho rozšíření, wraper phpunit MediaWiki automaticky objeví testy jednotek pomocí registrace rozšíření.
Proto již nemusíte háček registrovat a nemusíte specifikovat, že vaše testy jednotek jsou uloženy ve výchozím adresáři.

<span id="Tracking_categories"></span>
=== Kategorie sledování ===
{{see also|Help:Tracking categories|Manual:Extension.json/Schema#TrackingCategories}}
{{MW 1.25|and later}}
Od [[Special:MyLanguage/MediaWiki 1.25|MediaWiki 1.25]] musí být všechny kategorie, které chce rozšíření uvést na [[Special:TrackingCategories]], zaregistrovány v <code>extension.json</code>:

<syntaxhighlight lang="json">
{
	"TrackingCategories": [
		"myextension-tracking-category"
	]
}
</syntaxhighlight>

<code>myextension-tracking-category</code> je [[Special:MyLanguage/Help:System message|systémová zpráva]], která obsahuje název kategorie a je přidána na stránky s <code>Parser::addTrackingCategory()</code>.

<span id="Customizing_registration"></span>
== Přizpůsobení registrace ==
:''Viz [[Special:MyLanguage/Manual:Extension.json/Schema#callback|MPříručka:Extension.json/Schema#callback]].''

<span id="Also_composer.json"></span>
== Také composer.json ==

Pokud má rozšíření nebo vzhled knihovny závislosti, může je mít také soubor <code>composer.json</code>, viz {{ll|Manual:Composer.json best practices}}. Použijte pole <code>load_composer_autoloader</code>, aby MediaWiki používala automatické načítání Composer, když je to vhodné.

Některá pole metadat se překrývají mezi <code>extension.json</code> a <code>composer.json</code> (diskutované v {{task|T89456}}), včetně:
* <code>url</code> a <code>homepage</code>
* <code>license-name</code> a <code>license</code>

<span id="Code_stewardship"></span>
== Správce kódu ==
{{Component|mediawiki-configuration}}

<span id="See_also"></span>
== Související odkazy ==

<span id="Documentation"></span>
=== Dokumentace ===
* {{ll|Manual:Extension.json/Schema}}
** <code>[[phab:diffusion/MW/browse/master/docs/extension.schema.v2.json|docs/extension.schema.v2.json]]</code> je schéma pro <code>extension.json</code> (a skin.json).
* {{ll|Manual:Extension registration/Limitations|2=Známá omezení}}
* {{ll|Manual:Extension registration/Architecture|2=Přehled architektury}}
* {{ll|Manual:Extension registration/Migration|2=Průvodce migrací}} - několik doporučení pro aktualizaci starších rozšíření

===Feedback===
* Hlášení chyb v projektu [[phab:tag/mediawiki-configuration/|MediaWiki-Configuration]].
* [[Requests for comment/Extension registration|RfC]] o implementaci registrace rozšíření

<span id="References"></span>
== Poznámky pod čarou ==
{{reflist}}

[[Category:Extension registration{{#translation:}}]]
[[Category:Extension creation{{#translation:}}]]

{{Extensions}}