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
Since MediaWiki 1.5, XML-style parameters (tag attributes) are supported. The parameters are passed as the second parameter to the hook function, as an associative array. The value strings have already had HTML character entities decoded for you, so if you emit them back to HTML, don't forget to use, to avoid the risk of HTML injection.

How can I avoid modification of my extension's HTML output?
The return value of a tag extension is considered almost parsed text, which means its not treated as pure html, but still modified slightly. There are two main things that are done to the output of a tag extension (Along with a couple other minor things):

Strip markers are certain items which are inserted at various stages of processing wikitext to act as a marker to re-insert removed content at a later time. This is not something extensions usually need to worry about. This can sometimes be an issue in some extensions.
 * Replace strip markers.
 * which turns *'s into lists, and turns any line starting with a leading space into a &lt;pre&gt; among other things.

Tag extensions also support returning an array instead of just a string (Much like parser functions) in order to change how the return value is interpreted. The 0th value of the array must be the HTML. The "markerType" key can be set to  in order to stop further parsing. Doing something like  would ensure that the $html value is not further modified and treated as just plain html.

How do I get my extension to show up on Special:Version?
In order for your extension to be displayed on the MediaWiki Special:Version page, you must assign extension credits within the PHP code.

To do this, add a  variable as the first executable line of code before the hook line or function definition.

An example extension credit is:

Replace  with one of the following (unless your extension falls under multiple classes&mdash;then create a credit for each class):


 * 'specialpage'&mdash;reserved for additions to MediaWiki Special Pages;
 * 'parserhook'&mdash;used if your extension modifies, complements, or replaces the parser functions in MediaWiki;
 * 'variable'&mdash;extension that add multiple functionality to MediaWiki;
 * 'media'&mdash;used if your extension is a media handler of some sort
 * 'other'&mdash;all other extensions.

The  is the name of an interface/i18n message that describes your extension that will need to be defined in your extension's i18n.php file. If you omit this field, the  field will be used instead.

Retrieving the tag name inside of the callback
Suppose you have several tags and  that share the same callback, and inside the callback function, you want to obtain the name of the tag that invoked the callback.

The short answer is: the tag name ( or  ) is not present in any of the callback's arguments. But you can work around this by dynamically constructing a separate callback for each tag:

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: