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ı
You can use fine grained caching for your extension by using cache keys to differentiate between different versions of your extension output. While rendering you can add cache keys for every feature by adding an addExtraKey method to your hook function, e.g.:

However, modifying $parser->getOptions during parse means that the extra option keys aren't included when trying to get a cached page, only when rendering a page to go into cache, so you can use the PageRenderingHash hook to set extra options. PageRenderingHash is run both when putting a page into cache, and getting it out, so its important to only add new keys to the hash if they're not already there. e.g:

Some important notes on this:

! is used a separator for different rendering options Be warned that addExtraKey does not tell the parser cache that the extra key is in use, and thus can easily result in breaking the cache if you are not careful.
 * Using "!setting1=$value" instead of just "!$value" in the confstr ensures that the parser cache does not become messed up if different extensions are installed or their load order changes.
 * Some people use  instead of.

Since version 1.16
Parser hook functions are passed a reference to the parser object and a frame object; these should be used to parse wikitext.

has been around since version 1.8. Its advantages include simplicity (it takes just one argument and returns a string) and the fact that it parses extension tags in, so you can nest extension tags.

The second parameter to recursiveTagParse,, is an optional argument introduced in MW 1.16 alpha (r55682).

In other words, content such as  will be recognized and converted into the appropriate value. Although this unlikely to be the desired behavior, this was the only option available before MW 1.16.
 * If  is provided (using the value of   passed to your extension), then any template parameters in   will be expanded.
 * If  is not provided (e.g.,  ), or if   is set to false, then template parameters will not be expanded;   will not be altered.

However, one step of parsing that is still skipped for tags, even when using recursiveTagParse, is Parser::preSaveTransform. preSaveTransform is the first step of parsing, responsible for making permanent changes to the about-to-be saved wikitext, such as:

(, ~ ,  )  Without this step, shorthand links such as Help:Contents are considered to be invalid, and are left in their wikitext form when parsed.
 * Converting signatures
 * Expanding link labels, also known as the pipe-trick (e.g., changing Help:Contents into Contents ).
 * Expanding templates.

The original call to preSaveTransform intentionally skips such conversions within all extension tags. If you need pre save transform to be done, you should consider using a parser function instead. All tag extensions can also be called as a parser function using  which will have pre save transform applied.

Since version 1.5
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: