update README
This commit is contained in:
diyaa
parent
b7c0d49d63
commit
b05739b916
373
README.md
373
README.md
@ -1,362 +1,87 @@
|
||||
# Velora Player
|
||||
|
||||
إضافة ووردبريس توفّر مشغّل صوت حديث مع دعم:
|
||||
إضافة ووردبريس تضيف مشغّل صوت أنيق يمكن إدراجه داخل المحرر أو عبر `shortcode`.
|
||||
|
||||
- بلوك
|
||||
- Gutenberg
|
||||
- shortcode
|
||||
- ثيمات جاهزة
|
||||
- لوحة إعدادات
|
||||
- تتبّع بسيط لعدد مرات التشغيل
|
||||
## ماذا تفعل الإضافة؟
|
||||
|
||||
## نظرة سريعة
|
||||
- تعرض ملف صوتي واحد أو `playlist`
|
||||
- تعمل داخل Gutenberg كبلوك
|
||||
- تعمل أيضًا عبر `shortcode`
|
||||
- تدعم صورة غلاف وعنوان للمسار
|
||||
- تحتوي على ثيمات جاهزة
|
||||
- تسجّل عدد مرات التشغيل بشكل بسيط
|
||||
|
||||
هذه الإضافة تبني مشغّل صوت مخصص يمكن استخدامه داخل محرر ووردبريس أو عبر
|
||||
`shortcode`
|
||||
في الصفحات والمقالات.
|
||||
المشغّل يدعم صورة غلاف، عنوان للمسار الصوتي، شريط تقدّم، زر تشغيل وإيقاف، وثيمات عرض مختلفة.
|
||||
كما تحتوي الإضافة على نظام تحليلات بسيط يحسب عدد مرات التشغيل لكل ملف صوتي.
|
||||
## طريقة الاستخدام
|
||||
|
||||
## الميزات الرئيسية
|
||||
### 1. من محرر ووردبريس
|
||||
|
||||
- بلوك مخصص داخل محرر ووردبريس باسم
|
||||
`Velora Player`
|
||||
- دعم العرض الديناميكي من السيرفر
|
||||
- دعم الإدراج باستخدام
|
||||
`[audio_player]`
|
||||
- ثلاث ثيمات جاهزة:
|
||||
`modern-dark`
|
||||
،
|
||||
`glassmorphism`
|
||||
،
|
||||
`podcast-style`
|
||||
- إعدادات عامة للتحكم في الألوان، الحواف، والثيم الافتراضي
|
||||
- صفحة تحليلات داخل لوحة التحكم
|
||||
- واجهة
|
||||
`REST API`
|
||||
لتسجيل التشغيلات
|
||||
- افتح الصفحة أو المقالة
|
||||
- أضف بلوك `Velora Player`
|
||||
- اختر الملف الصوتي
|
||||
- أضف العنوان وصورة الغلاف إذا رغبت
|
||||
- اختر الثيم أو اترك الإعداد الافتراضي
|
||||
- انشر الصفحة
|
||||
|
||||
## كيف تعمل الإضافة
|
||||
### 2. باستخدام shortcode
|
||||
|
||||
### 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`
|
||||
فسيتم استخدام الثيم الافتراضي من إعدادات الإضافة.
|
||||
### 3. استخدام Playlist داخل shortcode
|
||||
|
||||
### 7. التحليلات
|
||||
|
||||
الملف:
|
||||
`includes/class-analytics.php`
|
||||
|
||||
وظيفته:
|
||||
|
||||
- إنشاء جدول خاص في قاعدة البيانات عند تفعيل الإضافة
|
||||
- إنشاء
|
||||
`hash`
|
||||
ثابت لكل رابط صوتي
|
||||
- تسجيل كل تشغيل في قاعدة البيانات
|
||||
- إرجاع ملخص عام
|
||||
- إرجاع أكثر الملفات تشغيلًا
|
||||
|
||||
اسم الجدول يكون بصيغة:
|
||||
يمكن تمرير `playlist` كسطور، وكل سطر بهذا الشكل:
|
||||
|
||||
```text
|
||||
{wp_prefix}map_analytics
|
||||
العنوان|رابط الصوت|رابط الصورة
|
||||
```
|
||||
|
||||
كل سجل يحتوي على معلومات مثل:
|
||||
|
||||
- رابط الملف الصوتي
|
||||
- عنوانه
|
||||
- عدد مرات التشغيل
|
||||
- آخر وقت تشغيل
|
||||
|
||||
### 8. واجهة REST API
|
||||
|
||||
الملف:
|
||||
`includes/class-rest-api.php`
|
||||
|
||||
تسجّل المسار التالي:
|
||||
مثال:
|
||||
|
||||
```text
|
||||
/wp-json/map/v1/track-play
|
||||
[audio_player playlist="Episode 1|https://example.com/ep1.mp3|https://example.com/ep1.jpg
|
||||
Episode 2|https://example.com/ep2.mp3|https://example.com/ep2.jpg" theme="podcast-style"]
|
||||
```
|
||||
|
||||
الطلب من نوع:
|
||||
إذا تم استخدام `playlist` فسيتم تشغيل المسارات من داخل نفس المشغّل.
|
||||
|
||||
`POST`
|
||||
## الخيارات المتاحة في shortcode
|
||||
|
||||
ويستقبل:
|
||||
|
||||
- `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"]
|
||||
```
|
||||
- `src` رابط الملف الصوتي
|
||||
- `title` عنوان المسار
|
||||
- `image` صورة الغلاف
|
||||
- `playlist` قائمة تشغيل
|
||||
- `theme` الثيم
|
||||
|
||||
## الثيمات المتوفرة
|
||||
|
||||
### modern-dark
|
||||
- `modern-dark`
|
||||
- `glassmorphism`
|
||||
- `podcast-style`
|
||||
|
||||
ثيم داكن عالي التباين مناسب للتصميمات الحديثة.
|
||||
## الإعدادات
|
||||
|
||||
### glassmorphism
|
||||
من لوحة التحكم:
|
||||
|
||||
ثيم شفاف بتأثير زجاجي وخلفية ضبابية.
|
||||
`Velora Player > Design Settings`
|
||||
|
||||
### podcast-style
|
||||
يمكنك تعديل:
|
||||
|
||||
ثيم أقرب لعرض حلقات البودكاست والمحتوى التحريري.
|
||||
- الثيم الافتراضي
|
||||
- الألوان
|
||||
- الحواف والمسافات
|
||||
- إظهار صورة الغلاف
|
||||
|
||||
## تدفق العمل داخل الإضافة
|
||||
## التحليلات
|
||||
|
||||
بشكل مبسط، التسلسل كالتالي:
|
||||
من لوحة التحكم:
|
||||
|
||||
1. يتم تحميل الإضافة من الملف الرئيسي.
|
||||
2. يتم تسجيل البلوك والـ shortcode وصفحات الإدارة.
|
||||
3. عند إدراج المشغّل، يتم تمرير الخصائص إلى
|
||||
`Renderer`
|
||||
4. يتم إنشاء
|
||||
HTML
|
||||
وبيانات التتبع.
|
||||
5. في الواجهة، يتولى
|
||||
`player.js`
|
||||
تشغيل الصوت وتحديث الواجهة.
|
||||
6. عند أول تشغيل، يتم إرسال طلب إلى
|
||||
`REST API`
|
||||
7. تقوم طبقة التحليلات بتحديث قاعدة البيانات.
|
||||
`Velora Player > Analytics`
|
||||
|
||||
## بنية الملفات
|
||||
ستجد:
|
||||
|
||||
```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`
|
||||
|
||||
ويمكن استخدامه لاحقًا لتنظيف بيانات الإضافة عند الحذف النهائي إذا أردت توسيع سلوك الإزالة.
|
||||
|
||||
## ملخص
|
||||
|
||||
هذه الإضافة مناسبة عندما تحتاج إلى:
|
||||
|
||||
- مشغّل صوت مخصص بدل المشغّل الافتراضي
|
||||
- دعم للمحرر الحديث
|
||||
- تخصيص مظهر عام على مستوى الموقع
|
||||
- تتبّع بسيط لمرات التشغيل بدون نظام تحليلات معقّد
|
||||
- إجمالي التشغيلات
|
||||
- أكثر الملفات تشغيلًا
|
||||
- ملخصًا بسيطًا لاستخدام المشغّل
|
||||
|
||||
Loading…
Reference in New Issue
Block a user