امتداد:إضافات

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

الدليل المرجعي لامتدادات ميدياويكي

Gadgets حالة الإصدار مستقر
تنفيذ	MyWiki , صفحة خاصة , واجهة برمجة التطبيقات
بيان	يسمح للمستخدمين بتمكين إضافات تستند إلى جافا سكريبت يقدمها المستخدمين من صفحة تفضيلاتهم
المؤلف/المؤلفون	Daniel Kinzler (Duesentriebنقاش)
سياسة التوافق	تصدر اللقطات البرمجية مع ميدياويكي. الإصدار الرئيسي لا يتوافق مع الإصدارات السابقة.
MediaWiki	1.19+
ترخيص	رخصة جنو العمومية 2.0 أو ما بعدها
التنزيل	تنزيل الامتداد غت [?]: تنزيل ملف غت الرئيسي تصفح المستودع (Phabricator · GitHub) تاريخ الالتزام مساهمو المستودع (غت هب) مراجعة الكود البرمجي README
مثال	ويكيميديا كومنز: نظرة عامة على الإضافات، تفضيلات المستخدمين (انقر على «إضافات»؛ يجب عليك أن تكون مسجل الدخول بالطبع)
المتغيرات $wgGadgetsRepo $wgSpecialGadgetUsageActiveUsers
الروابط المستخدمة BeforePageDisplay CodeEditorGetPageLanguage ContentHandlerDefaultModelFor DeleteUnknownPreferences GetPreferences PageDeleteComplete PageSaveComplete PreferencesGetIcon PreferencesGetLegend ResourceLoaderRegisterModules UserGetDefaultOptions getUserPermissionsErrors wgQueryPages
تنزيلات ربع سنوية	134 (Ranked 48th)
استخدام مواقع الويكي العمومية	4,529 (Ranked 177th)
ترجم الامتداد Gadgets لو كان متوفرا على translatewiki.net
المسائل	المهام المفتوحة · الإبلاغ عن عطل تقني

يقدم امتداد Gadgets سبيل للمستخدمين يمكنهم من اختيار «إضافات» مبنية على جافا سكريبت أو سي إس إس التي يقدمها مستخدمي موقع الويكي الآخرين.

تصمم الإضافات باستخدام قصاصات جافا سكريبت أو سي إس إس أو كلاهما موجودة في صفحات على نطاق الاسم ميدياويكي. تحدد كل إضافة باستخدام سطر في MediaWiki:Gadgets-definition، يقدم اسم وبيان للإضافة، وقائمة بقصاصات جافا سكريبت وسي إس إس التي تستعين بها (طالع فقرة الاستخدام التالية).

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

التنصيب

• نزّل الملف/الملفات وضعها في دليل يحمل اسم ‎Gadgets داخل مجلد ‎extensions/‎ لديك.
  يجب على مطوري البرمجيات والمساهمين بالكود البرمجي تثبيت الامتداد من غت بدلا من ذلك، مستخدمين:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets
• أضف الكود التالي في الجزء الأسفل من ملف LocalSettings.php :

  wfLoadExtension( 'Gadgets' );
  

•  تم التنفيذ – اذهب إلى Special:Version على موقع الويكي لديك كي تتحقق من أن الامتداد قد ثبت بنجاح.

الاستخدام

تشكيلة من بعض الإضافات الموجودة في تفضيلات المستخدم على موقع de.wikipedia

حال استحداث MediaWiki:Gadgets-definition مستخدمًا إضافة واحدة صالحة على الأقل، سيظهر قسم جديد اسمه «الإضافات» في صفحة Special:Preferences لكل المستخدمين. يمكن للمستخدمين تفعيل الإضافات التي يرغبون في استخدامها من هذا القسم. نظرة عامة على الإضافات المحددة حاليًا بموجب MediaWiki:Gadgets-definition تظهر أيضًا في صفحة Special:Gadgets، إلى جانب وصلات شبكية مفيدة إلى صفحات الأقلمة والنصوص البرمجية أو صفحات الأطر المعنية لتيسير الإنشاء أو التعديل. توجد إحصائيات تتناول تفضيلات الإضافات متاحة على Special:GadgetUsage.

صيغة التحديد

يجب أن يبدأ كل سطر في MediaWiki:Gadgets-definition بالمحرف «*» (النجمة) كي يعرّف إضافة. يجب أن يكون السطر بالصيغة التالية:

* mygadget [خيارات] | أسماء الصفحات

الخانة الأولى («mygadget» في المثال) هي الاسم الداخلي للإضافة. يأتي عنوان صفحة التفضيلات من صفحة رسائل الواجهة (MediaWiki:Gadget-mygadget) حيث يمكن كتابة الاسم الكامل وبيان قصير لها، وهو ما يسمح أيضًا باستخدام ترميز نصوص الويكي.

يتعين أن يبدأ الاسم الداخلي بحرف لاتيني أساسي ([A-Za-z]) ويجوز أن يتبعه أي عدد من الأحرف والأرقام ([0-9]) والشرطات (-) والشرطات التحتية (_) والنقط (.). إن السبب وراء هذا القيد هو أن الاسم الداخلي يتعين أن يكون صالحًا في صفة اسم بصيغة إتش تي إم إل، وكذلك في صفة مفتاح رسالة واجهة ميدياويكي وفي صفة اسم وحدة ResourceLoader برمجية.

تنسيق الخيارات:

[ResourceLoader | option1 | option2 | ... optionN]

وسم ResourceLoader مطلوب إلا في حال كانت الإضافة تحتوي على أطر لا غير. تحتاج الخيارات التي ليست سوى «وسوم» أن تكون أسماؤها مكتوبة كي يجري تفعيلها. تُتْبَع الخيارات التي تحتاج إلى قيمة علامة يساوي وقائمة قيم مفصولة بفاصلات. كافة المسافات الخالية اختيارية ويجوز حذفها.

[ResourceLoader | myflag | mykey = value1, value2, value3 ]

أمثلة:

* mygadget[ResourceLoader]|mygadget.js|mygadget.css

أو

* mygadget[ResourceLoader|package]| mygadget.js | mygadget-Foo.js | mygadget-data.json | mygadget.css

أو

* mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css

استخدام نطاق اسم تعريف الإضافات

إصدار ميدياويكي:

≤ 1.41

يوجد سبيلين اثنين لتحديد الإضافات استنادا إلى ‎$wgGadgetsRepoClass. لو كانت 'MediaWikiGadgetsDefinitionRepo' (القيمة الافتراضية)، سوف تحدد قائمة الإضافات المتاحة على MediaWiki:Gadgets-definition. سبيل آخر، وهو تحديد الإضافات على صفحات في نطاق الاسم تعريف الإضافات حينما تكون قيمة ‎$wgGadgetsRepoClass هي 'GadgetDefinitionNamespaceRepo'. (On MediaWiki 1.39+, the value to use instead is '\\MediaWiki\\Extension\\Gadgets\\GadgetDefinitionNamespaceRepo'.)

ترحيل تعريفات الإضافات القائمة غير مدعوم بعد، لذا سوف تفقد الإضافات المعرفّة من قبل بعد تغيير هذا الخيار.

إنشاء صفحة Gadget definition:mygadget ووضع نص جسون البرمجي التالي فيها سوف يكون له نفس أثر mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css.

{
	"settings": {
		"rights": [ "foo", "bar" ],
		"default": false,
		"package": false,
		"hidden": false,
		"skins": [],
		"actions": [],
		"category": ""
	},
	"module": {
		"scripts": [ "mygadget.js" ],
		"styles": [ "mygadget.css" ],
		"datas": [],
		"peers": [],
		"dependencies": [],
		"messages": [],
		"type": ""
	}
}

في المثال السابق، يستخدم كلا من Gadget:Mygadget.js وGadget:mygadget.css.

خيارات

الاسم	المتغيرات	الوصف	منذ
ResourceLoader	لا شيء	يسم النصوص البرمجية للإضافات في صفة متوافقة مع ResourceLoader .	1.17 (r76527)
dependencies	أسماء وحدات برمجية مفصولة بفاصلة	سوف تحمّل هذه الوحدات البرمجية قبل تنفيذ النصوص البرمجية لهذه الإضافة. طالع قائمة الوحدات البرمجية الافتراضية.	1.17 (r76639)
rights	أسماء امتيازات مفصولة بفاصلة	يجعل الإضافة متاحة (وظاهرة في التفضيلات) للمستخدمين الذين يتمتعون بامتيازات معينة دون غيرهم.	1.18 (r85268)
hidden	لا شيء	إخفاء الإضافة من صفحة التفضيلات. يمكن استخدام هذا السبيل بطريقة من اثنين: تمكين الإضافة بصفة افتراضية دون القدرة على تعطيلها (في صفة بديل وحدات برمجية للخاصية Common.js). لاحظ أنه يجب عليك أن تصيف كلا من: hidden | default لتحميل الوحدة البرمجية لكافة المستخدمين. الإضافات التي لا يقصد تقديمها للمستخدمين النهائيين، بل أن تحمّل عن طريق إضافات أخرى. على سبيل المثال، كي تسمح للإضافتين اثنين بإعادة استخدام ذات الكود البرمجي الداخلي، أو تسجيل الجزء «اللبي» من إضافة تحمّل فقط على صفحات معينة.	1.28
skins	أسماء سمات مفصولة بفاصلة	يجعل الإضافة متاحة (وظاهرة في التفضيلات) للمستخدمين الذين يستخدمون سمات محددة لا غير. قبل إصدار ميدياويكي 1.32 كنا ننظر بعين الاعتبار السمة المختارة في تفضيلات المستخدم، لا تلك المعروضة حاليًا (كما هو الحال حين إضافة ?useskin=monobook في معرف الموارد الموحد، مهمة T199478). منذ الإصدار 1.39، لم يعد نموذج ResourceLoader البرمجي مسجلًا على السمات غير المتاحة على الإضافات، لذا لا يمكن تحميل الإضافات على تلك السمات في صفة اعتماد أو باستخدام mw.loader.load() كذلك (مهمة T236603). استخدام skins هو آخر خيار ويجب أن يحصر بالكود المتخصص. على سبيل المثال، الكود الذي يعتمد على التعامل مع DOM في غياب واجهات برمجة تطبيقات معيارية ولا يمكن تنفيذها باستخدام وحدات اللب البرمجية.	1.19 (r100509)
actions	أسماء تصرفات مفصولة بفاصلة	يجعل الإضافة متاحة لتصرفات الصفحة المحددة لا غير. على سبيل المثال، actions = edit, history ينتج عنه تحميل إضافة أثناء التعديل وفي صفحات التاريخ لا غير. تحديد تصرف edit سوف ينتج عنه أيضًا تحميلها في action=submit. ينتج عن التصرفات غير الصالحة تعطيل الإضافة منذ أنها لا يمكن تشغيلها في أي مكان.	1.38 (gerrit:747112)
categories	أسماء تصنيفات مفصولة بفاصلة	يجعل الإضافة متاحة في التصنيفات المحددة لا غير. على سبيل المثال categories = Archived, Maintenance لتحميل إضافة في صفحات موجودة في Category:Archived أو Category:Maintenance لا غير.	1.42 (gerrit:1005092)
namespaces	أرقام نطاقات الاسم المفصولة بفاصلة	يجعل الإضافة متاحة على نطاقات الاسم المحددة لا غير. على سبيل المثال namespaces = 0, 2 لتحميل إضافة في النطاق الرئيسي ونطاق اسم المستخدم لا غير.	1.41 (gerrit:624517)
contentModels	نماذج محتوى مفصولة بفاصلة	يجعل من الإضافة متاحة على صفحات موجود فيه نماذج المحتوى المذكورة. على سبيل المثال contentModels = wikitext لتحميل إضافة في صفحات نصوص الويكي لا غير.	1.41 (gerrit:922062)
default	لا شيء	تفعيل الإضافة بصفة افتراضية للجميع (ويشمل ذلك عناوين الآيبي). لا يزال للمستخدمين المسجلين تعطيلها من تفضيلاتهم.	1.18 (r85902)
package	لا شيء	وضع علامة على هذه الإضافة في صفة محزومة. في هذا الوضع سيجري تنفيذ أول صفحة جافا سكريبت لا غير. يمكن استيراد الصفحات الأخرى مستخدمًا دالة require(). يمكّن هذا الوضع أيضًا استخدام صفحات جسون، التي لا يمكن ضمها خلاف ذلك.	1.38
targets	desktop أو mobile أو desktop,mobile(الافتراضي)	(رفع في 1.42.0-wmf.16) اضبط مستهدف/مستهدفات ResourceLoader للإضافة. لا تستخدم targets، بل استخدم skins حيث اقتضى الأمر ذلك.	1.21 (gerrit:60954)
type	styles (القيمة الافتراضية لإضافات سي إس إس لا غير) أو general (القيمة الافتراضية خلاف ذلك)	استخدم styles للوحدات البرمجية التي تعدل طراز العناصر الموجودة على الصفحة بالفعل لا غير (مثل أثناء تخصيص السمة أو الهيئة أو محتوى المقالة). سينتج عن هذا ضم ملفات سي إس إس الخاصة بالوحدة البرمجية من إتش تي إم إل الصفحة بدلًا من تحميلها باستخدام جافا سكريبت. لمزيد من التفاصيل، طالع ResourceLoader/Migration guide (users)#Gadget type. إن استخدام styles لن يحمّل أية ملفات جافا سكريبت محددة. فيما يخص الإضافات التي تعدّل طرز عناصر عن طريق كلًا من جافا سكريبت وكذلك سي إس إس، يتطلب الأمر وجود تعريفين اثنين مستقلين للإضافة.	1.28
peers	أسماء إضافات مفصولة بفاصلة	سوف تحمّل إضافات سي إس إس هذه فقط معًا مع هذه الإضافة. سوف تحمّل هذه الإضافة قبل أي dependencies، وسوف تنفّذ أنماطها حتى لو كانت جافا سكريبت معطلة. لمزيد من التفاصيل، طالع ResourceLoader/Migration guide (users)#Gadget peers.	1.29.0
supportsUrlLoad	لا شيء | true | false	اجعل الإضافة متاحة للتحميل مع متغير استعلام معرف الموارد الموحد ?withgadget.	1.38
requiresES6	لا شيء	(رفع في 1.42.0-wmf.13) يسمح باستخدام الإعراب النحوي ES6 (ES2015) في الإضافات. تمكين هذا الخيار يعني تخطي التصديق على الإعراب النحوي من طرف الخادم للإضافة. تحمّل أي إضافت تتطلب ES6 معًا في طلب وب واحد، وبالتالي يعزل حالات الفشل الناتجة عن إعراب نحوي غير صحيح أو غير مدعوم في هذه الإضافات وحدها، دون تأثير على الإضافات وسمات برمجيات ميدياويكي الأخرى. نحبّذ استخدام أداة مثل ESLint للتأكد من استخدام إعراب نحوي ES6 صالح لا غير. تضارب مع default.	1.40.0-wmf.7 (gerrit:758086)
top	لا شيء	(رفع في 1.29) يجعل الإضافة تحمّل أولًا. يجب استخدام هذه بحرص، إلا إنها مطلوبة في بعض أمور البدء مثل تسجيل الملحقات في المحرر المرئي.	1.22 (gerrit:75506)

يمكنك تحديد تبعيات إضافية لإضافتك، على سبيل المثال:

* mygadget[ResourceLoader|dependencies=jquery.ui, jquery.effects.clip]|mygadget.js|mygadget.css

هنا، نطلب من ResourceLoader تحميل الوحدات البرمجية jquery.ui وjquery.effects.clip مستخدمًا mygadget. لاحظ أن الإضافات لا يمكن تبعيتها على نصوص برمجية من صفحات أو ملفات جامدة أو معرفات موارد موحدة خارجية، بل وحدات برمجية مسجلة بالفعل في ResourceLoader. كي تجعل نصًا برمجيًا من صفحة يتبع نص برمجي آخر من صفحة، يجب على كليهما أن يكون إضافة تسجل نفسها في صفة وحدة برمجية في ResourceLoader، ومن ثم يمكن لكليهما أن يتبع غيره مستخدمًا الصياغة البرمجية التالية:

* childgadget[ResourceLoader|dependencies=ext.gadget.parentgadget]|childgadget.js

إن أردت تفعيل إضافة بصفة افتراضية، استخدم «default»:

* mygadget[ResourceLoader|default|dependencies=mediawiki.util]|mygadget.js|mygadget.css

كي تجعل الإضافة متاحة للمستخدمين الذين يتمتعون بالتصاريح الملائمة لا غير، اضبط خيار rights، على سبيل المثال:

* ImprovedDeletion [rights=delete] | ImprovedDeletion.js

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

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

* modrollback[ResourceLoader|rights=rollback]|modrollback.js
* UTCLiveClock[ResourceLoader|rights=purge]|UTCLiveClock.js
* Ajax_sysop[ResourceLoader|rights=patrol,rollback,markbotedits,delete]|Ajax_sysop.js

حقوق المستخدمين

يضيف هذا الامتداد حقي مستخدم جديدين، gadgets-edit وgadgets-definition-edit، الذين لا يمنحان لأي مجموعة بصفة افتراضية.

يمكنك إضافة ما يلي في LocalSettings.php لديك كي تقدم التصاريح الملائمة للمستخدمين المنتمين إلى مجموعة إداري الواجهة. يتطلب تعديل الصفحات الموجودة في نطاق الاسم «إضافات» التمتع بحق gadgets-edit وتعديل الصفحات الموجودة في نطاق اسم تعريف الإضافات يتطلب التمتع بحق gadgets-definition-edit.

$wgGroupPermissions['interface-admin']['gadgets-edit'] = true;
$wgGroupPermissions['interface-admin']['gadgets-definition-edit'] = true;

صفحات

الخانات المتبقية في السطر تشير إلى كود جافا سكريبت أو سي إس إس أو جسون البرمجي الذي يشكّل الإضافة الموجود في رسائل النظام. هذه مخزنة في نطاق الاسم ميدياويكي في صفة رسائل واجهة (MediaWiki:Gadget-mygadget.js وMediaWiki:Gadget-mygadget.css في المثال المذكور). يتعين أن تنتهي أسماء الصفحات بالنهايات «.css» أو «.js» أو «.json» على التوالي.

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

 * frobinator[ResourceLoader]|frob.js|frob.css|pretty.css
 * l33t[ResourceLoader]|l33t.js
 * foobar[ResourceLoader|package]|foo.js|bar.js|foobar-data.json

يرجى ملاحظة أنه لو كان كودك البرمجي يحتوي على أسطر يمكن تفسيرها في صفة نص برمجي ويكي (مثل كود التوقيع ~~~~)، ربما يجب عليك أن تحصرها في ‎<nowiki>...‎</nowiki> وأن تضع هذه الوسوم في تعليقات جافا سكريبت أو سي إس إس حتى لا يجري تفسيرها حينما تستخدم.

طالع السطرين الأول والأخير من MediaWiki:Gadget-externalsearch-bar.js مثالًا على ما ذكرنا.

فقرات

يمكن تقسيم قائمة الإضافات الموجودة في MediaWiki:Gadgets-definition إلى أقسام مستخدمًا أسطر تبدأ وتنتهي بعدد أثنين أو ثلاثة من المحارف «=» (علامة يساوي) توضع قبل وبعد اسم رسالة نظام تحدد اسم الفقرة، مثال ذلك:

 == interface-gadgets ==
 ...
 == editing-gadgets ==
 ...

سوف يحدد هذا فقرتين جديدتين، ويكون عنوانهما كما هو محدد في الصفحات MediaWiki:Gadget-section-interface-gadgets وMediaWiki:Gadget-section-editing-gadgets.

الإضافات الشائعة

طالع meta:Gadgets للتعرف على الإضافات الشائعة في مجتمعات ويكيميديا.

انظر أيضا

• Special:Gadgets – يسرد قائمة بكافة الإضافات وبيان قصير لكل منها
• Extension:Gadgets/Roadmap
• مدير الإضافات
• Extension:Widgets
• قصاصات