Manual:Tag extensions/tr

Bireysel projeler, ister basit dize işleme ister tam gelişmiş bilgi alma olsun, ek yeteneklerle yerleşik viki işaretlemesini genişletmeyi yararlı bulacaktır. Etiket uzantıları, kullanıcıların tam da bunu yapan yeni özel etiketler oluşturmasına olanak tanır. Örneğin, sayfaya bir bağış formu ekleyen basit bir etiketi eklemek için bir etiket uzantısı kullanılabilir. Ayrıştırıcı işlevleri ve kancalar ile birlikte uzantılar, MediaWiki'nin işlevselliğini değiştirmenin veya geliştirmenin en etkili yoludur. Bir uzantı üzerinde çalışmaya başlamadan önce, yapmaya çalıştığınız şeyi başka birinin tam olarak yapmadığından emin olmak için her zaman kontrol etmelisiniz.

Basit bir etiket uzantısı, ayrıştırıcıya kancalı olan bir geri çağrı işlevinden oluşur, böylece ayrıştırıcı çalıştığında, tüm öğeleri bulup değiştirir. Gerçek HTML'yi oluşturmak için ilgili geri çağırma işlevini çağıran belirli bir etiketin örnekleri.

Örnek
In extension.json, set up the hooks:

And add the hook into a PHP file

Bu örnek, etiketi için bir geri çağrı işlevi kaydeder. Bir kullanıcı bu etiketi şöyle bir sayfaya eklediğinde:, ayrıştırıcı dört bağımsız değişken ileterek   işlevini çağırır:


 * $input : ve  etiketleri arasında giriş yapın veya etiket "kapalı" ise null, yani
 * $args : HTML etiketi öznitelikleri gibi girilen etiket bağımsız değişkenler; bu, öznitelik adına göre indekslenmiş bir ilişkisel dizidir.
 * $parser : Üst ayrıştırıcı (bir Parser nesnesi); daha gelişmiş uzantılar, bağlamsal Title elde etmek, viki metnini ayrıştırmak, parantezleri genişletmek, bağlantı ilişkilerini ve bağımlılıkları kaydetmek vb. için bunu kullanır.
 * $frame : Üst çerçeve (bir PPFrame nesnesi). Bu, uzantının çağrıldığı bağlam hakkında ayrıştırıcıya daha eksiksiz bilgi sağlamak için $parser ile birlikte kullanılır.

Daha ayrıntılı bir örnek için Etiket uzantısı örneği bakın

Öznitellikler
Başka bir örneğe bakalım:

Bu örnek, etikete iletilen öznitelikleri değerleriyle birlikte atar. Bunun yeni, özel etiketlerin esnek bir şekilde belirtilmesine izin verdiği oldukça açıktır. Örneğin, bir kullanıcının  gibi bir şey kullanarak kullanıcı sayfasına bir iletişim formu eklemesine izin veren bir etiket uzantısı tanımlayabilirsiniz.

MediaWiki için gerçek anlamda çok sayıda etiket uzantısı mevcuttur, bunlardan bazıları bu sitede listelenmiştir; diğerleri hızlı bir web aramasıyla bulunabilir. Bunların birçoğu kullanım durumları için oldukça uzmanlaşmış olsa da, değişen derecelerde işlevsellik sağlayan çok sayıda sevilen ve kullanılan uzantılar vardır.

Sözleşmeler
Bir uzantının genel düzeni ve kurulumu için sayfasına bakın.

Uzantılarınızı yayımlama

 * 1) Bu vikide uzantınız, nasıl kurulacağı ve kullanımdaki ekran görüntüleri hakkında bilgiler içeren Extension: adlı yeni bir sayfa oluşturun.  adlı bu bilgiyi tutmak için uygun bir şablon oluşturuldu. Daha fazla bilgi için şablon sayfasına bakın. Ayrıca sayfanın gövdesine mümkün olduğunca fazla ayrıntı eklemelisiniz ve ilgili tartışma sayfasındaki kullanıcı sorularına yanıt vermek için oldukça düzenli olarak tekrar kontrol etmek akıllıca olacaktır. Ayrıca sayfanın  ile ait olduğundan emin olun.
 * 2) Uzantı kodu içinde yeni kancalar oluşturan uzantılar, onları uzantı kancası kaydına kaydetmelidir.
 * 3) mediawiki-l posta listesine bildirin.

Ayrıca uzantınızı yayımlama bölümüne bakın.

Güvenlik endişeleri
Yukarıda, yukarıdaki örneklerdeki girişinin, döndürülmeden önce  kullanılarak kaçıldığını fark edeceksiniz. İsteğe bağlı HTML yerleştirme için vektörleri tanıtmaktan kaçınmak için, tüm kullanıcı girdilerinin istemcilere geri yansıtılmadan önce bu şekilde ele alınması hayati önem taşır, bu da siteler arası betik çalıştırma güvenlik açıkları oluşturmaya neden olabilir.

Yükleme modülleri
Uzantınız için modül eklemenin doğru yolu, onları $wgOut yerine ParserOutput ile eklemektir. Modül listesi daha sonra otomatik olarak ParserOutput nesnesinden alınacak ve sayfa işleme önceden önbelleğe alınmış olsa bile $wgOut ile eklenecektir. Modülleri doğrudan $wgOut ile ekliyorsanız, bunlar ayrıştırıcı çıkışında önbelleğe alınmamış olabilir.

Zamanlama ve uzantılar
Bir uzantının kodunu değiştirirseniz, uzantıyı kullanan tüm sayfalar teorik olarak yeni kodun sonuçlarını hemen yansıtır. Teknik olarak, bu, uzantıyı içeren bir sayfa her oluşturulduğunda kodunuzun yürütüldüğü anlamına gelir.

Uygulamada, MediaWiki yazılımı, tarayıcı veya bir aracı proxy veya güvenlik duvarı tarafından sayfa önbelleğe alma nedeniyle bu genellikle böyle değildir.

MediaWiki'nin ayrıştırıcı önbelleğini atlamak ve sayfanın yeni bir sürümünün oluşturulduğundan emin olmak için, Düzenle düğmesine tıklayın, tarayıcınızın adres çubuğunda gösterilen URL'deki "action=edit" olarak "action=purge" ile değiştirin ve yeni URL'yi gönderin. Sayfa ve kaynak verdiği tüm şablonlar, önbelleğe alınmış tüm veriler yok sayılarak yeniden oluşturulacaktır. Ana sayfanın kendisi değiştirilmediyse, ancak oluşturulma şekli değiştiyse (uzantı değiştirildi veya yalnızca başvurulan bir şablon değiştirildiyse) temizleme eylemi gereklidir.

Bu size sayfanın yeni bir kopyasını almak için yeterli değilse, normalde yukarıdaki URL'nin sonuna '&rand=somerandomtext' ekleyerek aracı önbellekleri atlayabilirsiniz. Her seferinde 'somerandomtext' farklı olduğundan emin olun.

Uzantımı kullanan sayfalar için önbelleğe almayı nasıl devre dışı bırakırım?
MediaWiki 1.5'ten beri, ayrıştırıcı bir uzantıya üçüncü parametre olarak geçirilir. Bu ayrıştırıcı, önbelleği şu şekilde geçersiz kılmak için kullanılabilir:

Başka bir sayfa düzenlendiğinde sayfayı yeniden oluşturma
Belki de önbelleğe almayı tamamen devre dışı bırakmak istemiyorsunuz, yalnızca başka bir sayfa düzenlendiğinde sayfanın yeniden oluşturulmasını istiyorsunuz, tıpkı şablon yansıtmaların işlenme şekline benzer şekilde. Bu, kanca işlevinize iletilen ayrıştırıcı nesne kullanılarak yapılabilir. Aşağıdaki yöntem dosyasından kaldırıldı ve bu amaç için çalışıyor gibi görünüyor.

Önbelleğe alma davranışının ince taneli ayarı
Uzantı çıkışınızın farklı sürümlerini ayırt etmek için önbellek anahtarlarını kullanarak uzantınız için ayrıntılı önbelleğe almayı kullanabilirsiniz. Oluştururken, kanca işlevinize bir addExtraKey yöntemi ekleyerek her özellik için önbellek anahtarları ekleyebilirsiniz, örneğin:

Ancak, ayrıştırma sırasında $parser->getOptions ögesinin değiştirilmesi, önbelleğe alınmış bir sayfa almaya çalışırken fazladan seçenek anahtarlarının eklenmediği, yalnızca önbelleğe alınacak bir sayfa oluşturulurken eklendiği anlamına gelir, böylece PageRenderingHash ek seçenekleri ayarlamak için kanca ögesini kullanabilirsiniz. PageRenderingHash, hem bir sayfa önbelleğe alınırken hem de çıkarılırken çalıştırılır, bu nedenle, henüz orada değilse, karmaya yalnızca yeni anahtarlar eklemek önemlidir. ör.:

Bununla ilgili bazı önemli notlar:


 * Konfstr'de yalnızca "!$value" yerine "!setting1=$value" kullanılması, farklı uzantılar yüklendiğinde veya yükleme sırası değiştiğinde ayrıştırıcı önbelleğinin bozulmamasını sağlar. ! farklı işleme seçenekleri için bir ayırıcı olarak kullanılır
 * Bazı kişiler  yerine   kullanır. addExtraKey ögenin ayrıştırıcı önbelleğine ekstra anahtarın kullanımda olduğunu söylemediği konusunda uyarılırsınız ve bu nedenle, dikkatli olmazsanız kolayca önbelleğin bozulmasına neden olabilir.

1.16 sürümünden beri
Ayrıştırıcı kanca işlevleri, ayrıştırıcı nesnesine ve bir çerçeve nesnesine bir kaynak iletilir; bunlar vikimetinin ayrıştırmak için kullanılmalıdır.

1.8 sürümünden beri kullanılmaktadır. Avantajları arasında basitlik (yalnızca bir bağımsız değişken alır ve bir dize döndürür) ve uzantı etiketlerini  içinde ayrıştırması ve böylece uzantı etiketlerini iç içe geçirmeniz yer alır.

recursiveTagParse için ikinci parametre olan, MW 1.16 alpha'da (r55682) sunulan isteğe bağlı bir bağımsız değikendir.


 * sağlanırsa (uzantınıza iletilen  değeri kullanılarak),   içindeki tüm şablon parametreleri genişletilecektir.  Diğer bir deyişle,   gibi içerik tanınır ve uygun değere dönüştürülür.
 * sağlanmazsa (örneğin, ) veya   false olarak ayarlanırsa, daha sonra şablon parametreleri genişletilmeyecektir;   değiştirilmeyecek. Bu istenen davranış olmamasına rağmen, MW 1.16'dan önce mevcut olan tek seçenek buydu.

Bununla birlikte, recursiveTagParse kullanılırken bile etiketler için hâlâ atlanan bir ayrıştırma adımı Parser::preSaveTransform değeridir. preSaveTransform, kaydedilmek üzere olan vikimetinde kalıcı değişiklikler yapmaktan sorumlu olan, ayrıştırmanın ilk adımıdır, örneğin:


 * İmza dönüştürme (, ~ ,  )
 * Boru hilesi olarak da bilinen bağlantı etiketlerini genişletme (örneğin, Help:Contents ile Contents olarak değiştirmek). Bu adım olmadan, Help:Contents gibi stenografi bağlantılar geçersiz kabul edilir ve ayrıştırıldığında vikimetin biçiminde bırakılır.
 * şablonlarını genişletme.

Orijinal preSaveTransform çağrısı, tüm uzantı etiketlerinde bu tür dönüşümleri kasıtlı olarak atlar. Kayıt öncesi dönüşümün yapılması gerekiyorsa, bunun yerine bir ayrıştırıcı işlevi kullanmayı düşünmelisiniz. Tüm etiket uzantıları, önceden kaydetme dönüşümü uygulanmış olan  kullanılarak bir ayrıştırıcı işlevi olarak da çağrılabilir.

Sürüm 1.5'ten beri
MediaWiki 1.5'ten beri, XML tarzı parametreler (etiket öznitelikleri) desteklenmektedir. Parametreler, bir ilişkisel dizi olarak, kanca işlevine ikinci parametre olarak iletilir. Değer dizelerinin zaten sizin için kodu çözülmüş HTML karakter ögelerine sahipler, bu nedenle onları HTML'ye geri gönderirseniz, HTML ekleme riskinden kaçınmak için  kullanmayı unutmayın.

Uzantımın HTML çıkışının değiştirilmesini nasıl önleyebilirim?
Bir etiket uzantısının return değeri, neredeyse ayrıştırılmış metin olarak kabul edilir; bu, onun saf HTML olarak ele alınmadığı, ancak yine de biraz değiştirildiği anlamına gelir. Bir etiket uzantısının çıkışına yapılan iki ana şey vardır (Birkaç küçük şeyle birlikte):


 * Şerit işaretleyicileri değiştirin. Şerit işaretleyiciler, kaldırılan içeriği daha sonra yeniden eklemek için bir işaret olarak hareket etmek üzere vikimetni işlemenin çeşitli aşamalarında eklenen belirli ögelerdir. Bu, uzantıların genellikle endişelenmesi gereken bir şey değildir.
 * , * ögelerin listelere ve baştaki boşlukla başlayan herhangi bir satırı diğer şeylerin yanı sıra ile dönüştürür. Bu bazen bazı uzantılarda sorun olabilir.

Etiket uzantıları, return değerinin nasıl yorumlanacağını değiştirmek için yalnızca bir dize yerine bir dizi döndürmeyi de destekler (ayrıştırıcı işlevlere çok benzer). Dizinin 0. değeri HTML olmalıdır. Daha fazla ayrıştırmayı durdurmak için "markerType" anahtarı  olarak ayarlanabilir. gibi bir şey yapmak, $html değerinin daha fazla değiştirilmemesini ve sadece düz html olarak değerlendirilmemesini sağlar.

Uzantımın Special:Version sayfasında görünmesini nasıl sağlayabilirim?
Uzantınızın MediaWiki Special:Version sayfasında görüntülenmesi için PHP kodu içinde uzantı katkıları atamanız gerekir.

Bunu yapmak için, kanca satırından veya işlev tanımından önce ilk yürütülebilir kod satırı olarak bir  değişkeni ekleyin.

Örnek bir uzantı katkısı şudur:

ögesini aşağıdakilerden biriyle değiştirin (uzantınız birden fazla sınıfa dahil değilse. Sonra her sınıf için bir katkı oluşturun):


 * 'specialpage' &mdash; MediaWiki Özel Sayfalarına yapılan eklemeler için ayrılmıştır;
 * 'parserhook' &mdash; uzantınız MediaWiki'deki ayrıştırıcı işlevlerini değiştirir, tamamlar veya değiştirirse kullanılır;
 * 'variable' &mdash; MediaWiki'ye birden çok işlev ekleyen uzantı;
 * 'media' &mdash; uzantınız bir tür medya işleyicisiyse kullanılır
 * 'other' &mdash; diğer tüm uzantılar.

, uzantınızın i18n.php dosyasında tanımlanması gerekecek olan uzantınızı açıklayan bir arabirim/i18n mesajının adıdır. Bu alanı atlarsanız, bunun yerine  alanı kullanılacaktır.

Geri çağrının içindeki etiket adını alma
Aynı geri çağırmayı paylaşan birkaç ve  etiketiniz olduğunu ve geri arama işlevinin içinde, geri aramayı başlatan etiketin adını almak istediğinizi varsayalım.

Kısa cevap şudur: etiket adı ( veya  ) geri çağrının bağımsız değişkenlerinin hiçbirinde mevcut değildir. Ancak, her etiket için dinamik olarak ayrı bir geri çağrı oluşturarak bu sorunu çözebilirsiniz:

Toolbar buttons
provides an editing toolbar, allowing users to add tags into their editor by simply clicking a button. If you want a toolbar button for your new tag, create a file named something like  in your extension's   folder. The file should look like this:

Further details about customizing this file can be found here. Once you've created the file, you need to register it with so it will be delivered to visitors; this is done by editing your  :

Then, in your PHP file:

Ayrıca bakınız

 * –,  gibi özel etiket/değişkenlerin listesi, ...
 * – Wikimedia vikilerinde kullanılan ayrıştırıcı etiketlerinin listesi.