Manual:Tag extensions/ar

غالبا ما ستجد بعض المشاريع وحدها أنه من المفيد توسيع وسم الويكي المدمج باستخدام إمكانات إضافية، سواء كانت من ناحية معالجة السطور البرمجية البسيطة وصولا إلى سبل استرداد معلومات كاملة. تسمح امتدادات الوسوم للمستخدمين إنشاء وسوم جديدة مخصصة تفعل ما ذكرناه هنا. يمكن للمرء على سبيل المثال استخدام امتداد وسوم كي يضيف وسم  بسيط يعمل على إضافة نموذج تبرع إلى صفحة ما. إن الامتداد جنبا إلى جنب مع دوال المعرب اللغوي والروابط هي أفضل سبيل لتغيير وظائف برمجيات ميدياويكي أو تحسينها. عليك دائما التحقق من المصفوفة قبل الشروع في العمل على امتداد ما كي تتأكد أنه لا يوجد شخص آخر فعل ما سوف تشرع في عمله.

يتألف امتداد وسوم بسيط من دالة استدعاء التي توصل بالمعرب اللغوي حتى يتمكن حينما يعمل المعرب اللغوي من البحث عن كافة حالات ذكر وسم معين واستبداله وبالتالي استدعاء دالة الاستدعاء المعنية كي عرض صيغة إتش تي إم إل الفعلية.

مثال
In extension.json, set up the hooks:

And add the hook into a PHP file

يسجل هذا المثال دالة استدعاء من أجل وسم. حينما يضيف مستخدم هذا الوسم إلى صفحة مثل هذه: ، سيتولى المعرب اللغوي استدعاء دالة   ومن ثم تمرير أربعة متغيرات:


 * $input : مدخلات بين وسوم  و  أو null لو كان الوسم «مغلق - closed» أي
 * $args : متغيرات الوسوم، التي تدخل كما يجري إدخال نعوت وسوم إتش تي إم إل؛ هذه هي سلسلة مترابطة تفهرس حسب اسم النعت.
 * $parser : المعرب اللغوي الرئيسي (كائن المعرب اللغوي)؛ تستخدم الامتدادات المتقدمة المستوى هذه كي تحصل على العنوان حسب السياق وكذلك إعراب نصوص الويكي وتوسيع الأقواس وتسجيل علاقات الوصلات واعتمادها على بعضها البعض وخلافه.
 * $frame : الهيكل الرئيسي (عنصر PPFrame). يستخدم جنبا إلى جنب مع $parser لأغراض تزويد المعرب اللغوي بمعلومات كاملة عن السياق الذي استدعي فيه الامتداد.

لمزيد من الأمثلة المفصلة، طالع مثال امتداد الوسوم

النعوت
هيا بنا نشاهد مثال آخر:

يضيف هذا المثال النعوت التي مررت إلى الوسم مع قيمها. لا جدال أن هذا الأمر يسمح بوجود تحديد مرن للوسوم الجديدة والمخصصة. ربما تحدد على سبيل المثال امتداد وسوم يسمح للمستخدم بإضافة نموذج اتصال إلى صفحة المستخدم ذاته، مستخدما كود برمجي كالتالي.

ثمة وفرة فعلية في امتدادات الوسوم متاحة لبرمجيات ميدياويكي وبعضها مدرج على هذا الموقع بينما الآخرين يمكن العثور عليهم مستخدما بحث سريع على الوب. بينما أن عدد من هذه الامتدادات متخصص إلى حد ما من ناحية حالات الاستخدام، يوجد كم كبير الامتدادات المحبوبة شائعة الاستخدام التي تقدم مستويات مختلفة من السمات.

الأعراف
طالع لتتعرف على الهيئة العامة وكيفية تنصيب امتداد.

نشر امتداداتك

 * 1) أنشئ صفحة جديدة على موقع الويكي هذا تحمل اسم Extension:&lt;extension_name> تحمل معلومات عن امتدادك وكيفية تنصيبه ولقطات من الشاشة أثناء استخدامه. يوجد قالب مؤاتي جاهز لإضافة تلك المعلومات يحمل اسم . طالع صفحة القالب لتطلع على مزيد من المعلومات. يتعين عليك أيضا أن تضيف أكبر كم ممكن من التفاصيل إلى متن الصفحة ومن الحصيف أن تزور الصفحة تكرارا كي ترد على أسئلة المستخدمين على صفحة النقاش الملحقة. تأكد أيضا من أن الصفحة أضيفت إلى.
 * 2) يجب أن تسجل الامتدادات التي تحدد وصلات جديدة داخل كود الامتداد البرمجي في صفحة سجل وصلات الامتدادات.
 * 3) أبلغ القائمة البريدية mediawiki-l.

طالع أيضا نشر امتدادك.

بواعث قلق تتعلق بالأمن
سوف تلاحظ فيما سبق أن المدخلات في الأمثلة سالفة الذكر تهرب باستخدام  قبل رجوعها. من الأهمية بمكان أن تعامل كافة مدخلات المستخدم بهذه الطريقة قبل ردها إلى جهاز العميل وذلك لتجنب إضافة محاور حقن برمجة اعتباطية قد تؤدي إلى حدوث ثغرات أمنية بسبب البرمجة على أكثر من موقع.

تحميل الوحدات البرمجية
إن أفضل سبيل لإضافة الوحدات البرمجية إلى امتدادك هو إضافتها إلى ParserOutput لا إلى $wgOut. من ثم سوف تؤخذ قائمة الوحدات البرمجية آليا من عنصر ParserOutput وتضاف إلى $wgOut حتى حينما يكون عرض الصفحة محفوظ في الحفظ المؤقت مسبقا. لو كنت تضيف الوحدات البرمجية مباشرة إلى $wgOut قد لا تحفظ حفظا مؤقتا في مخرجات المعرب اللغوي.

التوقيت والامتدادات
لو غيرت الكود المصدري لأي امتداد، سوف تعرض كافة الصفحات التي تستعين بالامتداد آليا على الفور نتائج الكود المصدري الجديد. من الناحية الفنية، يعني هذا أن كودك المصدري ينفذّ كل مرة تعرض فيها صفحة تحتوي على الامتداد.

ومن الناحية العملية، غالبا ما لا يكون الأمر كما سلف، بسبب الحفظ المؤقت للصفحة – سواء في برمجيات ميدياويكي أو متصفح الإنترنت أو بروكسي وسيط أو جدار ناري.

كي تتخطى الحفظ المؤقت للمعرب اللغوي لميدياويكي والتأكد أن النسخة الجديدة من الصفحة تولّد، اضغط على تعديل ومن ثم ضع محل "action=edit"في معرف الموارد الموحد المبين في سطر العنوان من متصفحك "action=purge" ومن ثم إرسال معرف الموارد الموحد الجديد. بهذه الطريقة سوف يعاد توليد الصفحة وكافة القوالب المذكورة فيها وبالتالي تجاهل كافة البيانات المحفوظة حفظا مؤقتا. يحتاج الأمر استخدام فعل تنظيف الحفظ المؤقت لو كانت الصفحة الرئيسية ذاتها لم يجري عليها تعديل، إلا أن الطريقة التي يتعين بها عرضها قد تغيرت (جرى على الامتداد تعديل أو مجرد تعديل قالب مذكور).

إن لم يكن هذا كافيا للحصول على نسخة حديثة من الصفحة، يمكنك في المعتاد تجاوز الحفظ المؤقت الوسيط عن طريق إضافة '&rand=somerandomtext' إلى نهاية معرف الموارد الموحد المذكور. احرص على أن يكون 'somerandomtext' مختلفا في كل مرة.

كيف أعطل الحفظ المؤقت للصفحات التي تستخدم امتدادي؟
منذ إصدار ميدياويكي 1.5، يمر المعرب اللغوي بصفته المتغير الثالث في أي امتداد. يمكن استخدام المعرب اللغوي في أغراض تعطيل الحفظ المؤقت كما يلي:

إعادة توليد الصفحة حينما يجري تعديل على صفحة أخرى
يجوز أنك لا ترغب في تعطيل الحفظ المؤقت كلية بل مجرد إعادة توليد الصفحة حينما يجري تعديل صفحة أخرى، كما هو الحال في كيفية التعامل مع أعمال تضمين القوالب. يمكن تنفيذ ذلك مستخدما عنصر المعرب اللغوي الذي يمرر إلى دالة الربط التي تستخدمها. رفعت الطريقة التالية من ملف ويبدو أنها تعمل على ما يرام لهذا الغرض.

التعديل الدقيق للغاية لسلوك الحفظ المؤقت
يمكنك استخدام الحفظ المؤقت الدقيق للغاية مع امتداداتك عن طريق استخدام مفاتيح الحفظ المؤقت كي تفرق بين الإصدارات المختلفة من مخرجات امتدادك. أثناء العرض يمكنك إضافة مفاتيح حفظ مؤقت لكل ميزة عن طريق إضافة طريقة addExtraKey إلى دالة رابطك. إليك مثال:

إلا أن تعديل $parser->getOptions أثناء الإعراب اللغوي يعني أن مفاتيح الخيار الإضافية ليست مشتملة حينما يحاول الحصول على صفحة محفوظة حفظا مؤقتا، بل سوف تشتمل فقط أثناء عرض صفحة بالذهاب إلى الحفظ المؤقت حتى يمكنك استخدام رابط PageRenderingHash لضبط خيارات إضافية. يعمل رابط PageRenderingHash حينما تضع صفحة في الحفظ المؤقت وكذلك إخراجها، لذلك من الأهمية بمكان أن تضع المفاتيح الجديدة إلى الرابط لو لم يوجد رابط قائم من قبل. إليك مثال:

هذه بعض من الملاحظات الهامة في هذا الشأن:


 * يضمن استخدام "!setting1=$value" بدلا من "!$value" فقط في confstr أن الحفظ المؤقت للمعرب اللغوي لا يصيبه الاختلال لو نصبّت امتدادات أخرى أو تغير ترتيب تحميلها. يستخدم المحرف ! في صفة فاصل بين خيارات العرض المختلفة
 * يستخدم البعض ‎ بدلا من استخدام ‎ . يرجى العلم أن إضافة addExtraKey لا يوجه الحفظ المؤقت للمعرب اللغوي إلى أن المفتاح الإضافي مستخدم، وبالتالي قد ينتج عن هذا تعطيل الحفظ المؤقت لو لم تكن حريصا.

منذ الإصدار 1.16
تمرر دوال روابط المعرب اللغوي بصفة ذكر لعنصر المعرب اللغوي وعنصر هيكل؛ يجب استخدام هذه في إعراب نصوص الويكي لغويا.

أضيفت ‎ منذ الإصدار 1.8. تشتمل مزايا ذلك البساطة (حيث يتطلب الأمر متغير واحد فقط ويكون رده هو سطر) وكذلك حقيقة أنه يعرب وسوم الامتداد لغويا في ‎ حتى يمكنك إدخال وسوم الامتداد داخل بعضها البعض.

أما المتغير الثاني في recursiveTagParse وهو  هو متغير اختياري أضيف إلى نسخة ميدياويكي 1.16 ألفا (r55682).


 * لو كان  موجود (باستخدام قيمة   التي مررت إلى امتدادك)، سوف ينتج عن هذا توسيع أية متغيرات قوالب موجودة في  .  بعبارة أخرى، سوف يجري التعرف على أي محتوى مثل   وسوف يحول إلى القيمة الملائمة للغرض.
 * لو كان  غير موجود (مثل  )، أو لو كان   مضبوطة قيمته إلى false، لن يجري توسيع متغيرات القالب أي لن يجري أي تغيير على  . رغم أن هذا الأمر يحتمل قليلا جدا أن يكون السلوك المرغوب، كان هذا هو الخيار الوحيد المتاح قبل إصدار ميدياويكي 1.16.

إلا أن خطوة واحدة في الإعراب اللغوي يجري حتى الآن تخطيها في أمور الوسوم حتى لو كنت تستخدم recursiveTagParse هي Parser::preSaveTransform. إن preSaveTransform هي أول خطوة في الإعراب اللغوي وتتولى إجراء تغييرات مستديمة على نص الويكي الذي على وشك لحفظ، كما يلي:


 * تحويل التوقيعات (, ~ ,  )
 * توسيع ملصقات الوصلات، الذي يعرف أيضا باسم pipe-trick (مثال على ذلك تغيير Help:Contents إلى Contents ). دون هذه الخطوة، سوف تعتبر الوصلات مثل Help:Contents غير صالحة، ومن ثم تترك في هيئتها نص ويكي حينما يجري إعرابها لغويا.
 * توسيع قوالب.

يتخطى الاستدعاء الأصلي في preSaveTransform عن قصد حالات التحويل هذه داخل كافة وسوم الامتداد. لو كنت ترغب في أن يجري التحويل قبل الحفظ، عليك أن تفكر جديا في استخدام دالة معرب لغوي بدلا من هذه. يمكن أيضا لكافة امتدادات الوسوم أن تستدعى في صفة دالة معرب لغوي مستخدما  وهو الذي سيعمل على تنفيذ التحويل قبل الحفظ.

منذ الإصدار 1.5
منذ إصدار ميدياويكي 1.5، أصبح دعم المتغيرات من نوع إكس إم إل (نعوت الوسوم) ممكنا. تمرر المتغيرات في صفة المتغير الثاني إلى دالة الرابط، في هيئة سلسلة مترابطة. سلاسل القيم جرى بالفعل فك تشفير كيانات محارف إتش تي إم إل فيها لأجلك، لذا لو أرسلتها مرة أخرى إلى إتش تي إم إل، لا تنس استخدام  كي تتجنب حدوث حقن لنص إتش تي إم إل برمجي.

كيف يمكنني تجنب حدوث تعديل على مخرجات إتش تي إم إل من امتدادي؟
تعتبر القيمة الراجعة من امتداد وسوم تقريبا نص معرب لغويا، ويعني هذا أنها لا عامل معاملة إتش تي إم إل صرف، بل يجري عليها تعديل طفيف. يوجد أمرين اثنين رئيسيين ينفذان على مخرجات امتداد وسوم (بالإضافة إلى بضعة أمور طفيفة أخرى):

This can sometimes be an issue in some extensions.
 * استبدال strip markers 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.
 * 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:

طالع أيضا

 * – List of special tag/variables like,  , ...
 * – List of parser tags in use on Wikimedia wikis.