Jump to content

Extension:JsonConfig

Sorun izleyicisi: #JsonConfig
From mediawiki.org
This page is a translated version of the page Extension:JsonConfig and the translation is 98% complete.
Languages:
MediaWiki manüel uzantıları
JsonConfig
Sürüm durumu: kararlı
Uygulama ContentHandler , Vikim
Açıklama Viki tabanlı bir JSON yapılandırma sistemi sağlar
Yazar(lar) Yuri Astrakhan (yurikmesaj)
En son sürüm 1.1.1
Uyumluluk politikası MediaWiki ile birlikte anlık görüntüler yayımlanır. Master geriye dönük olarak uyumlu değil.
MediaWiki 1.38+
Veritabanı değişiklikleri Hayır
Lisans GNU Genel Kamu Lisansı 2.0 veya üstü
İndir
Uzantıyı indir
Git [?]:

RFC
Parametreler

  • $wgJsonConfigs
  • $wgJsonConfigModels
Kullanılan kancalar
Quarterly downloads 239 (Ranked 23rd)
Public wikis using 897 (Ranked 264th)
Translatewiki.net adresinde mevcutsa, JsonConfig uzantısını çevirin
Sorunlar Açık görevler · Hata bildir

JsonConfig uzantısı, diğer uzantıların yapılandırma verilerini bir viki sayfasında JSON blobu olarak depolamasına izin verir.

Mevcut özellikler ve kullanım modelleri

Example JSON visualization rendered by the JsonConfig extension
  • Verileri birkaç şekilde depolamak için JsonConfig'i kullanabilirsiniz:
    • tek bir yapılandırma sayfasında, ör. Config içinde uzantınız için bir dizi ayar: MyExtSettings (Config, JsonConfig uzantısıyla ilişkili varsayılan ad alanıdır);
    • kendi ad alanlarında bulunan benzer yapıya sahip bir dizi sayfada, ör. bilinen proxy'lerin IP adresleri veya "Proxy:Opera" adlı olay günlüğü şemaları veya Schema:AccountCreation adlı şemalar
    • yalnızca başlıkları bir normal ifade kalıbıyla eşleşen sayfalar için kullanma, ör. Config:Proxy:Opera veya Config:Opera.proxy. Bu, her içerik modeli için bir tane olmak üzere çok sayıda ad alanı içeren bir vikiyi doldurmaktan kaçınır.
  • Veri doğrulama (geçerli JSON dışında) ve normalleştirme yapmak için bir içerik sınıfı sağlayabilirsiniz.
  • HTML görünümünü özelleştirmek için bir görünüm sınıfı sağlayabilirsiniz.
  • Verileri saklayabilirsiniz:
    • "one-per-wiki", "one-per-cluster", hatta her "family" için bir tane (paylaşılan memcached için önbellek anahtarının farklı yapısı);
    • genel veya özel bir vikide ve kimlik bilgileriyle erişilir;
    • ayrı bir kümede ve değiştirildiğinde uzaktan bildirim yapın.

Viki üzerinde kullanım

Şuan ki

  • Commons tablo veri kümeleri
  • Commons harita veri kümeleri
  • Dashiki gösterge tablosu yapılandırmaları
  • Diğerleri?

Geçmiş

Kurulum

  • Dosyaları indirin ve extensions/ klasörünüzdeki JsonConfig adlı dizine yerleştirin.
    Developers and code contributors should install the extension from Git instead, using:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/JsonConfig
  • LocalSettings.php dosyanızın altına aşağıdaki kodu ekleyin: 
    wfLoadExtension( 'JsonConfig' );
  • Gerektiği gibi yapılandırın.
  • Yes Yapıldı – Uzantının başarıyla yüklendiğini doğrulamak için vikinizde Special:Version seçeneğine gidin.

Yapılandırma

$wgJsonConfigs

Bu değişken, her tür yapılandırma sayfası için profilleri tanımlar. $wgJsonConfigs, her bir alt dizinin aşağıdaki parametrelere sıfır veya daha fazlasına sahip olduğu ilişkilendirilebilir bir dizi dizisidir. Varsayılan olarak, JsonConfig dize anahtarını bu profilin temsil ettiği model kimliği olarak kullanır, ancak aynı model kimliğini birden fazla profilde yeniden kullanmak istemeniz durumunda bunu model parametresiyle geçersiz kılabilirsiniz.

parametre tür varsayılan açıklama
model string ($wgJsonConfigs anahtarında) Yeni bir sayfa oluştururken kullanılacak model kimliği. Hiçbiri belirtilmezse, bu profilin dizi anahtarı model kimliği olur. Bu değer null olarak ayarlanırsa, yerleşik modül kimliği JsonConfig kullanılacaktır. Model kimliği, null veya 'JsonConfig' dışında $wgJsonConfigModels içinde de listelenmelidir.
namespace int NS_CONFIG (482) Bu yapılandırmaların yer alacağı ad alanı veya varsayılan olarak 'Config:'
nsName string/false Varsayılan olmayan (NS_CONFIG 482 değil) ad alanı için, buna kurallı (İngilizce) bir ad atar. Birden fazla $wgJsonConfigs dizisi aynı ad alanını kullanıyorsa, adı yalnızca bir kez ayarlayın. Bulunmazsa, bir uyarı verilir ve ad alanı otomatik olarak "ConfigNNN" adını alır. Bu yapılandırmanın yerel olarak depolanmaması durumunda, nsName yerel bildirim olmadan uzak ad alanı olarak kullanılacaktır.

Ad alanını diğer, JsonConfig içerikli olmayan sayfalar ile paylaşmak istiyorsanız, bu değeri false olarak ayarlayın.

nsTalk string nsName+_talk Varsayılan olmayan ad alanları için, tartışma sayfalarına kanonik (İngilizce) bir ad atar
pattern string (all) Verilen ad alanındaki sayfa başlığıyla eşleşen düzenli ifade. Boşsa, yapılandırma ad alanındaki tüm sayfalara uygulanır. Eski "alt boşluk" davranışını eşleştirmek için isSubspace=true için ^/^ad:./ kalıbını ve isSubspace=false için /^ad$/ kalıbını kullanın.
isLocal bool true true ise, bu yapılandırma küme içinde paylaşılmayacak, bunun yerine her vikinin yerel bir yapılandırmasını olacaktır. false ise, bu yapılandırmanın birden fazla viki arasında paylaşılması amaçlanmıştır ve bu özel vikinin onu yerel olarak depolaması için "store" alanını ayarlayın.
Bu işaret, önbelleğe alma anahtarını etkiler, bu nedenle, bu ayar false ise memcached'de aynı ada sahip bir yapılandırma sayfası paylaşılır, ancak true ise viki başına benzersiz olacaktır.
cacheExp int 24*60*60 Değer ne kadar süreyle (saniye cinsinden) memcached'de önbelleğe alınmalıdır
cacheKey string Değer ayarlanmışsa, bu dizeyi önbelleğe alma anahtarına ekleyin. Önceki önbelleğe alınmış değerleri geçersiz kılmak için cacheKey kullanın, ör. önbelleğe alınan değerleri değiştirecek uyumsuz bir değişiklik yaparken ve geri dönmeniz gerekebileceğinden endişelenirsiniz. Bu anahtar, aynı ailedeki tüm dil vikilerinin aynı önbelleğe alınmış değeri paylaşırken aynı sayfada ancak farklı vikilerde saklanmasına izin vermek için de kullanılabilir. Örneğin, Vikipedi "wp" kullanabilir ve Vikisöz "wq" kullanabilir.
flaggedRevs bool false true ise, Flagged Revisions uzantısı ile doğrulanan en son revizyonu almaya çalışacak, null ise, işaretli revizyon kontrol edilecek ve varsa kullanılacaktır. false ise, her zaman en son revizyonu kullanır.
remote array Yapılandırmaya başka bir vikiden nasıl erişileceğini açıklayan parametrelere sahip bir nesne. 'store' ayarlanmamışsa ve isLocal, false ise mevcut olmalıdır.
  ‑ url string Yalnızca bu yapılandırma profili için uzak vikiden yapılandırma almak için varsayılan olmayan API uç noktası. Belirtilmezse, $wgJsonConfigApiUri değerini kullanır.
  ‑ username string Verilirse, uzak yapılandırma depolamasının kimliğini doğrulamak için kullanılacaktır.
  ‑ password string username sayfasına bakın.
store array Geçerli vikinin bu yapılandırma verilerini gerçekten barındırmasını sağlamak için bu değeri true veya bir dizi olarak ayarlayın. Bu değer, eksikse ve isLocal, true ise otomatik olarak doldurulur.
  ‑ cacheNewValue bool true Yapılandırma değiştiğinde, önbellek nasıl değişmelidir. false ise, önbelleğe alınan değeri siler ve diğer vikileri yeniden istemeye zorlar. true, yeni değeri önbelleğe ayarlar. Bu yapılandırmayı kullanan viki ve depolayan vikiler aynı önbelleği paylaşıyorsa, bu çoğunlukla yararlıdır. false olması durumunda, eğer tüketici viki yeni değeri çok hızlı talep ederse, onu muhtemelen eski bir köle DB'den alabilir.
  ‑ notifyUrl string İsteğe bağlı olarak, yapılandırma değiştiğinde çağrılacak uzak API URL'sini belirtin.
  ‑ notifyUsername string notifyUrl ile kullanmak için isteğe bağlı kullanıcı adı
  ‑ notifyPassword string notifyUrl ile kullanmak için isteğe bağlı parola

$wgJsonConfigModels

Bu değişken, hangi özel içerik sınıfının hangi Model kimliğini işleyeceğini tanımlar. Aynı içerik sınıfı tarafından birden fazla Model Kimliği işlenebilir. Tüm içerik sınıfları JCContent sınıfından türetilmelidir; model kimliği null ile eşleşirse, varsayılan JCContent sınıfı model kimliğini işler.

Örnek: 

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

HTML oluşturma için ayrı bir sınıf uygularsanız, yapılandırma modelinizi fazladan view sınıfı olan bir dizi olarak belirtebilirsiniz: 

$wgJsonConfigModels['Config.MyExtSettings'] = [
    'class' => 'MyExt\MyContentClass',
    'view'  => 'MyExt\MyContentViewClass', // easier to extend JCDefaultObjContentView or JCDefaultContentView
];

Örnekler

1.0.0 sürümünden önce, JsonConfig hangi sayfaların verilen içerik modeline ait olduğunu özelleştirmek için name ve isSubspace değerlerini kullanıyordu. Her ikisi de 1.0.0 sürümünde kaldırıldı ve normal ifadeyi kabul eden pattern parametresiyle değiştirildi. Desenlerinizi ^ ve $ sembolleriyle çevrelediğinizden ve eğik çizgiler (PHP stili) eklediğinizden emin olun

Hello World

En basit durum, her vikide yerel olarak depolanan, herhangi bir doğrulama olmaksızın tek bir yapılandırma sayfasıdır. Bu ayarları LocalSettings.php ile eklemeniz yeterli 

// Content model is 'JsonConfig.MySettings'
// Model class is set to NULL to allow non-validated data
$wgJsonConfigModels['JsonConfig.MySettings'] = null;

$wgJsonConfigs['JsonConfig.MySettings'] = array(
  'pattern' => '/^MySettings$/', // Page name in Config namespace
);

Yukarıdakiler yerel vikide "Config" ad alanını etkinleştirir, ancak yalnızca "Config:MySettings" sayfasının oluşturulmasına izin verir, bu ad alanındaki başka herhangi bir sayfanın oluşturulmasına izin verilmez. Sayfada iyi biçimlendirilmiş JSON verilerini saklayabilirsiniz.

PHP'de MySettings verilerini okumak için, sayfaya erişmek için bir TitleValue nesnesi kullanın, ardından içeriğini isteyin: 

use JsonConfig\JCSingleton;
$tv = new TitleValue( NS_CONFIG, 'MySettings' ); // DB Key
$content = JCSingleton::GetContent( $tv );
if ( $content->isValid() ) {
    $data = $content->getData();
    ...
}

Supporting Wikimedia templates

Some templates (e.g. Template:TNT) from Wikimedia projects require JsonConfig to support the Data namespace on commons for mw.ext.data.get. You can use the following config to support that usecase. 

wfLoadExtension( 'JsonConfig' );

$wgJsonConfigEnableLuaSupport = true; // required to use JsonConfig in Lua
$wgJsonConfigModels['Tabular.JsonConfig'] = 'JsonConfig\JCTabularContent';
$wgJsonConfigs['Tabular.JsonConfig'] = [ 
        'namespace' => 486, 
        'nsName' => 'Data',
        // page name must end in ".tab", and contain at least one symbol
        'pattern' => '/.\.tab$/',
        'license' => 'CC0-1.0',
        'isLocal' => false,
];

$wgJsonConfigModels['Map.JsonConfig'] = 'JsonConfig\JCMapDataContent';
$wgJsonConfigs['Map.JsonConfig'] = [ 
        'namespace' => 486,
        'nsName' => 'Data',
        // page name must end in ".map", and contain at least one 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'
];

Bir kümede paylaşılan birden fazla yapılandırma

Diyelim ki, güvenilir proxy'lerin IP'lerini Meta-Wiki'de "Config:Proxy:SomeName" sayfaları olarak saklamaya ve bu verileri küme ile paylaşmaya karar verelim. 

// All wikis must have this configuration:
$wgJsonConfigs['JsonConfig.Proxy'] = [
  'pattern' => '/^Proxy\:./', // require at least one letter after the ':'
  'isLocal' => false,
];

// The LocalSettings.php for all wikis except Meta-Wiki will set this URL to Meta-Wiki's API endpoint:
$wgJsonConfigs['JsonConfig.Proxy']['remote'] = 'http://meta.wikimedia.org/w/api.php';

// LocalSettings.php for Meta-Wiki will indicate that the data should be stored there
$wgJsonConfigs['JsonConfig.Proxy']['store'] = true;

Bunun yerine, proxy'lere ayrı bir ad alanı tahsis etmek isterseniz, parametreler şu şekilde değişir: 

$wgJsonConfigs['JsonConfig.Proxy'] = [
  'namespace' => NNN, // NNN is the number you would reserve for Proxy namespace
  'nsName' => 'Proxy', // Canonical namespace name
];

Doğrulama

Çoğu zaman, kendi doğrulamasına sahip özel bir içerik sınıfı da istenir. JSON sayfaları, JCContent üzerinden türetilen içerik sınıfları tarafından yönetilir. İçerik sınıfı, ham metnin ayrıştırılması ve doğrulanmasından sorumludur. JCContent, JSON ayrıştırmasının ötesinde herhangi bir doğrulama yapmaz, ancak ondan türetmeyi ve JCContent::validate() ile geçersiz kılmayı seçebilirsiniz. Daha da iyisi, bir dizi doğrulama ilkeli sağlayan ve yalnızca JCObjContent::validateContent() ile geçersiz kılan JCObjContent sınıfından türetebilirsiniz. 

// This should be done on all wikis, including Meta-Wiki
$wgJsonConfigModels['JsonConfig.Proxy'] = 'ProxyExt\ProxyContent';

Bu belgenin iyiliği için, Opera Mini sunucularını açıklayan proxy yapılandırma sayfasının şu biçime sahip olduğunu varsayalım: 

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

İşte bu verileri doğrulamak için içerik sınıfı. 

use JsonConfig\JCObjContent;
use JsonConfig\JCValidators;

class ProxyContent extends JCObjContent {

    /**
     * Derived classes must implement this method to perform custom validation
     * using the check(...) calls
     */
    public function validateContent() {
        // 'enabled' must be a boolean, true by default.
        // JCValidators::* already handle localized error messages
        $this->testOptional( 'enabled', true, JCValidators::isBool() );
        // an optional field 'comment' of type string
        $this->testOptional( 'comment', '', JCValidators::isString() );
        // 'ips' must be a list of valid CIDR ranges
        // field is not optional when default value would not pass validation
        $this->test( 'ips', self::getIpValidator() );
    }

    private static function getIpValidator() {
        // JCValue $value is a value of the field being checked wrapped with the status information.
        //              $v->getValue() actual value being examined
        //              $v->isMissing() if the value is not present in the data
        //              $v->defaultUsed() if the value did not exist and a default was supplied
        // array $path the location of this field in the hierarchy - each value is either string or an int
        // JCObjContent $self - this object, useful to get access to other fields via $self->getField()
        // You may modify the value stored inside, set additional flags, or report an error
        // using the $v->error( $key, $path, ... ) function
        return function ( JCValue $value, array $path, JCObjContent $self ) {
            $isErr = false;
            $v = $value->getValue();
            if ( is_string( $v ) ) {
                // user supplied a single string, treat as an non-assoc array
                $v = array( $v );
            } else {
                // ensure that $v is an non-assoc array, and all of its values are strings
                $isErr = !JCUtils::isList( $v ) || !JCUtils::allValuesAreStrings( $v );
            }
            if ( !$isErr ) {
                // @todo: do the rest of the IP validation and set $isErr to true on failure
            }
            // Error message might be in this form:
            // "Parameter \"$1\" must be an array of valid non-restricted (no private networks) CIDR IP blocks"
            if ( $isErr ) {
                $value->error( 'my-proxyconfig-err-ips', $path );
            } else {
                $value->setValue( $v );
            }
        };
    }
}

Depolama vikisindeki özelleştirme davranışı

Ayrıca, depolama vikisinde görüntülemeyi ve sayfa oluşturmayı özelleştirmek isteyebilirsiniz (yukarıdaki örnekte Meta-Wiki). Bunu yapmanın iki yolu vardır: JCContent-türetilmiş sınıfınızın içinde veya JCContentView üzerinden türetilen ayrı bir "view" sınıfı aracılığıyla. İkinci yaklaşım, mimariyi temiz bir şekilde ayırdığı için tercih edilir ve görünüm sınıfının, verileri kullanan tüm vikilerde değil, yalnızca depolama vikisinde (örneğin, Meta-Wiki) bulunması gerekir.

JCContent-türetilmiş sınıftaki varsayılan değeri geçersiz kılmak için, yapıcıyı geçersiz kılın ve $text değerini üst kurucuya iletmeden önce NULL olarak gelirse yeni varsayılana ayarlayın. HTML oluşturmayı geçersiz kılmak için JCContent::getHtml() geçersiz kılın.

Önerilen şekilde, JCContentView veya daha zengin özelliklere sahip JCDefaultContentView üzerinden türetilen bir görünüm sınıfı oluşturun. JCContentView için, valueToHtml() ve getDefault() uygulamanız gerekecek. Varsayılan olarak, görünüm JCDefaultContentView sınıfı tarafından uygulanır ve bu, görünümünde küçük ayarlamalara ihtiyacınız varsa özelleştirilebilir bir temel olarak da kullanılabilir. 

// Yukarıdakinden model tanımını değiştirmek - META dahil tüm vikilerde yapılmalıdır
$wgJsonConfigModels['JsonConfig.Proxy'] = [ 'class' => 'ProxyExt\ProxyContent' ];

// view sınıfını ekleyin - yalnızca depolama vikisinde yapılmalıdır (ör. 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;
    }
}


En iyi uygulamalar

  • JsonConfig kullanan uzantılar, yapılandırmalarını ana uzantı dosyasındaki $wgJsonConfigs ve $wgJsonConfigModels değerlerine eklemelidir.
  • Yapılandırma verilerini birden fazla viki arasında paylaşırsanız, $wgJsonConfigs[] içinde kullanılan anahtar adını belgeleyin ve LocalSettings.php içinde 'store' / 'remote' bölümünü başlatın. Bu, yapılandırma işlevini çoğaltan bir dizi genel değişken sunmaktan daha iyidir. Örneğin Wikimedia'nın Graph uzantısı yapılandırmasına bakın (bu, basit yapılandırma değişkenleri yerine karmaşık çoklu viki kurulumunu kullanmasına rağmen).

Durum

Uygulanan özellikler

  • JSON ayrıştırma JSON metnini bir diziye veya bir nesneye dönüştürür
  • Görselleştirme JSON'u koddan ziyade görüntülemesi kolay bir tablo olarak gösterir ve bazı ekstra vurgulamalar içerir. Örneğin, değer sağlanmadıysa ve varsayılan kullanılıyorsa, gri renkte gösterilir veya değer varsayılanla aynı olduğunda mor olarak gösterilir. Örneğin, bunu ve bunu bakın.
  • Kod Düzenleyici JSON düzenlemeyi basitleştirir
  • Özel Doğrulama, değerin doğru biçimde olup olmadığını veya bir kullanıcı kimliğinin var olup olmadığını kontrol etmek gibi karmaşık kontroller gerçekleştirir.
  • MemCached önbelleğe alma json blob'larını memcached'de özel anahtarlar ve süre sonu politikaları altında depolar ve kaydetme sırasında sıfırlar.
  • Flagged Revision desteği, yapılandırmaların üretime geçmeden önce "incelendi" olarak işaretlenmesine izin verir
  • Çoğu temel arayüz öğesinin yerelleştirilmesi birçok dilde yapılmıştır ve en yaygın mesajların tek bir yerde yalnızca bir kez verilmesi çeviri işini azaltacaktır.

Uygulanmamış hoş şeyler

Bu özellikler, birden fazla yapılandırma türü için arzu edilir:

  • Şema doğrulayıcı - Çoğu uzantı karmaşık doğrulama kurallarına ihtiyaç duymayabileceğinden veya şema artı ekstra doğrulamayı birleştirmek isteyebileceğinden, JSON Şeması'na göre doğrulayın.
  • Özel düzenleyici - Zero team, muhtemelen JSON Schema'ya dayalı daha karmaşık bir düzenleyici uygulamayı düşünüyor.
  • API sorgu desteği - Yapılandırma sayfalarının, metin blobları yerine tüm biçimlerde - json/xml/... - normal API sonuçları olarak döndürülmesine izin verin:
    api.php ? action=query & titles=Config:Proxy:Opera & prop=jsonconfig
  • Yerelleştirme - her yapılandırma anahtarı için yerelleştirilmiş açıklamalar gösterebilmek iyi olur

Dış erişim

Depolanan yapılandırma verilerine sıklıkla JavaScript, bot veya diğer programlar gibi bazı harici aracılar tarafından ihtiyaç duyulabilir. JavaScript, standart action=query&rvprop=content API'yi çağırarak gerekli verilere erişmek için JSONP'yi kullanabilir veya CORS kullanılamıyorsa bir yönlendirme hizmeti geliştirebiliriz. Uzantı yazarları, alana özgü bilgiler sağlamak için kendi API modüllerini eklemeyi seçebilirler. Son olarak, rvprop=jcddata Sorgu API parametresi, rvprop=content döndüreceği bir metin blobu olarak değil, API sonucunun bir parçası olarak JSON verilerini döndürecektir. 

// UYGULANMADI! Nasıl doğru yapılacağına karar verene kadar normal action=query API'sini kullanın
var req = {
    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) { /* hataları ve uyarıları işleme, içeriği işleme */ }
});

Ayrıca bakınız

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:JsonConfig/tr&oldid=6299791"