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، أصبح دعم المتغيرات من نوع إكس إم إل (نعوت الوسوم) ممكنا. تمرر المتغيرات في صفة المتغير الثاني إلى دالة الرابط، في هيئة سلسلة مترابطة. سلاسل القيم جرى بالفعل فك تشفير كيانات محارف إتش تي إم إل فيها لأجلك، لذا لو أرسلتها مرة أخرى إلى إتش تي إم إل، لا تنس استخدام  كي تتجنب حدوث حقن لنص إتش تي إم إل برمجي.

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


 * استبدال strip markers. إن strip markers هي عناصر محددة تضاف في مراحل مختلفة من معالجة نصوص الويكي وتعمل في صفة مادة معلمة الغرض منها إضافة محتوى محذوف مرة أخرى في وقت لاحق. هذا الأمر ليس أمرا تحتاج الامتدادات للتعامل معه في المعتاد.
 * تحوّل محارف * إلى قوائم وتحول أي سطر يبدأ بمسافة إلى &lt;pre&gt; وأشياء أخرى. هذا الأمر قد يصبح في بعض الأحيان معضلة لبعض الامتدادات.

كما تساند امتدادات الوسوم رد سلسلة بدلا من مجرد سطر (كما هو الحال في دوال المعرب اللغوي) كي تغير كيفية تفسير القيمة المردودة. يتعين أن تكون القيمة 0 للسلسلة أن تكون بصيغة إتش تي إم إل. يجوز ضبط مفتاح «markerType» ليكون  كي توقف إجراء المزيد من الإعراب اللغوي. عمل شيء ما يشبه  قد يضمن أن قيمة ‎$html لا تعدل أي تعديل إضافي وتعامل معاملة إتش تي إم إل صرف.

كيف يمكنني جعل امتدادي يظهر في صفحة Special:version؟
كي يظهر امتدادك في صفحة Special:Version في ميدياويكي، يتعين عليك تعيين بيانات حقوق الامتداد داخل كود بي إتش بي البرمجي.

كي تنفذ ذلك، أضف متغير  في صفة أول سطر تنفيذ في الكود البرمجي قبل سطر الوصلة أو تعريف الدالة.

إليك مثال على بيانات حقوق الامتداد:

ضع محل  واحد مما يلي (إلا لو كان امتدادك ينتمي إلى أكثر من فئة واحدة. في هذه الحالة أنشئ بيانات حقوق لكل فئة على حدة):


 * 'specialpage' مخصص للإضافات إلى صفحات ميدياويكي الخاصة؛
 * 'parserhook' يستخدم لو كان امتدادك يعدل دوال المعرب اللغوي في ميدياويكي أو يكملها أو يحل محلها؛
 * 'variable' امتداد يضيف وظائف متعددة إلى ميدياويكي؛
 * 'media' يستخدم لو كان امتدادك يعمل بشكل أو آخر في صفة امتداد يتعامل مع ملفات وسائط؛
 * 'other' كافة الامتدادات الأخرى.

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

استرداد اسم الوسم داخل رد الاتصال
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.