Manual:Developing extensions/hi



हर एक्सटेंशन में तीन भाग होते हैं:


 * 1) सेटअप
 * 2) कार्यान्वयन
 * 3) स्थानीयकरण

एक मिनिमल एक्सटेंशन में यह संरचना मौजूद होगी:


 * MyExtension/extension.json
 * सेटअप के निर्देश का संग्रहण। फ़ाइल के नाम को 'extension.json' होना चाहिए। (मीडियाविकि 1.25 से पहले सेटअप के निर्देश एक्सटेंशन के अनुसार नामित एक  फ़ाइल में थे। कई एक्सटेंशन अभी भी इस PHP फ़ाइल में पीछे की ओर की संगतता शिम हैं।)


 * MyExtension/includes/ (or MyExtension/src/)
 * एक्सटेंशन के लिए PHP निष्पादन कोड रखता है।


 * MyExtension/resources/ (or MyExtension/modules/)
 * एक्सटेंशन के लिए क्लाइंट-मुखी जानकारी जैसे जावास्क्रिप्ट, CSS, LESS आदि रखता है।


 * MyExtension/i18n/*.json
 * एक्सटेंशन के लिए स्थानीयकरण की जानकारी रखता है।

जब आप एक एक्सटेंशन विकसित करेंगे, 'MyExtension' को आपके एक्सटेंशन के नाम से बदल दीजिएगा। उसकी डिरेक्ट्री और PHP फ़ाइल(ओं) के नाम 'अपर कैमल केस' में रखें; यह साधारण फ़ाइल नामकरण प्रथा है। ( आपके एक्सटेंशन के लिए शुरुआत की एक अच्छी जगह है।)

सेटअप
सेटअप का हिस्सा लिखने के दौरान आपका उद्देश्य है एक्सटेंशन को स्थापित करने में यथासंभव आसान बनाना, ताकि सदस्यों को बस LocalSettings.php पर यह पंक्ति जोड़नी पड़े:

अगर आप चाहते हैं कि सदस्य आपके एक्सटेंशन को कॉन्फ़िगर कर पाएँ, आपको कुछ कॉन्फ़िगरेशन पैरामीटरों को परिभाषित और प्रलेखित करना होगा, और आपके सदस्य का सेटअप कुछ ऐसा नज़र आएगा:

इस सरलता तक पहुँचने के लिए आपके सेटअप फ़ाइल को कई कार्य करने होंगे (जिन्हें निम्न अनुभागों में विस्तार से वर्णित किया गया है):


 * आपके एक्सटेंशन द्वारा उपयुक्त किसी भी मीडिया हैंडलर, पार्सर फ़ंक्शन, विशेष पृष्ठ, अनुकूलित XML टैग, और वेरिएबल को पंजीकृत करना।
 * आपके एक्सटेंशन के लिए परिभाषित किसी भी कॉन्फ़िगरेशन वेरिएबलों को परिभाषित और/या वैलिडेट करना।
 * स्वतः लोड करने के लिए आपके एक्सटेंशन द्वारा उपयुक्त वर्गों को तैयार करना।
 * यह तय करना कि आपके सेटअप का कौन-सा हिस्सा तुरंत किया जाना चाहिए और कौन-सा हिस्सा मीडियाविकि मूल के शुरू होने और कॉन्फ़िगर किए जाने के बाद किया जाना चाहिए।
 * आपके एक्सटेंशन द्वारा उपयुक्त किसी भी अतिरिक्त हुक को पंजीकृत करना।
 * आपके एक्सटेंशन द्वारा उपयुक्त किसी भी नए डेटाबेस टेबल को बनाना या जाँचना।
 * आपके एक्सटेंशन के लिए स्थानीयकरण सेटअप करना।



मीडियाविकि पर सुविधाएँ पंजीकृत करना
मीडियाविकि के  पृष्ठ पर सभी स्थापित एक्सटेंशनों को सूचीबद्ध किया जाता है। उदाहरणस्वरूप, आप Special:Version पर, इस विकि पर स्थापित सभी एक्सटेंशन देख सकते हैं।

ऐसा करने के लिए एक्सटेंशन की जानकारी extension.json पर जोड़ दें। एंट्री कुछ ऐसी दिखेगी:

कई फ़ील्ड्स वैकल्पिक हैं, मगर उन्हें भर देना एक अच्छी प्रथा है। उस स्केमा का संस्करण है जिसके विरुद्ध फ़ाइल को लिखा गया है। उपलब्ध संस्करण हैं 1 और 2। इस सुविधा के बारे में प्रलेख के लिए यहाँ देखें। अगर आपको मीडियाविकि के किसी अधिक पुराने संस्करण को समर्थित करने की ज़रूरत नहीं, नवीनतम संस्करण चुनें।

उपरोक्त पंजीकरण के साथ, आपको अपनी सुविधा को मीडियाविकि पर "हुक" भी कराना होगा। उपरोक्त विधि सिर्फ Special:Version पृष्ठ को सेटअप करती है। आप यह काम किस तरह से करेंगे, यह आपके एक्सटेंशन के प्रकार पर निर्भर होगा। विस्तार के लिए कृपया हर प्रकार के एक्सटेंशन का प्रलेख देखें:



अपने एक्सटेंशन को कॉन्फ़िगर करने योग्य बनाना
अगर आप चाहते हैं कि सदस्य आपके एक्सटेंशन को कॉन्फ़िगर कर पाएँ, आपको एक या एकाधिक कॉन्फ़िगरेशन वेलिएबल्स प्रदान करने होंगे। उन वेरिएबलों को अनूठे नाम देना अच्छा होगा। उन्हें मीडियाविकि की नामकरण प्रथाओं का भी पालन करना होगा (जैसे ग्लोबल वेरिएबलों की शुरुआत $wg से होनी चाहिए)।

उदाहरणस्वरूप, अगर आपके एक्सटेंशन का नाम "MyExtension" है, आप अपने सभी कॉन्फ़िगरेशन वेरिएबलों की शुरुआत में  जोड़ सकते हैं। यह सुनिश्चित करना ज़रूरी है कि मीडियाविकि मूल में से कोई भी वेरिएबल इस तरह से शुरू नहीं होता है, और आपको यह भी जाँचना चाहिए कि कोई भी प्रकाशित एक्सटेंशन इस तरह से वेरिएबलों की शुरुआत नहीं करता है। अगर ओवरलैप होने वाले वेरिएबलों के नामों की वजह से सदस्यों को आपके या किसी दूसरे एक्सटेंशन के बीच किसी एक को चुनना पड़े, आपकी खैर नहीं होगी।

अपनी स्थापना की टिप्पणियों में हर कॉन्फ़िगरेशन वेरिएबल के लिए विस्तृत प्रलेख शामिल करना भी एक अच्छी प्रथा है।

यह रहा शुरुआत करने के लिए एक बॉइलर प्लेट का उदाहरण:

ध्यान रखें कि  को कॉल करने के बाद ग्लोबल वेरिएबल   मौजूद नहीं होता। अगर आप वेरिएबल को सेट करते हैं, मान लीजिए   पर, तब extension.json में निर्दिष्ट डिफ़ॉल्ट वैल्यू का इस्तेमाल नहीं किया जाएगा। If you set the variable, e.g. in  then the default value given in extension.json will not be used.

अनुकूलित एक्सटेंशनों के अंदर ग्लोबल वेरिएबलों के बारे में अधिक जानकारी के लिए देखें।



स्वतः लोडिंग के लिए वर्ग तैयार करना
अगर आप अपने एक्सटेंशन को लागू करने के लिए वर्ग का इस्तेमाल करते हैं, मीडियाविकि पर एक सरलीकृत तंत्र है जिससे PHP उस स्रोत फ़ाइल को आसानी से ढूँढ़ पाएगा जहाँ पर आपका वर्ग स्थित है। ज़्यादातर मामलों में इस कारण आपको अपना  साधन लिखने की ज़रूरत नहीं पड़ेगी।

मीडियाविकि के स्वतः लोडिंग तंत्र का इस्तेमाल करने के लिए आपको फ़ील्ड में एंट्रियाँ जोड़नी होंगी। हर एंट्री की कुँजी वर्ग का नाम होगी; वैल्यू उस फ़ाइल का नाम होगा जिसमें वर्ग की परिभाषा मौजूद होगी। किसी साधारण एक-वर्ग-वाले एक्सटेंशन के लिए वर्ग को आम तौर पर एक्सटेंशन का नाम दिया जाता है, तो आपका स्वतः लोडिंग अनुभाग कुछ इस तरह का नज़र आएगा (एक्सटेंशन का नाम है 'MyExtension'):

फ़ाइल का नाम उस डिरेक्ट्री के सापेक्ष है जिसमें extension.json फ़ाइल मौजूद है।

अधिक जटिल एक्सटेंशनों के लिए नामस्थानों का इस्तेमाल किया जा सकता है। विस्तार के लिए Manual:Extension.json/Schema#AutoloadNamespaces देखें।



अतिरिक्त हुक्स परिभाषित करना
देखें।



डेटाबेस टेबल्स जोड़ना
सुनिश्चित करें कि एक्सटेंशन मूल डेटाबेस टेबलों को बदलता नहीं है। इस बजाय, एक्सटेंशन को प्रासंगिक MW टेबलों तक बाहरी कुँजियों वाले नए टेबल्स बनाने चाहिए।

अगर आपके एक्सटेंशन को अपने डेटाबेस टेबल्स जोड़ने की ज़रूरत है, हुक का इस्तेमाल करें। उपयोग के बारे में अधिक जानकारी के लिए मैन्युअल पृष्ठ देखें।



स्थानीयकरण सेटअप करें
देखें:
 * स्थानीयकरण (संक्षिप्त)



लॉग्स जोड़ें
मीडियाविकि पर पारदर्शिता और सहयोग के लिए विकि पर सदस्यों द्वारा सभी कार्यों को ट्रैक किया जाता है। ऐसा करने के लिए देखें।



निर्भरताएँ हैंडल करना
मान लें कि एक्सटेंशन को किसी दूसरे एक्सटेंशन की उपस्थिति की ज़रूरत होती है, उदाहरणस्वरूप क्योंकि कार्यक्षमताएँ या डेटाबेस टेबल्स का इस्तेमाल किया जाता है और गैर-उपस्थिति के मामले में त्रुटि संदेशों से बचा जाता है।

उदाहरणस्वरूप, एक्सटेंशन को विशिष्ट फ़ंक्शन्स के लिए  एक्सटेंशन की उपस्थिति की ज़रूरत होती है।

इसे निर्दिष्ट करने का एक तरीका होगा extension.json में  कुँजी का इस्तेमाल करना।

अन्यथा, ये रहे कुछ और विचार:

यह 1.23 से लेकर कम-से-कम 1.35 तक काम करेगा।

स्थानीयकरण
अगर आप चाहते हैं कि आपके एक्सटेंशन के इस्तेमाल उन विकियों पर किया जाए जो एकाधिक भाषाओं में उपलब्ध है, आपको अपने एक्सटेंशन पर स्थानीयकरण का समर्थन जोड़ना होगा।



&lt;language-key>.json में संदेश रखें
एक स्थानीयकरण JSON फ़ाइल में संदेशों की परिभाषाएँ रखें, जहाँ हर भाषा कुँजी आपके एक्सटेंशन की एक अनुवादित भाषा को प्रतिनिधित करेगी। संदेशों को एक संदेश कुँजी और संदेश के साथ मानक JSON प्रारूप में रखा जाता है। हर संदेश छोटे अक्षरों में होना चाहिए और उनमें रिक्त स्थान नहीं होने चाहिए। हर कुँजी के नाम की शुरुआत छोटे अक्षरों में एक्सटेंशन के नाम से होनी चाहिए। एक उदाहरण आप MobileFrontend एक्सटेंशन में पा सकते हैं। यह रहा एक मिनिमल JSON फ़ाइल का उदाहरण (इस मामले में 'en.json'):

en.json



संदेश प्रलेख qqq.json में रखें
संदेश की कुँजियों के लिए प्रलेख qqq कोड वाली छद्म-भाषा के लिए JSON फ़ाइल में रखा जा सकता है। उपरोक्त उदाहरण का एक प्रलेख हो सकता है:

qqq.json:



स्थानीयकरण फ़ाइल लोड करें
अपने extension.json में अपनी संदेश फ़ाइलों का स्थान निर्दिष्ट करें (उदाहरणस्वरूप, i18n/ डिरेक्ट्री में):



PHP में wfMessage का इस्तेमाल करें
अपने सेटअप और कार्यान्वयन कोड में संदेश के हर शाब्दिक उपयोग को  के एक कॉल से बदल दें। (और SpecialPage के उपवर्गों जैसे कुछ अधिक) का इस्तेमाल करने वाले वर्गों पर आप का इस्तेमाल कर सकते हैं। उदाहरण:



जावास्क्रिप्ट में mw.message का इस्तेमाल करें
जावास्क्रिप्ट में भी i18n फ़ंक्शन्स का इस्तेमाल किया जा सकता है। विस्तार के लिए देखें।



एक्सटेंशन के प्रकार
एक्सटेंशनों को कार्यान्वयन की प्रोग्रामिंग तकनीकों के अनुसार श्रेणीबद्ध किया जा सकता है। ज़्यादातर जटिल एक्सटेंशन्स इनमें से एकाधिक तकनीकों का इस्तेमाल करते हैं:


 * उपवर्गीकरण: मीडियाविकि यह अपेक्षा करेगा कि विशिष्ट प्रकार के एक्सटेंशनों को मीडियाविकि द्वारा प्रदत्त बुनियादी वर्गों के उपवर्गों के रूप में लागू किया जाए:
 *  – के उपवर्गों की मदद से वे पृष्ठ बनाए जाते हैं जिन्हें सिस्टम की वर्तमान स्थिति, सदस्यों द्वारा इनपुट पैरामीटरों, और डेटाबेस क्वेरीज़ की मदद से डायनामिक रूप से बनाया जाता है। रिपोर्ट्स और डेटा एंट्री फ़ॉर्म्स, दोनो बनाए जा सकते हैं। इनकी मदद से रिपोर्टिंग और प्रबंधन के कार्य, दोनों किए जा सकते हैं।
 *  – स्किन्स, मीडियाविकि के वर्ग के उपवर्ग बनकर पृष्ठों को आउटपुट करने वाले कोड को बदलकर मीडियाविकि की दिखावट और अनुभव को बदलते हैं।
 *  – मीडियाविकि के प्रोसेसिंग के अंदर कुँजी पॉइंट्स पर अनुकूलित PHP कोड जोड़ने का एक तकनीक। इनका इस्तेमाल मीडियाविकि के पार्सर, इसके स्थानीयकरण इंजन, इसकी एक्सटेंशन प्रबंधन प्रणाली और इसकी अनुरक्षण प्रणाली द्वारा किया जाता है।
 *  – XML-रूप टैग्स जिन्हें HTML कोड आउटपुट करने वाले किसी PHP फ़ंक्शन से जोड़ा जाता है। अपने आपको टैग्स के अंदर के टेक्स्ट को ही प्रारूपित करने तक सीमित न करें। आपको उसे दिखाने की भी ज़रूरत नहीं। कई टैग एक्सटेंशन्स टेक्स्ट का इस्तेमाल पैरामीटरों के रूप में करते हैं जिससे Google वस्तुओं, डेटा एंट्री फ़ॉर्म्स, RSS फ़ीड्स, चुनिंदा विकि लेखों से सारांश, आदि को एम्बेड करने वाला HTML बनाया जा सकता है।
 *  – एक तकनीक जिसे किसी फ़ंक्शन से संबद्ध एक ही ID से कई विकिटेक्स्ट स्ट्रिंग्स मैप किए जा सकते हैं। वेरिएबल्स और पार्सर फ़ंक्शन्स, दोनों इस तकनीक का इस्तेमाल करते हैं। उस ID पर मैप किए गए सारे टेक्स्ट को फ़ंक्शन द्वारा लौटाए गए वैल्यू से बदल दिया जाएगा। टेक्स्ट स्ट्रिंग्स और ID के बीच मानचित्रण को $magicWords ऐरे में रखा जाता है। ID का विवेचन एक जटिल प्रक्रिया है - अधिक जानकारी के लिए देखें।
 *  – इन्हें वेरिएबल्स कहना गलत होगा। ये विकिटेक्स्ट के हिस्से हैं जो साँचों की तरह दिखते हैं, मगर इनमें कोई पैरामीटर या निर्दिष्ट होर्ड-कोड किए गए वैल्यू नहीं होते हैं।  या   जैसे मानक विकि मार्कअप वेरिएबलों के उदाहरण हैं। इनका नाम इनके वैल्यूओं के स्रोत के आधार पर दिया गया है: एक PHP वेरिएबल या फिर ऐसा कुछ जो किसी वेरिएबल को सौंपा जा सकता है, जैसे कोई स्ट्रिंग, संख्या, एक्सप्रेशन, या फ़ंक्शन में लौटाया गया वैल्यू।
 *  – .  टैग एक्सटेंशन्स की तरह पार्सर फ़ंक्शन्स तर्कों को प्रोसेस करके एक वैल्यू लौटाते हैं। टैग फ़ंक्शन्स के विपरीत, पार्सर फ़ंक्शन्स का परिणाम विकिटेक्स्ट होता है।
 *  – आप मीडियाविकि के प्रतिक्रिया API पर अनुकूलित मॉड्यूल्स जोड़ सकते हैं जिन्हें जावास्क्रिप्ट, बॉट्स या तृतीय-पक्ष क्लाइंट्स की मदद से इन्वोक किया जा सकता है।
 *  – अगर आपको विकिटेक्स्ट, JSON, आदि के अलावा किसी प्रारूप में डेटा रखने की ज़रूरत है, आप एक नया बना सकते हैं।



दूसरे मूल संस्करणों का समर्थन
मीडियाविकि मूल के पुराने संस्करणों को समर्थित करने की दो प्रचलित प्रथाएँ हैं:

(For extensions hosted on gerrit, these branches are automatically created when new versions of MediaWiki are released.) This results in cleaner code and faster development but users on old core versions do not benefit from bugfixes and new features unless they are backported manually.
 * Master: एक्सटेंशन की master शाखा, मूल जितने हो सके उतने पुराने संस्करणों से अनुकूल है। इससे अनुरक्षण पर ज़रा-सा बोझ पड़ता है (पीछे की तरफ अनुकूलता के लिए हैक्स काफ़ी लंबे समय तक रखने पड़ते हैं, और एक्सटेंशन में बदलावों को मीडियाविकि के कई पुराने संस्करणों पर परीक्षित करना पड़ता है), मगर मीडियाविकि के पुराने संस्करण चला रहे साइटों को एक्सटेंशन पर हाल में जोड़ी गई कार्यक्षमता से फ़ायदा हो सकता है।
 * प्रकाशन शाखाएँ: एक्सटेंशन की प्रकाशन शाखाएँ मूल की उचित शाखाओं से अनुकूल हैं, जैसे मीडियाविकि का इस्तेमाल करने वाले साइटों को एक्सटेंशन की  शाखा का इस्तेमाल करना होगा। (Gerrit पर होस्ट किए जाने वाले एक्सटेंशनों के लिए, ये शाखाएँ मीडियाविकि के नए संस्करणों के प्रकाशित किए जाने पर अपने आप बना दी जाती हैं।) इससे कोड साफ़-सुथरा रहता है और विकास की तेज़ी बढ़ जाती है, मगर पुराने मूल संस्करणों का इस्तेमाल करने वाले विकियों को बग-सुधारों और नई सुविधाओं से फ़ायदा नहीं होता अगर उन्हें सदस्यों द्वारा बैकपोर्ट न किया जाए।

एक्सटेंशनों के अनुरक्षकों को Extension साँचे के  पैरामीटर से यह घोषित कर देना चाहिए कि वे किस प्रथा का पालन करते हैं।

प्रकाशन
अपने मौजूदा एक्सटेंशन के प्रलेख को स्वतः श्रेणीबद्ध और मानकीकृत करने के लिए कृपया देखें। अपने नए एक्सटेंशन को इस विकि पर जोड़ने के लिए:



तैनात-कार्य और पंजीकरण
अगर आपका उद्देश्य है अपने एक्सटेंशन को विकिमीडिया साइटों (संभवतः विकिपीडिया समेत) में लागू करवाना, प्रदर्शन और सुरक्षा में अतिरिक्त सावधानी का आश्वासन ज़रूरी है। देखें।

अगर आपका एक्सटेंशन नामस्थान जोड़ता है, आपको इसके डिफ़ॉल्ट नामस्थानों को पंजीकृत कर देना चाहिए; उसी तरह, अगर यह डेटाबेस टेबल्स जोड़ता है, आपको उन्हें पर पंजीकृत कर देना चाहिए।

कृपया ध्यान रखें कि विकिमीडिया साइटों पर नए एक्सटेंशनों के निरीक्षण और तैनात-कार्य की प्रक्रिया काफ़ी धीमी हो सकती है, और कुछ मामलों में तो इसे दो से भी ज़्यादा वर्ष लग जाते हैं।

<span id="Help_documentation">

सहायता प्रलेख
आपको अपने एक्सटेंशन द्वारा प्रदत्त सुविधाओं के लिए एक सार्वजनिक डोमेन सहायता प्रलेख प्रदान करना चाहिए। एक अच्छा उदाहरण है । आपको फ़ंक्शन की मदद से सदस्यों को प्रलेख की एक कड़ी देनी चाहिए।

<span id="Providing_support_/_collaboration">

सहायता / सहयोग प्रदान करना
एक्सटेंशन के विकासकों को विकिमीडिया के पर एक खाता बनाना चाहिए, और एक्सटेंशन के लिए एक नई परियोजना का अनुरोध करना चाहिए। यह एक सार्वजनिक मंच प्रदान करेगा जहाँ सदस्य समस्याएँ और सुझाव प्रस्तुत कर पाएँगे, और आप सदस्यों और विकासकों के साथ मिलकर बग्स ठीक कर सकते हैं और अपने एक्सटेंशन के लिए सुविधाओं की योजनाएँ बना सकते हैं।

<span id="See_also">

ये भी देखें

 * – विस्तृत इनलाइन प्रलेख के साथ कुछ उदाहरण सुविधाएँ लागू करता है
 * – एक काम करने वाला बॉइलरप्लेट एक्सटेंशन, जिसे आप अपने एक्सटेंशन के लिए शुरुआत का एक स्थान मानकर चल सकते हैं
 * Example एक्सटेंशन पढ़ें, और अपने कोड को BoilerPlate एक्सटेंशन पर आधारित करें।
 * cookiecutter-mediawiki-extension – एक cookiecutter साँचा जो एक बॉइलरप्लेट एक्सटेंशन बनाता है (वेरिएबलों आदि के साथ)
 * इससे आप तुरंत अपना एक्सटेंशन बनाना शुरू कर सकते हैं।
 * BoilerPlate एक्सटेंशन भी बना सकता है।
 * - उनसे विशिष्ट कोड की प्रतिलिपि बनाएँ
 * – बताता है कि आपका एक्सटेंशन क्लाइंट्स को API कैसे प्रदान कर सकता है
 * एक्सटेंशनों के लिए सर्वोत्तम प्रथाएँ
 * एक्सटेंशनों के लिए सर्वोत्तम प्रथाएँ
 * एक्सटेंशनों के लिए सर्वोत्तम प्रथाएँ
 * एक्सटेंशनों के लिए सर्वोत्तम प्रथाएँ