إنشاء البرنامج المساعد¶

سنتعمق في هذا الدليل في كيفية إنشاء مكون إضافي لـ Climweb، ونناقش بنية المكون الإضافي ونقدم مثالًا للمكون الإضافي للحصول على الإلهام ومناقشة كيفية نشر المكون الإضافي الخاص بك.

بنية البرنامج المساعد¶

يعد ClimWeb Plugin في الأساس مجلدًا يحمل اسم المكون الإضافي. يجب أن يكون المجلد Django/Wagtail App

قم بتهيئة البرنامج المساعد الخاص بك من قالب البرنامج المساعد¶

قالب المكون الإضافي هو قالب cookiecutter الذي ينشئ مكونًا إضافيًا بالبنية والملفات المطلوبة. وهذا يضمن أن البرنامج المساعد يتبع البنية المتوقعة ويمكن تثبيته بسهولة في climweb.

لإنشاء مثيل للقالب، قم بتنفيذ الأوامر التالية من الدليل الذي تريد إنشاء البرنامج الإضافي فيه:

pip install cookiecutter
cookiecutter gh:wmo-raf/climweb --directory plugin-boilerplate

للحصول على مزيد من التفاصيل حول استخدام النموذج المعياري للمكونات الإضافية، يمكنك اتباع دليل خطوة بخطوة حول إنشاء مكون إضافي باستخدام النموذج النموذجي للمكونات الإضافية.

واجهة برمجة تطبيقات تثبيت البرنامج المساعد¶

تحتوي صورة Climweb docker على نصوص bash التالية المستخدمة لتثبيت المكونات الإضافية. يمكن استخدامها لتثبيت مكون إضافي في حاوية adl موجودة في وقت التشغيل. يمكن استخدام install_plugin.sh لتثبيت مكون إضافي من عنوان url أو git repo أو مجلد محلي على نظام الملفات.

يمكنك العثور على هذه البرامج النصية في المواقع التالية في الصور المضمنة:

/deploy/plugins/install_plugin.sh

في هذا الريبو، يمكنك العثور على البرامج النصية في المجلد "deploy/plugins".

تتوقع هذه البرامج النصية أن يتبع مكون ClimWeb الإضافي الاتفاقيات الموضحة أدناه:

هيكل ملف البرنامج المساعد¶

يتوقع البرنامج النصي install_plugin.sh أن يكون للمكون الإضافي الخاص بك بنية محددة كما يلي:

├── plugin_name
│  ├── climweb_plugin_info.json (A simple json file containing info about your plugin)
|  ├── setup.py
|  ├── build.sh (Called when installing the plugin in a Dockerfile/container)
|  ├── runtime_setup.sh (Called on first runtime startup of the plugin)
|  ├── uninstall.sh (Called when uninstalling the plugin in a container)
|  ├── src/plugin_name/src/config/settings/settings.py (Optional Django setting file)

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

build.sh: يتم استدعاؤه عند بدء تشغيل الحاوية في حالة حدوث تثبيت وقت التشغيل.
runtime_setup.sh: يتم استدعاؤه عند بدء تشغيل الحاوية لأول مرة بعد تثبيت المكون الإضافي، وهو مفيد لتشغيل أوامر المستخدم المتميز على الحاوية.
uninstall.sh: عند الاتصال بـ uninstall، ستكون قاعدة البيانات متاحة ولذلك يجب تشغيل أي عمليات ترحيل عكسية هنا.

ملف معلومات البرنامج المساعد¶

الملف "climweb_plugin_info.json" هو ملف json، موجود في مجلد المكون الإضافي الجذري، ويحتوي على بيانات تعريف حول المكون الإضافي الخاص بك. يجب أن يحتوي على بنية JSON التالية:

{
  "name": "TODO",
  "version": "TODO",
  "description": "TODO",
  "author": "TODO",
  "author_url": "TODO",
  "url": "TODO",
  "license": "TODO",
  "contact": "TODO"
}

بنية البرنامج المساعد المتوقعة عند التثبيت من مستودع git¶

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

افتراضيًا، يُنشئ النص المعياري للمكونات الإضافية مستودعًا بهذه البنية.

على سبيل المثال، يجب أن يحتوي git repo المطابق على شيء مثل:

├─ * (an outermost wrapper directory named anything is allowed but not required) 
│  ├── plugins/ 
│  │  ├── plugin_name
│  |  |  ├── climweb_plugin_info.json
|  |  |  ├── setup.py
|  |  |  ├── build.sh
|  |  |  ├── runtime_setup.sh
|  |  |  ├── uninstall.sh
|  |  |  ├── src/plugin_name/src/config/settings/settings.py (Optional Django setting file)

البرنامج المساعد النموذجي¶

باستخدام النموذج المعياري للمكونات الإضافية، يمكنك بسهولة إنشاء مكون إضافي جديد وإعداد بيئة تطوير عامل إرساء تقوم بتثبيت adl باعتباره تبعية. يمكن تثبيت هذا بسهولة عبر ملف تعريف الارتباط.

إنشاء البرنامج المساعد¶

لاستخدام النموذج النموذجي للمكونات الإضافية، يجب عليك أولاً تثبيت أداة Cookiecutter ("pip install cookiecutter`).

بمجرد تثبيت Cookiecutter، يمكنك تنفيذ الأمر التالي لإنشاء مكون إضافي ADL جديد من القالب الخاص بنا. في هذا الدليل، سنقوم بتسمية المكون الإضافي الخاص بنا "My Climweb Plugin"، ومع ذلك يمكنك اختيار اسم المكون الإضافي الخاص بك عندما يطلب منك Cookiecutter ذلك.

ملاحظة

تعتمد وحدة python على اسم البرنامج المساعد الذي اخترته. إذا استخدمنا على سبيل المثال "My Climweb Plugin"، فيجب أن يكون اسم تطبيق Django هو my_climweb_plugin

cookiecutter gh:wmo-raf/climweb --directory plugin-boilerplate
project_name [My Climweb Plugin]: 
project_slug [my-climweb-plugin]: 
project_module [my_climweb_plugin]:

إذا لم تشاهد أي أخطاء، فهذا يعني أنه تم إنشاء المكون الإضافي الخاص بك.

كتابة البرنامج المساعد¶

لقد قمت الآن بإنشاء مكون إضافي، دعنا نتناول المزيد من التفاصيل حول كيفية توسيع Climweb وتخصيصه باستخدام المكون الإضافي الخاص بك.

حالة التخزين¶

إذا كان المكون الإضافي الخاص بك يحتاج إلى تخزين الحالة، فيجب عليك القيام بذلك فقط في:

قاعدة البيانات المستخدمة من قبل Climweb
استخدام آلية التخزين الافتراضية لـ Django
يتم استخدام Redis بواسطة Climweb، ولكن فقط للحالة غير المستمرة مثل ذاكرة التخزين المؤقت التي يمكن تدميرها في أي لحظة.

ملاحظة

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

إضافة متطلبات بايثون¶

المكون الإضافي الخاص بك هو مجرد وحدة لغة بايثون عادية سيتم تثبيتها في بيئة Climweb الافتراضية باستخدام "pip" بواسطة "install_plugin.sh". في حالة استخدام البرنامج المساعد، يمكنك إضافة أي متطلبات لبايثون إلى ملف متطلبات النقطة الموجود في requirements/base.txt.

باعتباره تطبيق Django/Wagtail¶

عند بدء تشغيل خدمة Climweb Django، فإنها تبحث عن أي مكونات إضافية في دليل المكونات الإضافية. إذا وجد أي شيء، فإنه يفترض أن المجلد الفرعي src/plugin_name/ يحتوي على تطبيق Django ويضيفه إلى INSTALLED_APPS. هذا يعني أن المكون الإضافي الخاص بك يجب أن يكون تطبيق Django/Wagtail ويتطابق اسمه تمامًا مع اسم مجلد البرنامج الإضافي.

في تطبيق Django/Wagtail الخاص بالمكون الإضافي الخاص بك، يمكنك القيام بأي شيء يمكنك القيام به عادةً باستخدام تطبيق Django/Wagtail مثل إجراء عمليات الترحيل، واستخدام طريقة ready() للقيام بتكوين بدء التشغيل وما إلى ذلك.

نشر البرنامج المساعد الخاص بك¶

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