363 lines
9.4 KiB
Markdown
363 lines
9.4 KiB
Markdown
# 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`
|
|
|
|
مثال:
|
|
|
|
```text
|
|
[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`
|
|
ثابت لكل رابط صوتي
|
|
- تسجيل كل تشغيل في قاعدة البيانات
|
|
- إرجاع ملخص عام
|
|
- إرجاع أكثر الملفات تشغيلًا
|
|
|
|
اسم الجدول يكون بصيغة:
|
|
|
|
```text
|
|
{wp_prefix}map_analytics
|
|
```
|
|
|
|
كل سجل يحتوي على معلومات مثل:
|
|
|
|
- رابط الملف الصوتي
|
|
- عنوانه
|
|
- عدد مرات التشغيل
|
|
- آخر وقت تشغيل
|
|
|
|
### 8. واجهة REST API
|
|
|
|
الملف:
|
|
`includes/class-rest-api.php`
|
|
|
|
تسجّل المسار التالي:
|
|
|
|
```text
|
|
/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
|
|
|
|
مثال بسيط:
|
|
|
|
```text
|
|
[audio_player src="https://example.com/audio.mp3" title="My Track"]
|
|
```
|
|
|
|
مثال كامل:
|
|
|
|
```text
|
|
[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. تقوم طبقة التحليلات بتحديث قاعدة البيانات.
|
|
|
|
## بنية الملفات
|
|
|
|
```text
|
|
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`
|
|
|
|
ويمكن استخدامه لاحقًا لتنظيف بيانات الإضافة عند الحذف النهائي إذا أردت توسيع سلوك الإزالة.
|
|
|
|
## ملخص
|
|
|
|
هذه الإضافة مناسبة عندما تحتاج إلى:
|
|
|
|
- مشغّل صوت مخصص بدل المشغّل الافتراضي
|
|
- دعم للمحرر الحديث
|
|
- تخصيص مظهر عام على مستوى الموقع
|
|
- تتبّع بسيط لمرات التشغيل بدون نظام تحليلات معقّد
|