Velora Player

إضافة ووردبريس توفّر مشغّل صوت حديث مع دعم:

• بلوك
• Gutenberg
• shortcode
• ثيمات جاهزة
• لوحة إعدادات
• تتبّع بسيط لعدد مرات التشغيل

نظرة سريعة

هذه الإضافة تبني مشغّل صوت مخصص يمكن استخدامه داخل محرر ووردبريس أو عبر shortcode في الصفحات والمقالات.
المشغّل يدعم صورة غلاف، عنوان للمسار الصوتي، شريط تقدّم، زر تشغيل وإيقاف، وثيمات عرض مختلفة.
كما تحتوي الإضافة على نظام تحليلات بسيط يحسب عدد مرات التشغيل لكل ملف صوتي.

الميزات الرئيسية

• بلوك مخصص داخل محرر ووردبريس باسم Velora Player
• دعم العرض الديناميكي من السيرفر
• دعم الإدراج باستخدام [audio_player]
• ثلاث ثيمات جاهزة: modern-dark ، glassmorphism ، podcast-style
• إعدادات عامة للتحكم في الألوان، الحواف، والثيم الافتراضي
• صفحة تحليلات داخل لوحة التحكم
• واجهة REST API لتسجيل التشغيلات

كيف تعمل الإضافة

1. ملف التشغيل الرئيسي

الملف: modern-audio-player.php

وظيفته:

• تعريف معلومات الإضافة
• تعريف الثوابت الأساسية
• تحميل الكلاسات
• تنفيذ activation hook لإنشاء الإعدادات الافتراضية وجدول التحليلات
• تشغيل الكلاس الرئيسي

2. الكلاس الرئيسي

الملف: includes/class-plugin.php

وظيفته:

• تهيئة الخدمات الأساسية:
  • الإعدادات
  • لوحة التحكم
  • الـ shortcode
  • REST API
• تحميل الترجمة
• تسجيل البلوك من خلال block.json
• استخدام render_callback لعرض المشغّل من السيرفر

3. الإعدادات

الملف: includes/class-settings.php

يحتوي على:

• القيم الافتراضية للإضافة
• قراءة الإعدادات من قاعدة البيانات
• تنظيف القيم قبل الحفظ

الإعدادات المتوفرة:

• الثيم الافتراضي
• الثيمات المفعّلة
• لون التمييز
• لون الخلفية
• لون النص
• درجة استدارة الحواف
• إظهار صورة الغلاف أو إخفاؤها

4. لوحة التحكم

الملف: admin/class-admin.php

يوفّر صفحتين داخل لوحة تحكم ووردبريس:

• صفحة إعدادات
• صفحة تحليلات

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

5. العرض

الملف: includes/class-renderer.php

هذا الملف هو المسؤول عن بناء HTML الخاص بالمشغّل.

أهم ما يفعله:

• يجهّز الخصائص القادمة من البلوك أو الـ shortcode
• يطبّق الثيم الافتراضي إذا لزم الأمر
• يبني متغيرات CSS اعتمادًا على إعدادات الإضافة
• يضيف بيانات التحليلات داخل data-* attributes
• يعرض نسخة معاينة داخل المحرر إذا لم يتم اختيار ملف صوتي بعد
• يحمّل ملفات الواجهة الأمامية عند العرض الديناميكي أو عند استخدام الـ shortcode

6. الـ shortcode

الملف: includes/class-shortcode.php

يسجّل [audio_player]

الخصائص المدعومة:

• src
• title
• image
• theme

مثال:

[audio_player src="https://example.com/audio.mp3" title="Episode 1" image="https://example.com/cover.jpg" theme="glassmorphism"]

إذا لم يتم تمرير theme فسيتم استخدام الثيم الافتراضي من إعدادات الإضافة.

7. التحليلات

الملف: includes/class-analytics.php

وظيفته:

• إنشاء جدول خاص في قاعدة البيانات عند تفعيل الإضافة
• إنشاء hash ثابت لكل رابط صوتي
• تسجيل كل تشغيل في قاعدة البيانات
• إرجاع ملخص عام
• إرجاع أكثر الملفات تشغيلًا

اسم الجدول يكون بصيغة:

{wp_prefix}map_analytics

كل سجل يحتوي على معلومات مثل:

• رابط الملف الصوتي
• عنوانه
• عدد مرات التشغيل
• آخر وقت تشغيل

8. واجهة REST API

الملف: includes/class-rest-api.php

تسجّل المسار التالي:

/wp-json/map/v1/track-play

الطلب من نوع:

POST

ويستقبل:

• src
• title
• hash
• nonce

قبل تسجيل التشغيل يتم التحقق من:

• وجود القيم المطلوبة
• صحة hash
• صحة nonce

9. جافاسكربت الواجهة

الملف: assets/js/player.js

هذا الملف يدير سلوك المشغّل على الواجهة، مثل:

• تشغيل وإيقاف الصوت
• تحديث الوقت الحالي والمدة
• تحديث شريط التقدم
• الانتقال داخل الملف الصوتي
• إرسال أول تشغيل فقط إلى REST API لكل نسخة من المشغّل داخل الصفحة

10. بلوك المحرر

الملف: assets/js/block-editor.js

هذا الملف يسجل البلوك داخل المحرر ويضيف:

• اختيار ملف صوتي من المكتبة
• إدخال عنوان المسار
• اختيار صورة غلاف
• تفعيل أو تعطيل الثيم العام
• اختيار ثيم مخصص
• معاينة مباشرة باستخدام ServerSideRender

11. التنسيق

الملف: assets/css/player.css

يحتوي على تنسيقات المشغّل، والثيمات المختلفة، والاستجابة للشاشات الصغيرة.

طريقة الاستخدام

استخدام البلوك

من داخل محرر ووردبريس:

1. أضف بلوك Velora Player
2. اختر الملف الصوتي
3. أضف العنوان وصورة الغلاف
4. حدّد هل تريد استخدام الثيم العام أو ثيم مخصص

استخدام shortcode

مثال بسيط:

[audio_player src="https://example.com/audio.mp3" title="My Track"]

مثال كامل:

[audio_player src="https://example.com/audio.mp3" title="Podcast Episode" image="https://example.com/image.jpg" theme="podcast-style"]

الثيمات المتوفرة

modern-dark

ثيم داكن عالي التباين مناسب للتصميمات الحديثة.

glassmorphism

ثيم شفاف بتأثير زجاجي وخلفية ضبابية.

podcast-style

ثيم أقرب لعرض حلقات البودكاست والمحتوى التحريري.

تدفق العمل داخل الإضافة

بشكل مبسط، التسلسل كالتالي:

1. يتم تحميل الإضافة من الملف الرئيسي.
2. يتم تسجيل البلوك والـ shortcode وصفحات الإدارة.
3. عند إدراج المشغّل، يتم تمرير الخصائص إلى Renderer
4. يتم إنشاء HTML وبيانات التتبع.
5. في الواجهة، يتولى player.js تشغيل الصوت وتحديث الواجهة.
6. عند أول تشغيل، يتم إرسال طلب إلى REST API
7. تقوم طبقة التحليلات بتحديث قاعدة البيانات.

بنية الملفات

modern-audio-player/
├── modern-audio-player.php
├── uninstall.php
├── README.md
├── admin/
│   └── class-admin.php
├── includes/
│   ├── class-plugin.php
│   ├── class-settings.php
│   ├── class-renderer.php
│   ├── class-shortcode.php
│   ├── class-rest-api.php
│   └── class-analytics.php
├── blocks/
│   └── block.json
└── assets/
    ├── css/
    │   ├── player.css
    │   └── editor.css
    └── js/
        ├── player.js
        ├── block-editor.js
        ├── player.asset.php
        └── block-editor.asset.php

ملاحظات مهمة

• الإضافة تعتمد على العرض الديناميكي، لذلك دالة save داخل البلوك ترجع null
• ملفات الواجهة يتم تحميلها عبر block.json وميتاداتا الأصول
• عند استخدام الـ shortcode يتم تحميل ملفات الواجهة أيضًا من خلال Renderer::enqueue_block_assets()

إزالة الإضافة

يوجد ملف: uninstall.php

ويمكن استخدامه لاحقًا لتنظيف بيانات الإضافة عند الحذف النهائي إذا أردت توسيع سلوك الإزالة.

ملخص

هذه الإضافة مناسبة عندما تحتاج إلى:

• مشغّل صوت مخصص بدل المشغّل الافتراضي
• دعم للمحرر الحديث
• تخصيص مظهر عام على مستوى الموقع
• تتبّع بسيط لمرات التشغيل بدون نظام تحليلات معقّد