🇬🇧 English Version: Read the original article in English here.

بدلة الحرباء: ليه تخصيص الثيمات التقليدي في Oracle APEX بيحبسك؟ (وإزاي تفلت منه) 🦎👔

الجزء الأول من السلسلة التقنية الشاملة: بناء وإدارة أنظمة التصميم المتقدمة في Oracle APEX.

⚡ الخلاصة في كلمتين (TL;DR)

تخيل رحت اشتريت بدلة توكسيدو إيطالي فاخرة بـ 3,000 دولار. أول يوم في الفرح شكلها يجنن ومضبوطة بالمللي. بس المفاجأة إن الترزي بعد ما لبسهالك، راح لاحم الجاكيت والصديري والبنطلون في جلد جسمك بـ “سوبر جلو” حديدي دائم!

حبيت تروح تجري على البحر الصبح؟ هتجري بالتوكسيدو. نزلت تغير زيت عربيتك في ورشة الحرفيين؟ هتغير الزيت بالتوكسيدو والبيبيون. معزوم على شواء في عز أغسطس؟ مبروك عليك صوف صامد في حرارة 42 درجة مئوية!

ده بالضبط اللي بيحصل لما تقرر تعدل وتعمل تخصيص لمظهر تطبيقاتك في Oracle APEX باستخدام أداة Theme Roller التقليدية. بتلاقي نفسك حابس كل الشاشات، وكل المستخدمين، وكل النوافذ المنبثقة (Modal Dialogs) جوه ملف CSS ضخم ملحوم في التطبيق للأبد.

في أول مقال من سلسلتنا الجديدة APEX Theme Factory، هنكسر قيد “البدلة الملحومة”. هنتعلم إزاي نحول الثيمات من مجرد وشم دائم ملوش حل لـ بدلة فضاء معيارية سريعة التبديل مبنية فوق Universal Theme 42 بنمط Iris—بدون تعديل سطر كود واحد، وبدون ما نكسر اشتراك الثيم الأصلي، ومع إمكانية التراجع الكامل بضغطة زر واحدة. 🚀

📦 مستودع كود المشروع: كود المحرك، وحزم الثيمات، وسكربتات التثبيت متاحة بالكامل على github.com/ash2osh/APEX_THEME_FACTORY.

🦎 فزورة الحرباء: حكاية دولابين ملابس

كل مطور في بيئات الشركات بيصطدم في مرحلة ما بـ “فخ دولاب الملابس”:

┌────────────────────────────────────────┐       ┌────────────────────────────────────────┐
│      التخصيص التقليدي في أبيكس         │       │          محرك APEX Theme Factory       │
│         (البدلة الملحومة بالأمير)      │       │        (بدلة الفضاء المعيارية)         │
├────────────────────────────────────────┤       ├────────────────────────────────────────┤
│ • ملف CSS متضخم جوه Theme Roller       │       │ • حزم معزولة بنطاق محدد على <html>     │
│ • تلوث عشوائي لعناصر :root عالمياً     │       │ • متغيرات تصميم مخصصة (--app-*)        │
│ • شكل واحد إجباري لكل المستخدمين       │       │ • تبديل فوري لكل مستخدم وجهاز          │
│ • رعب من كسر اشتراك Universal Theme    │       │ • احتفاظ كامل باشتراك الثيم 42         │
│ • الحذف محتاج دعاء وستر ربنا           │       │ • تجربة جافة (Dry-Run) وحذف ذري آمن    │
└────────────────────────────────────────┘       └────────────────────────────────────────┘

في الواقع العملي للشركات، مستخدمين نظامك مش شغالين في نفس الظروف:

مشرف المخازن في الوردية الليلية: محتاج نمط مظلم فائق التباين (Dark Mode) عشان شاشات التابلت ماتعميش عينيه في عتمة المستودع.
محاسب التكاليف والمراجعة: محتاج واجهة ناصعة وهادية شبه الورق (Linen)، مع خطوط جداول دقيقة تسهل مطابقة آلاف الفواتير في شاشات التقارير التفاعلية (Interactive Grids).
الإدارة التنفيذية ومجلس الإدارة: محتاجين واجهة كحلي مع بطاقات مؤشرات أداء لامعة (Telemetry Cards) تناسب شاشات العرض الكبيرة في غرف الاجتماعات.

تاريخياً، عشان تعمل كده في أوراكل أبيكس كنت بتضطر تعمل كذا نسخة من نفس التطبيق، أو تحشر تعديلات CSS بتعمل تضارب عنيف مع كل ترقية جديدة لنظام أبيكس.

🪤 الأفخاخ التلاتة في تلوين أبيكس التقليدي

1. كتلة الـ Theme Roller الصامتة

أداة Theme Roller لما بتغير فيها ألوان أو حواف بيتم تجميع ملف CSS ضخم وربطه بالتطبيق. ولو حبيت تعمل تعديل إضافي، بتضطر تفتح صندوق الـ Custom CSS وتحط أكوادك هناك.

في ظرف شهور، الصندوق ده بيتحول لـ “مقبرة برمجية” فيها أكتر من 2,000 سطر مليانين علامات !important، ومحددات عناصر قديمة، وألوان Hex صلبة. وأول ما أوراكل تنزل ترقية جديدة لأبيكس، المحددات دي بتفرقع وتخرب تنسيق الأزرار والقوائم.

2. معضلة اشتراك الـ Universal Theme 42

الثيم الموحد Universal Theme 42 هو أحد أعظم مزايا أوراكل أبيكس. الاشتراك فيه (Subscription) بيضمن إن شاشاتك تاخد أحدث تحسينات الأمان، وسرعة الأداء، وإمكانية الوصول لمتحدي الإعاقة (Accessibility - a11y) مع كل تحديث جديد.

لكن المطور اللي بيحاول يغير القوالب (Templates) بنفسه بيكسر الاشتراك ده فجأة، وساعتها بيبقى معزول في جزيرة فنية لوحده ومضطر يصين كل قوالب الـ HTML والـ JavaScript بإيديه.

3. صدمة نمط Iris في APEX 26.1

مع إصدار Oracle APEX 26.1، ظهر النمط الأحدث Iris. نمط متطور جداً وجديد هندسياً، وبيعتمد على مئات المتغيرات البرمجية من الـ CSS Tokens كالتالي:

أكتر من 1,000 ذرة داخلية للمكونات (--a-*).
أكتر من 400 توكن أساسي لألوان ومسافات الثيم (--ut-*).
أكتر من 100 توكن للأدوات المساعدة (--u-*).

/* قراءة المتغيرات البرمجية المباشرة من نمط Iris في APEX 26.1 */
:root {
  --ut-color-scheme: light;
  --ut-palette-primary: #00688c;
  --ut-body-background-color: #fbf9f8;
  --ut-component-background-color: #fff;
  --a-base-font-weight-semibold: 500;
}

المفاجأة هنا إن Iris بينزل بنمط فاتح فقط (Light-Only)!

مفيش أي سطر للنمط المظلم (Dark Mode) جوه ملف Iris.min.css. ولو حاولت تعمل ثيم مظلم عبر تغيير --ut-body-background-color على مستوى الـ :root، هتلاقي النوافذ المنبثقة وشاشات الـ Popup LOV باظت وبقى الكلام فيها غير مقروء تماماً!

🛡️ الحل: محرك APEX Theme Factory

فكرة APEX Theme Factory بتعتمد على فلسفة هندسية بسيطة ولكنها عبقرية: بدل ما تلمس الـ Theme Roller أو تبوظ جداول قاعدة البيانات، إحنا بنعامل الثيمات كـ حزم برمجية مستقلة ومحمولة (Portable Packages):

sample-themes/carbon-volt/
├── theme.json          # مواصفات الحزمة والمعلومات الأساسية
├── theme.recipe.json   # وصفة التصميم وقواعد القياسات التفاعلية
├── css/
│   ├── theme.css       # نقطة الدخول المعزولة
│   ├── tokens.css      # خرائط المتغيرات المخصصة
│   └── apex/           # قواعد المكونات (العناوين، الحقول، النوافذ)
├── fonts/              # خطوط WOFF2 ذاتية الاستضافة بالكامل
└── preview/cover.jpg   # صورة المعاينة بدقة 960 بكسل

الأركان الأربعة للهيكل المعماري الجديد:

عزل النطاق الصارم (html.app-theme-<name>): الثيم مش بيشتغل إلا لما الكلاس الخاص بيه يتضاف على مستوى جذر الصفحة (<html>). لو شلت الكلاس، التطبيق بيرجع لـ Iris الأصلي 100% في نفس اللحظة بدون أي شوائب في ملفات الـ CSS العامة.
التمهيد الفوري بدون وميض (Zero-Flicker Pre-Paint Bootstrap): بدل ما نستنى الصفحة تخلص تحميل وبعدين ننادي كود JavaScript يغير الألوان فيحصل وميض أبيض يخطف العين، بنحط سطر تمهيد متزامن في Page 0 بيقرا التفضيل ويحط كلاس الثيم في أقل من 2 ميلي ثانية قبل ما المتصفح يرسم أول بكسل على الشاشة.
حزم ذاتية الاحتواء بدون اعتماد على سيرفرات خارجية: كل ثيم بيطلع في ملف ZIP مقفول تماماً. جواه خطوط الـ WOFF2 الخاصة بيه، فمفيش أي طلبات بتروح لـ Google Fonts أو CDNs خارجية. وتقدر تثبته أو تحذفه بأمر سطر أوامر آمن، أو من خلال 3 خطوات يدوية جوه Page Designer لو معندكش صلاحيات شل.
حماية اشتراك الـ Universal Theme 42 بنسبة 100%: لأن الشغل كله بيتم على طبقة الـ CSS و Page 0 فقط، تطبيقك بيفضل محتفظ باشتراكه الرسمي في Universal Theme بدون أي مساس.

🎨 استكشف الثيمات التمانية الجاهزة في المشروع

المشروع بييجي مع 8 ثيمات جاهزة ومجربة إنتاجياً بتغطي كل الأذواق الهندسية:

اسم حزمة الثيم	الاتجاه الفني	خطوط الطباعة	طبيعة السطح والتباين
Carbon Volt	جرافيت تقني داكن مع لمسات ليموني فسفوري وسماوي	Noto Kufi / Mono	داكن عالي التباين (`#12151c`)
Citrus Pop	مساحات مائية مبهجة مع بطاقات عائمة ولمسات برتقالي يوسفي	Tajawal	فاتح منعش (`#f0fbf9`)
Cobalt Press	ملمس ورق صحفي دافئ مع خطوط كحلي كلاسيكية وعناوين قرمزية	Cairo	فاتح هادئ (`#faf8f5`)
Estate Slate	رمادي مؤسسي دقيق للأعمال الإدارية مع لمسات كهرمانية خافتة	IBM Plex Sans Arabic	فاتح دقيق (`#f8f9fa`)
Estate Slate Dark	رمادي صخري مظلم للأنظمة الحساسة مع لمسات زمردية باردة	IBM Plex Sans Arabic	داكن مؤسسي (`#161a22`)
Linen	بساطة مطلقة مع إطارات فائقة النعومة وتناسق تام مع منتجات أبل	System UI / Iris	فاتح ناصع (`#ffffff`)
Solarized Dark	عمق تقني مستوحى من شاشات الـ Terminal الاحترافية	IBM Plex Mono	داكن مريح للعين (`#002b36`)
Velvet Signal	أسطح باذنجانية فاخرة مع حواف دائرية وإشارات بنفسجية متوهجة	Alexandria	داكن عصري (`#1b1622`)

🛠️ خطتنا في المقالات القادمة

في المقالات الخمسة الجاية من السلسلة دي، هنفكك كل جزء في المحرك ده بالتفصيل العملي:

الجزء الثاني (المقال الثاني): قلعة عزل الـ CSS — إزاي نتحكم في متغيرات --app-* ونتفادى كارثة مسح أيقونات Font APEX.
الجزء الثالث (المقال الثالث): سر الوميض الصفري — إزاي بنمنع الوميض الأبيض المزعج من خلال حقن كود سريع في Page 0.
الجزء الرابع (المقال الرابع): ماكينة الحزم المحمولة — أرشفة ملفات الـ ZIP، وحقن قوالب الـ APEXLang مع أمان التراجع التلقائي.
الجزء الخامس (المقال الخامس): بناء أداة تبديل الثيمات المخصصة — اعتراض قائمة Navigation Bar، والتعامل مع روابط Hash في الـ Friendly URLs، وربط مكونات Alpine.js.
الجزء السادس (مسك الختام): حفظ الثيمات على مستوى المؤسسة — ربط تفضيلات المستخدم مع قاعدة البيانات (:APP_USER) واستدعاءات Ajax المباشرة.

جاهز تقلع بدلة التوكسيدو الملحومة وتلبس بدلة فضاء خارقة سريعة التبديل؟ نتقابل في المقال الجاي عشان نبني قلعة الـ CSS الحصينة! 🚀

💡 ابدأ مع APEX Theme Factory الآن: تقدر تعمل Clone للمستودع، وتجرب الثيمات الجاهزة (carbon-volt، iris-dark، وغيرها)، وتستخدم أداة التثبيت الآلية: 🔗 https://github.com/ash2osh/APEX_THEME_FACTORY