السلام عليكم ورحمة الله وبركاته جميعًا.
قبل فترة شارك الأخ @Hossam Hassan خبرًا مفاده إتاحة منصة كلمات لواجهاتها البرمجية (Kalimat API) مجاناً للاستخدام الشخصي في موضوع على المجتمع، ولذلك أشارككم اليوم تجربة عملية وتطبيقًا مباشرًا لكيفية استغلالها في بيئة تطوير حقيقية.
فقد طورت إضافة ووردبريس باسم (Midad Quran Inserter) تضيف مكونًا جديدًا في محرر جوتنبرج الافتراضي في ووردبريس يسمح بالبحث عن أي آية في القرآن بالاعتماد على Kalimat API، ويدرجها بالرسم العثماني ضمن المقالة أو الصفحة.
الهدف من المشروع هو تجريب دقة وسرعة محرك بحث Kalimat، وبنفس الوقت توفير أداة مجانية وعملية للمدونين وأصحاب المواقع الإسلامية لإدراج الآيات القرآنية في مقالاتهم ضمن مواقعهم الشخصية بسهولة.
وتكمن الأهمية الكبرى لهذه الإضافة في معالجتها لمشكلة شائعة، وهي وقوع أخطاء إملائية غير مقصودة عند كتابة الآيات القرآنية يدويًا، إلى جانب توفيرها للوقت والجهد المبذولين في عملية البحث عن الآيات في مصادر خارجية، ثم نسخها ولصقها وتنسيقها في المحرر.
وتجدر الإشارة إلى أن الواجهة البرمجية لمنصة Kalimat مجانية ومخصصة للاستخدام الشخصي وغير التجاري في الوقت الحالي.
هيكلية الإضافة وآلية العمل
لضمان أن تكون الإضافة عالية الأداء والأمان، لم أربط الواجهة الأمامية للمحرر بـ Kalimat API بشكل مباشر، بل اعتمدت على هيكلية تفصل بين المهام:
- الواجهة الخلفية والإعدادات (PHP): أنشأت صفحة إعدادات مخصصة في لوحة تحكم ووردبريس لتخزين مفتاح واجهة برمجة التطبيقات (X-Api-Key) الخاص بالمستخدم بشكل آمن.
- نقطة اتصال وسيطة (REST API Proxy): لحماية المفتاح ومنعه من الظهور في المتصفح، سجلت مسارًا وسيطًا داخل ووردبريس، حيث يستقبل هذا المسار استعلام البحث، ويرسل الطلب إلى api.kalimat.dev، ويقوم بتهيئة البيانات المسترجعة قبل إرسالها للمحرر.
- الواجهة الأمامية للمكوّن (React/JS): قمت ببناء المكون باستخدام أدوات ووردبريس التفاعلية (wp.element, wp.components) لتوفير تجربة بحث سلسة، ووفرت فيها إمكانية الاطلاع على نتائج البحث، وإدراج الآية المطلوبة بنقر واحدة، بالإضافة إلى إزالتها والبحث مجددًا.
أبرز مميزات الإضافة
- مرونة في البحث، حيث تدعم البحث بكلمات عربية، أو عبر استخدام صيغة رقمية (رقم السورة:رقم الآية) لإظهار آية مطلوبة مباشرة، مثل البحث عن 2:255 لإظهار آية الكرسي.
- الرسم العثماني، اعتمدت على خط Amiri Quran لعرض النص القرآني لكونه يدعم الرسم العثماني، ولتمييزه عن نص آخر في المقالة.
- سرعة عالية، فخلال الاستخدام العملي للإضافة، كانت الاستجابة سريعة بفضل البنية التحتية الممتازة التي تعتمد عليها Kalimat API، بالإضافة إلى كفاءة نقطة الاتصال الوسيطة (Proxy) في ووردبريس التي تقوم بمعالجة النتائج وإظهارها للمحرر بشكل شبه لحظي.
- جاهزة للترجمة، إذ كافة النصوص المعروضة مغلفة بدوال الترجمة، وتدعم اللغتين العربية والإنجليزية.
طريقة استخدام الإضافة
لاستخدام الإضافة أو تجريبها في موقعك، قم بتحميلها من مستودعها على GitHub على شكل ملف zip، ثم ارفع الملف إلى ووردبريس من خلال الإضافات > أضف إضافة جديدة > رفع إضافة، ثم فعلها.
وبعد ذلك قم بطلب مفتاح API مجاني من منصة Kalimat.dev، وانتظر حتى يصلك على الإيميل، ثم توجه إلى الإعدادات > مداد للقرآن في ووردبريس وأدخل المفتاح، واحفظ التغييرات.
وبعد ذلك في محرر المكونات (Gutenberg)، أضف مكون Midad Quran Inserter، ثم ابحث، وأدرج الآية التي تريدها مباشرة، وفي هذا الفيديو يوجد شرح لكيفية استخدام الإضافة.
الإضافة مفتوحة المصدر بالكامل ومتاحة تحت رخصة (GPL-2.0).
أرغب بأن تشاركوني آراءكم التقنية حول فكرة بناء Proxy Endpoint داخل ووردبريس لحماية مفتاح API بدلاً من استدعائها من الـ Frontend مباشرة، هل برأيكم هذه أفضل ممارسة؟ وما رأيكم بأداء الإضافة؟
