Extension:JsonConfig

Rozšíření JsonConfig umožňuje jiným rozšířením ukládat svá konfigurační data jako JSON blob na wiki stránce.

• JsonConfig můžete použít k ukládání dat několika způsoby:
  • na jedné konfigurační stránce, např. několik nastavení pro vaše rozšíření v Config:MyExtSettings (Config je výchozí jmenný prostor přidružený k rozšíření JsonConfig);
  • v sadě stránek s podobnou strukturou nacházejících se ve vlastním jmenném prostoru, např. IP adresy známých proxy serverů nebo schémata protokolu událostí s názvem "Proxy:Opera", nebo schémata s názvem Schema:AccountCreation
  • použití pouze pro stránky, jejichž názvy odpovídají regulárnímu výrazu, např. Config:Proxy:Opera nebo Config:Opera.proxy. Tím se zabrání zaplňování wiki spoustou jmenných prostorů, jedním pro každý model obsahu.
• Můžete poskytnout třídu obsahu pro validaci dat (nad rámec platného JSON) a normalizaci.
• Můžete poskytnout třídu zobrazení pro přizpůsobení zobrazení HTML.
• Data můžete ukládat:
  • "jeden na wiki", "jeden na cluster" nebo dokonce jeden na nějakou "rodinu" (jiná struktura klíče mezipaměti pro sdílený memcached);
  • ve veřejné nebo soukromé wiki a přístup k nim s použitím přihlašovacích údajů;
  • v samostatném clusteru a provádět vzdálené upozornění při změně.

• Tabulkové datové sady Commons
• Mapové datové sady Commons
• Konfigurace řídicího panelu Dashiki
• Jiné?

• Konfigurace operátorů Wikipedia Zero (viz Extension:ZeroBanner)

• Stáhněte soubor/y a vložte je do adresáře pojmenovaného JsonConfig ve vaší složce extensions/.
  Vývojáři a přispěvatelé kódu by si místo toho měli nainstalovat rozšíření from Git pomocí:

  cdextensions/
  gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/JsonConfig
  

• Na konec vašeho souboru LocalSettings.php přidejte následující kód:

  wfLoadExtension( 'JsonConfig' );
  

• Vyžaduje nastavení v konfiguračním souboru.
• Yes Dokončeno – Přejděte na stránku Special:Version vaší wiki a zkontrolujte, zda bylo rozšíření úspěšně nainstalováno.

Tato proměnná definuje profily pro každý typ konfiguračních stránek. $wgJsonConfigs je asociativní pole polí, kde každé podpole nemá žádný nebo více z následujících parametrů. Ve výchozím nastavení používá JsonConfig řetězcový klíč jako ID modelu, které tento profil představuje, ale v případě, že chcete stejné ID modelu znovu použít ve více než jednom profilu, můžete jej přepsat parametrem model.

Tato proměnná definuje, která vlastní třída obsahu bude zpracovávat které ID modelu. Stejná třída obsahu může zpracovávat více než jedno ID modelu. Všechny třídy obsahu musí být odvozeny z třídy JCContent. Pokud se modelID mapuje na null, pak se ID modelu zpracovává výchozí třída JCContent.

Příklad:

$wgJsonConfigModels['Config.MyExtSettings'] = 'MyExt\MyContentClass';

Pokud implementujete samostatnou třídu pro vykreslování HTML, můžete svůj konfigurační model specifikovat jako pole s další třídou view:

$wgJsonConfigModels['Config.MyExtSettings'] = [
 'class' => 'MyExt\MyContentClass',
 'view' => 'MyExt\MyContentViewClass', // snadnější prodloužit o JCDefaultObjContentView nebo JCDefaultContentView
];

Nejjednodušším případem je jedna konfigurační stránka bez jakéhokoli ověření, uložená lokálně na každé wiki. Stačí přidat tato nastavení do LocalSettings.php

// Model obsahu je JsonConfig.MySettings
// Třída modelu je nastavena na NULL, aby povolila neověřená data.
$wgJsonConfigModels['JsonConfig.MySettings'] = null;
$wgJsonConfigs['JsonConfig.MySettings'] = array(
 'pattern' => '/^MySettings$/', // Název stránky v jmenném prostoru Config
);

Výše uvedené povoluje jmenný prostor "Config" na lokální wiki, ale umožňuje vytvoření pouze stránky Config:MySettings, nikoli žádné jiné stránky v tomto jmenném prostoru. Na stránku můžete ukládat správně formátovaná data JSON.

Pro čtení dat MySettings v PHP použijte objekt TitleValue pro přístup ke stránce a poté si vyžádejte její obsah:

use JsonConfig\JCSingleton;
$tv = new TitleValue( NS_CONFIG, 'MySettings' ); // Klíč databáze
$content = JCSingleton::GetContent( $tv );
if ( $content->isValid() ) {
 $data = $content->getData();
 ...
}

Některé šablony (např. Template:TNT) z projektů Wikimedie vyžadují, aby JsonConfig podporoval jmenný prostor Data na commons za mw.ext.data.get. Pro podporu tohoto případu použití můžete použít následující konfiguraci.

wfLoadExtension( 'JsonConfig' );
$wgJsonConfigEnableLuaSupport = true; // vyžadováno použití JsonConfig v Lua
$wgJsonConfigModels['Tabular.JsonConfig'] = 'JsonConfig\JCTabularContent';
$wgJsonConfigs['Tabular.JsonConfig'] = [ 
 'namespace' => 486, 
 'nsName' => 'Data',
 // Název stránky musí končit na ".tab" a obsahovat alespoň jeden symbol
 'pattern' => '/.\.tab$/',
 'license' => 'CC0-1.0',
 'isLocal' => false,
];
$wgJsonConfigModels['Map.JsonConfig'] = 'JsonConfig\JCMapDataContent';
$wgJsonConfigs['Map.JsonConfig'] = [ 
 'namespace' => 486,
 'nsName' => 'Data',
 // Název stránky musí končit na .map a obsahovat alespoň jeden symbol
 'pattern' => '/.\.map$/',
 'license' => 'CC0-1.0',
 'isLocal' => false,
];
$wgJsonConfigInterwikiPrefix = "commons";
$wgJsonConfigs['Tabular.JsonConfig']['remote'] = [ 
 'url' => 'https://commons.wikimedia.org/w/api.php'
];
$wgJsonConfigs['Map.JsonConfig']['remote'] = [
 'url' => 'https://commons.wikimedia.org/w/api.php'
];

Řekněme, že se rozhodneme ukládat IP adresy důvěryhodných proxy serverů jako stránky Config:Proxy: na Meta-Wiki a sdílet tato data s clusterem.

// Všechny wikiny musí mít tuto konfiguraci:
$wgJsonConfigs['JsonConfig.Proxy'] = [
 'pattern' => '/^Proxy\:./', // vyžadovat alespoň jedno písmeno za ':'
 'isLocal' => false,
];
// Parametr LocalSettings.php pro všechny wikiny kromě Meta-Wiki nastaví tuto URL adresu na koncový bod API Meta-Wiki:
$wgJsonConfigs['JsonConfig.Proxy']['remote'] = 'http://meta.wikimedia.org/w/api.php';
// LocalSettings.php pro Meta-Wiki bude znamenat, že data by měla být uložena tam.
$wgJsonConfigs['JsonConfig.Proxy']['store'] = true;

Pokud chcete místo toho vyhradit samostatný jmenný prostor proxy, parametry se změní na:

$wgJsonConfigs['JsonConfig.Proxy'] = [
 'namespace' => NNN, // NNN je číslo, které byste rezervovali pro jmenný prostor proxy.
 'nsName' => 'Proxy', // Kanonický název jmenného prostoru.
];

Většinou by člověk také chtěl vlastní třídu obsahu s vlastním ověřováním. Stránky JSON jsou zpracovávány třídami obsahu, které jsou odvozeny od třídy JCContent. Třída content je zodpovědná za analýzu a validaci nezpracovaného textu. JCContent neprovádí žádnou validaci kromě parsování JSON, ale můžete se rozhodnout z ní odvodit a přepsat JCContent::validate(). Ještě lepší je odvodit třídu z třídy JCObjContent, která poskytuje řadu validačních primitiv, a přepsat pouze třídu JCObjContent::validateContent().

// Toto by se mělo dělat na všech wikinách, včetně Meta-Wiki
$wgJsonConfigModels['JsonConfig.Proxy'] = 'ProxyExt\ProxyContent';

Pro účely této dokumentace předpokládejme, že stránka s konfigurací proxy serveru popisující servery Opera Mini má tento formát:

{
"enabled":true,
"comment":"See http://... for updates",
"ips":[
'37.228.104.0/21',
...
]
}

Zde je třída obsahu pro ověření těchto dat.

use JsonConfig\JCObjContent;
use JsonConfig\JCValidators;
class ProxyContent extends JCObjContent {
 /**
 * Odvozené třídy musí implementovat tuto metodu, aby mohly provádět vlastní validaci pomocí volání check(...).
 */
 public function validateContent() {
 // 'enabled' - musí být booleovská hodnota, ve výchozím nastavení true.
 // JCValidators::* již zpracovává lokalizované chybové zprávy
 $this->testOptional( 'enabled', true, JCValidators::isBool() );
 // volitelné pole 'comment' typu string
 $this->testOptional( 'comment', '', JCValidators::isString() );
 // 'ips' - musí být seznam platných rozsahů CIDR
 // pole není volitelné, pokud by výchozí hodnota neprošla ověřením
 $this->test( 'ips', self::getIpValidator() );
 }
 private static function getIpValidator() {
 // JCValue $value - hodnota kontrolovaného pole obalená informacemi o stavu.
 // $v->getValue() skutečná zkoumaná hodnota
 // $v->isMissing() pokud hodnota není v datech přítomna
 // $v->defaultUsed() pokud hodnota neexistovala a byla zadána výchozí hodnota
 // array $path - umístění tohoto pole v hierarchii - každá hodnota je buď řetězec, nebo celé číslo
 // JCObjContent $self - tento objekt, užitečný pro přístup k dalším polím přes $self->getField()
 // Můžete upravit hodnotu uloženou uvnitř, nastavit další příznaky nebo nahlásit chybu.
 // pomocí funkce $v->error( $key, $path, ... )
 return function ( JCValue $value, array $path, JCObjContent $self ) {
 $isErr = false;
 $v = $value->getValue();
 if ( is_string( $v ) ) {
 // uživatel zadal jeden řetězec, považovat za neasociované pole
 $v = array( $v );
 } else {
 // ujistěte se, že $v je neasociované pole a všechny jeho hodnoty jsou řetězce
 $isErr = !JCUtils::isList( $v ) || !JCUtils::allValuesAreStrings( $v );
 }
 if ( !$isErr ) {
 // @todo: proveďte zbytek ověření IP adresy a v případě selhání nastavte $isErr na hodnotu true
 }
 // Chybová zpráva může mít tento tvar:
 // Parametr \"1ドル\" musí být pole platných neomezených (ne privátních sítí) bloků IP adres CIDR.
 if ( $isErr ) {
 $value->error( 'my-proxyconfig-err-ips', $path );
 } else {
 $value->setValue( $v );
 }
 };
 }
}

Můžete si také přizpůsobit zobrazení a vytváření stránek na wiki úložiště (ve výše uvedeném příkladu Meta-Wiki). Existují dva způsoby, jak to udělat: uvnitř třídy odvozené od JCContent, nebo prostřednictvím samostatné třídy "view", která je odvozena od JCContentView. Druhý přístup je vhodnější, protože jasně odděluje architekturu a třída zobrazení musí existovat pouze v úložné wiki (např. Meta-Wiki), nikoli na všech wikinách, které data používají.

Chcete-li přepsat výchozí hodnotu ve třídě odvozené z JCContent, přepište konstruktor a nastavte hodnotu $text na novou výchozí hodnotu, pokud byla zadána jako NULL, než ji předáte nadřazenému konstruktoru. Chcete-li přepsat generování HTML, přepište JCContent::getHtml().

Doporučeným způsobem vytvořte třídu zobrazení, která je odvozena od třídy JCContentView nebo od třídy JCDefaultContentView s větším množstvím funkcí. Pro JCContentView budete muset implementovat valueToHtml() a getDefault(). Ve výchozím nastavení je zobrazení implementováno třídou JCDefaultContentView, kterou lze také použít jako přizpůsobitelný základ, pokud potřebujete jen drobné úpravy vzhledu.

// Změna definice modelu oproti výše uvedené - měla by být provedena na všech wikinách, včetně META
$wgJsonConfigModels['JsonConfig.Proxy'] = [ 'class' => 'ProxyExt\ProxyContent' ];
// Přidejte třídu zobrazení - mělo by se to dělat pouze na wiki úložiště (např. META)
$wgJsonConfigModels['JsonConfig.Proxy']['view'] = 'ProxyExt\ProxyView';

class ProxyView extends JsonConfig\JCDefaultObjContentView {
 public function getDefault( $modelId ) {
 return <<<JSON
{
 "comment": "See http://... for updates",
 "ips": [
 "N.N.N.N/NN",...
 ]
}
JSON;
 }
}

• Rozšíření, která používají JsonConfig, by měla přidat své konfigurace do $wgJsonConfigs a $wgJsonConfigModels v hlavním souboru rozšíření.
• Pokud sdílíte konfigurační data mezi více wikinami, zdokumentujte použitý název klíče v $wgJsonConfigs[] a inicializujte sekci 'store' / 'remote' v LocalSettings.php. To je lepší než zavádět řadu globálních proměnných, které duplikují funkcionalitu konfigurace. Viz například konfiguraci rozšíření Graph napříč více wikinami na Wikimediai (ačkoli to používá složité nastavení pro více wikin namísto jednoduchých konfiguračních proměnných).

• Analýza JSON převádí text JSON buď do pole, nebo do objektu
• Vizualizace zobrazuje JSON jako snadno zobrazitelnou tabulku, nikoli jako kód, s dodatečným zvýrazněním. Například pokud hodnota není zadána a je použita výchozí hodnota, zobrazí se šedě, nebo pokud je hodnota stejná jako výchozí, zobrazí se fialově. Například viz toto a toto.
• Editor kódu zjednodušuje úpravy JSON
• Vlastní ověření provádí složité kontroly, jako je kontrola správného formátu hodnoty nebo existence ID uživatele.
• Ukládání do mezipaměti MemCached ukládá objekty JSON blob v memcached pod vlastními klíči a zásadami vypršení platnosti a při uložení je resetuje.
• Podpora označených revizí umožňuje označit konfigurace jako "zkontrolované" před jejich spuštěním do produkčního prostředí
• Lokalizace většiny základních prvků rozhraní byla provedena v mnoha jazycích a snížilo by se překladatelské úsilí, kdyby se většina běžných zpráv prováděla pouze jednou na jednom místě.

Tyto funkce by byly žádoucí pro více než jeden typ konfigurací:

• Validátor schématu - ověřuje se podle JSON Schema, protože většina rozšíření nemusí vyžadovat složitá ověřovací pravidla nebo může chtít kombinovat schéma s dalším ověřováním.
• Vlastní editor - tým Zero uvažoval o implementaci složitějšího editoru, pravděpodobně založeného na schématu JSON.
• Podpora dotazů API - povolí vrácení konfiguračních stránek jako běžných výsledků API ve všech formátech - json/xml/... místo textových objektů blob:

  api.php ? action=query & titles=Config:Proxy:Opera & prop=jsonconfig

• Lokalizace - bylo by dobré mít možnost zobrazit lokalizované popisy pro každý konfigurační klíč

Uložená konfigurační data mohou být často potřebná nějakým externím agentem, jako je JavaScript, robot nebo jiné programy. JavaScript by mohl použít buď JSONP pro přístup k potřebným datům voláním standardního action=query&rvprop=content API, nebo bychom mohli vyvinout službu pro přesměrování, pokud CORS není k dispozici. Autoři rozšíření se mohou rozhodnout přidat vlastní moduly API, které poskytnou informace specifické pro danou doménu. A konečně, parametr rvprop=jcddata Query API by vrátil data JSON jako součást výsledku API, nikoli jako textový objekt blob, který by vrátil parametr rvprop=content.

// NEIMPLEMENTOVÁNO! Používejte běžné API action=query, dokud se nerozhodneme, jak to udělat správně.
varreq={
format:'json',action:'query',
titles:'Proxy:Opera',
prop:'revisions',rvprop:'jcdcontent',indexpageids:'',
};
$.ajax({
url:'//meta.wikipedia.org/w/api.php',
data:req,cache:true,dataType:'jsonp',
success:function(result){/* ošetřovat chyby a varování, zpracovávat obsah */}
});

• Help:Tabular Data

• Stable extensions/cs
• ContentHandler extensions/cs
• Personalization extensions/cs
• GPL licensed extensions/cs
• Extensions in Wikimedia version control/cs
• AlternateEdit extensions/cs
• ApiMain::moduleManager extensions/cs
• ArticleDeleteComplete extensions/cs
• ArticleUndelete extensions/cs
• ArticleViewFooter extensions/cs
• BeforePageDisplay extensions/cs
• CanonicalNamespaces extensions/cs
• CodeEditorGetPageLanguage extensions/cs
• CodeMirrorGetMode extensions/cs
• ContentHandlerDefaultModelFor extensions/cs
• ContentHandlerForModelID extensions/cs
• EditFilterMergedContent extensions/cs
• EditPage::showEditForm:initial extensions/cs
• EditPageCopyrightWarning extensions/cs
• GetContentModels extensions/cs
• LinksUpdateComplete extensions/cs
• LoadExtensionSchemaUpdates extensions/cs
• MovePageIsValidMove extensions/cs
• PageMoveComplete extensions/cs
• PageSaveComplete extensions/cs
• ScribuntoExternalLibraries extensions/cs
• SkinCopyrightFooterMessage extensions/cs
• TitleGetEditNotices extensions/cs
• GetUserPermissionsErrors extensions/cs
• All extensions/cs
• Extensions used on Wikimedia/cs
• Extensions included in Miraheze/cs
• Extensions included in WikiForge/cs

• Extensions with manual MediaWiki version/cs