التطوير

تطوير الستايلات

تعلّم كيفية بناء ستايلاتك الخاصة لكليجا.

ستايل كليجا مجلد يضم قوالب HTML وملفات تصميم تتحكم بشكل واجهة الموقع. تعيش الستايلات داخل styles/، ويختار المدير الستايل النشط من لوحة التحكم.

القوالب صفحات HTML عادية تعلوها لغة وسوم صغيرة. يترجم كليجا كل قالب إلى PHP مرة واحدة، ويخزّن الناتج مؤقتاً، ثم يقدّم الملف المخزَّن في الطلبات التالية. لا تكتب PHP داخل القالب إطلاقاً، فالمحلّل يحذفها.

تشرح هذه الصفحة نظام الستايلات في كليجا 4. يوجد محرك القوالب في includes/style.php، حيث يبحث kleeja_style عن القوالب ويخزّنها مؤقتاً، ويترجمها KleejaTemplateCompiler. ويوجد مدير الستايلات في includes/adm/m_styles.php. يأتي كليجا 4 بستايل واحد للواجهة هو bootstrap، ولم يعد الستايل القديم default موجوداً. راجع ترقية ستايل من كليجا 3.

كيف يعمل النظام

يبني ملف includes/common.php مسارات الستايل من إعدادين اثنين: يحمل style مجلد الستايل النشط، ويحمل style_depend_on اسم الستايل الأب حين يرث الستايل من ستايل آخر. وحين يكون style فارغاً، يستخدم كليجا bootstrap.

حين تستدعي الصفحة $tpl->display('login')، يبحث المحرك عن login.html في الستايل النشط، ثم يرجع إلى الستايل الأب، ثم يترجم الملف إلى cache/tpl_login.php ويضمّنه. يُعاد استخدام الملف المترجَم حتى يُمسح المخزون المؤقت.

كل متغير عام في PHP هو متغير قالب. تنسخ الدالة display() مصفوفة $GLOBALS إلى المحرك قبل العرض، فتصبح $config و$lang و$userinfo وكل ما تعرّفه الصفحة متاحاً بالصيغة {config.sitename} و{lang.LOGIN} وهكذا.

بنية المجلد

الستايل مجلد داخل styles/ يتكوّن اسمه من حروف صغيرة وأرقام ونقاط وشرطات سفلية، وبطول ثلاثة محارف على الأقل.

styles/

styles/
└── my_style/
    ├── info.txt          # مطلوب — بيانات الستايل
    ├── header.html       # مطلوب — يفتح الصفحة ويحمّل ملفات CSS
    ├── footer.html       # مطلوب — يغلق الصفحة
    ├── index_body.html   # مطلوب — نموذج الرفع
    ├── up_boxes.html     # مطلوب — صناديق النتائج بعد الرفع
    ├── info.html         # مطلوب — رسائل المعلومات
    ├── err.html          # مطلوب — رسائل الأخطاء
    ├── login.html        # ... ملف لكل صفحة، انظر الجدول أدناه
    ├── screenshot.png    # اختياري — صورة مصغّرة في لوحة التحكم
    ├── index.html        # اختياري — يمنع عرض محتويات المجلد
    ├── css/
    ├── js/
    └── images/

الستايل الذي يرث من ستايل آخر لا يحتاج سوى القوالب التي يغيّرها. يضم bootstrap_black ملف header.html وملف تنسيق وملف info.txt الخاص به، ويرث ما تبقّى من bootstrap.

القوالب

القالب	يعرضه	الصفحة
`header.html`	`Saaheader()`	الشيفرة الافتتاحية لكل صفحة.
`footer.html`	`Saafooter()`	الشيفرة الختامية لكل صفحة.
`index_body.html`	`index.php`	نموذج الرفع في الصفحة الرئيسة.
`up_boxes.html`	`get_up_tpl_box()`	صناديق الروابط بعد نجاح الرفع.
`info.html`	`kleeja_info()`	رسائل المعلومات. ويحل محل الصفحة الرئيسة عند تعطيل الرفع.
`err.html`	`kleeja_err()`	رسائل الأخطاء.
`download.html`	`do.php`	صفحة تحميل الملف.
`login.html`	`ucp.php`	نموذج تسجيل الدخول.
`register.html`	`ucp.php`	نموذج التسجيل.
`profile.html`	`ucp.php`	نموذج الملف الشخصي.
`fileuser.html`	`ucp.php`	مدير ملفات المستخدم.
`get_pass.html`	`ucp.php`	استعادة كلمة المرور.
`guide.html`	`go.php`	صفحة الشرح.
`rules.html`	`go.php`	صفحة القوانين.
`report.html`	`go.php`	نموذج الإبلاغ عن ملف.
`call.html`	`go.php`	نموذج التواصل.
`stats.html`	`go.php`	إحصاءات الموقع.

تستخدم رسائل البريد القالب includes/mail_template.html، وهو ليس جزءاً من الستايل.

القالب المفقود خطأ قاتل. حين يعجز المحرك عن إيجاد اسم في الستايل النشط أو أبيه، يوقف الطلب برسالة No Template !. لذا يجب أن يشحن الستايل الذي لا يملك depend_on كل القوالب أعلاه، لأن كليجا 4 لا يملك ستايل default يرجع إليه.

ملف info.txt

يحمل كل ستايل ملف info.txt تقرؤه لوحة التحكم. يتجاهل المحلّل الأسطر الفارغة والأسطر التي تبدأ بـ #، ويقسم الباقي عند أول =، ويعامل النقطتين في المفتاح كمفتاح فرعي.

styles/my_style/info.txt

#
# This is a configuration file of the style.
#

#Style name
name = My Style

#Style desc
desc:en = A clean, responsive style for Kleeja
desc:ar = ستايل بسيط ومتجاوب لكليجا

#Style copyright
copyright = 2026 Your Name

#Version of style
version = 1.0

#Min. required version of kleeja
kleeja_version = 4.0.0

#name of the style required by this style
depend_on = bootstrap

#plugins required to install this style
#plugins_required = test, test2

المفتاح	الغرض
`name`	الاسم المعروض في قائمة الستايلات.
`desc:<lang>`	الوصف لكل لغة، ويرجع إلى `desc:en`.
`copyright`	سطر حقوق النشر المعروض مع الستايل.
`version`	إصدار الستايل. يستخدمه المتجر لاكتشاف التحديثات.
`kleeja_version`	أدنى إصدار مطلوب من كليجا. يفشل التفعيل على ما هو أقدم منه.
`depend_on`	مجلد الستايل الأب. تُلتمس القوالب الناقصة فيه.
`plugins_required`	أسماء مجلدات الإضافات المطلوب تثبيتها وتفعيلها، مفصولة بفواصل.

يقود ملف info.txt الفحوص التي تجري عند تفعيل المدير للستايل. يمنع التفعيلَ برسالة واضحة أيٌّ من: غياب مجلد الستايل الأب، أو إصدار كليجا أقدم من kleeja_version، أو إضافة مطلوبة غير مثبّتة.

صياغة القوالب

يحوّل المحلّل مجموعة صغيرة من الوسوم شبه البرمجية إلى PHP، ويمرّر ما عداها كما هو.

حين يحتوي القالب على خطأ، مثل <IF> لم يُغلق أو <ELSE> في غير موضعه، يتوقف كليجا ويعرض صفحة Template error تذكر اسم القالب ورقم السطر.

المتغيرات

ضع اسم المتغير بين قوسين معقوفين مفردين. تنقلك النقطة داخل المصفوفة.

styles/my_style/header.html

<title>{title} - {config.sitename}</title>
<p>{lang.WELCOME}، {username}</p>
<link rel="stylesheet" href="{STYLE_PATH}css/stylesheet.css" />

يجوز أن تحتوي الأسماء على حروف وأرقام وشرطات سفلية ونقاط، ولا شيء غير ذلك. أما {lang.X} و{olang.X} فلهما سلوك خاص: عند غياب المفتاح يطبع المحرك الوسم نفسه بدل نص فارغ، ما يسهّل اكتشاف الترجمات الناقصة.

المرشّحات

يُطبع المتغير كما هو. يخزّن كليجا النصوص مُرمَّزة بـ HTML، لذا تكون معظم القيم آمنة داخل HTML أصلاً. أضف مرشّحاً بعد | حين تذهب القيمة إلى مكان آخر:

المرشّح	الناتج
`{name\|e}`	مُرمَّز بـ HTML مرة واحدة بالضبط، حتى لو كان النص المخزَّن مُرمَّزاً مرتين.
`{name\|url}`	مُرمَّز لاستخدامه في رابط عبر `rawurlencode()`.
`{name\|js}`	قيمة JSON مع علامات الاقتباس، آمنة داخل كتلة `<script>`.
`{name\|int}`	عدد صحيح.

styles/my_style/footer.html

<script>
    var STYLE_LANG = { copy: {lang.COPY|js}, copied: {lang.COPIED|js} };
</script>
<a href="https://example.com/share?title={title|url}">{title|e}</a>

الحلقات

يكرّر الوسم <LOOP> عناصر المصفوفة. داخل الحلقة، تقرأ الأقواس المزدوجة الصف الحالي، ويطبع {%key%} المفتاح الحالي، ويطبع {%value%} القيمة الحالية.

styles/my_style/header.html

<ul class="menu">
    <LOOP NAME="top_menu">
        <IF LOOP="show">
        <li><a href="{{url}}">{{title}}</a></li>
        </IF>
    </LOOP>
</ul>

أما المصفوفة المسطّحة من النصوص فيكفيها {%value%}:

styles/my_style/login.html

<IF NAME="ERRORS">
    <ul class="alert">
        <LOOP NAME="ERRORS">
            <li>{%value%}</li>
        </LOOP>
    </ul>
</IF>

يمكن تداخل الحلقات. داخل الحلقة الداخلية يقرأ {{field}} صف الحلقة الداخلية، ويعود صف الحلقة الخارجية عند إغلاق الداخلية. يسمّي <LOOP NAME> دائماً متغيراً عاماً، لا حقلاً من الصف الحالي، لذا جهّز المصفوفة الداخلية في PHP.

الشروط

يأخذ الوسم <IF> خصائص بدل تعبير حر. استخدم NAME للمتغير العام، وLOOP لحقل من صف الحلقة الحالي.

styles/my_style/index_body.html

<IF NAME="user_is">
    <p>{lang.WELCOME} {username}</p>
<ELSE>
    <a href="{action_login}">{lang.LOGIN}</a>
</IF>

<IF NAME="config.safe_code">
    <img src="{captcha_file_path}" alt="{lang.REFRESH_CAPTCHA}" />
</IF>

الخاصية	المعنى
`NAME`	متغير عام، مع إمكانية إضافة مقارنة.
`LOOP`	حقل من صف الحلقة الحالي، مع إمكانية إضافة مقارنة. استخدم `NAME` أو `LOOP`، لا كليهما.
`ISSET`	يغلّف المتغير المسمّى بالدالة `isset()`.
`EMPTY`	يغلّف المتغير المسمّى بالدالة `empty()`.
`AND`	مقارنة إضافية تُربط بالمعامل `&&`.
`OR`	مقارنة إضافية تُربط بالمعامل `\|\|`.

تُربط فحوص NAME أو LOOP وISSET وEMPTY بالمعامل &&، ثم يُضاف AND وOR بهذا الترتيب. ويمكن أن تستخدم قيم الخصائص علامات اقتباس مزدوجة أو مفردة.

تقبل المقارنات الرموز والكلمات معاً:

المعامل	الصيغة الكلامية
`==`	`eq`
`!=`	`neq`
`<`	`lt`
`>`	`gt`
`<=`	`lte`
`>=`	`gte`

القيمة على اليمين رقم، أو كلمة، أو نص بين علامتَي اقتباس مفردتين مثل 'quoted text' للقيم التي تحتوي مسافات، أو متغير آخر بالصيغة {name} أو {{field}}. تُقارَن الكلمة كنص حتى لو احتوت أرقاماً، لذا يعمل <IF NAME="style == bootstrap4"> كما هو متوقع.

styles/my_style/header.html

<IF NAME="go_current == index" ISSET="extras.header">
    <div class="extras_header">{extras.header}</div>
</IF>

يمدّد الوسم <ELSEIF> سلسلة الشروط، ويعكس الوسم <UNLESS> الفحص. أغلق الثلاثة بـ </IF> أو </UNLESS> أو الوسم العام </END>.

styles/my_style/profile.html

<IF NAME="current_smt == users">
    ...
<ELSEIF NAME="current_smt == team">
    ...
</IF>

<UNLESS NAME="no_results">
    <p>{lang.RESULTS}</p>
</UNLESS>

لا تستطيع القوالب تشغيل PHP. الشرط الذي يحتوي شيفرة PHP، مثل $x أو استدعاء دالة، يُترجَم إلى false ويُطلق تحذيراً يذكر اسم القالب ورقم السطر. احسب القيمة في PHP وافحص متغيراً بدلاً من ذلك.

الشروط المختصرة

الشرط الثلاثي بين قوسين اختصارٌ لكتلة <IF> قصيرة، ولا يقبل علامات اقتباس ولا فواصل.

styles/my_style/footer.html

(page_stats?<div class="footer_stats">{page_stats}</div>:)
<a href="{{url}}" class="nav-link(go_current=={{name}}? active:)">{{title}}</a>

اترك أحد الطرفين فارغاً كي لا يُعرض شيء في تلك الحالة.

كشف المتصفح

يعرض الوسم <IS_BROWSER> كتلته للمتصفحات التي تسمّيها فقط. استخدم != لعكس الشرط، وقائمة مفصولة بفواصل لمطابقة أكثر من متصفح.

styles/my_style/header.html

<IS_BROWSER!="mobile">
    <img src="{user_avatar}" alt="{username}" />
</IS_BROWSER>

<IS_BROWSER="safari,firefox">
    <link rel="stylesheet" href="{THIS_STYLE_PATH}css/fixes.css" />
</IS_BROWSER>

الأسماء المدعومة هي chrome وedge وfirefox وsafari وopera وie وkonqueror وmozilla وwebkit وmobile. وأضف رقم إصدار بعد أي اسم عدا mobile لاستهدافه، مثل ie11 أو firefox115.

مساعدات الصفوف

داخل الحلقة، يفحص الوسمان <ODD> و<EVEN> حقلاً رقمياً من الصف الحالي، ويناوب الوسم <RAND> بين نصّين مع كل استدعاء. يحتاج <ODD> و<EVEN> إلى وسمَي الإغلاق، وإلا طُبعا كنص.

styles/my_style/fileuser.html

<LOOP NAME="files">
    <tr class="<RAND="row_a","row_b">">
        <td>{{name}}</td>
    </tr>
</LOOP>

تضمين قالب

يعرض الوسم <INCLUDE> قالباً آخر في مكانه. أضف PATH لجلبه من مجلد خارج الستايل النشط.

styles/my_style/index_body.html

<INCLUDE NAME="sidebar">

الحماية من التحليل

يحذف المحلّل شيفرة PHP من القوالب، فلا تبقى كتل <?php ?> ولا <? ?> ولا <% %> ولا <script language="php"> بعد الترجمة، ويُطبع <? المنفرد كنص. وغلّف الشيفرة بالوسم <IGNORE> لإخفائها عن المحلّل تماماً، وهو مفيد مع JavaScript أو CSS التي قد تبدو كوسم قالب.

styles/my_style/footer.html

<IGNORE>
<script>const tpl = { name: "{not a variable}" };</script>
</IGNORE>

متغيرات القوالب

المسارات

المتغير	يشير إلى
`{STYLE_PATH}`	رابط الستايل الأب حين يكون `depend_on` مضبوطاً، وإلا رابط الستايل النشط. استخدمه للملفات الموروثة.
`{THIS_STYLE_PATH}`	رابط مجلد الستايل النشط. استخدمه لملفاتك التي تتجاوز الأب.
`{STYLE_PATH_ADMIN}`	رابط قالب لوحة التحكم، `admin/Damask/`.
`{DEFAULT_PATH_ADMIN}`	رابط قالب لوحة التحكم الافتراضي، وهو أيضاً `admin/Damask/`.

في الستايل الوارث يشير {STYLE_PATH} إلى الأب. لذا فتحميل {STYLE_PATH}css/stylesheet.css ثم {THIS_STYLE_PATH}css/stylesheet.css يمنحك ملف الأب متبوعاً بتعديلاتك، وهو تماماً ما يفعله bootstrap_black.

الصفحة والمستخدم

المتغير	المحتوى
`{title}`	عنوان الصفحة.
`{dir}`	اتجاه النص، `rtl` أو `ltr`، حسب اللغة النشطة. ومثله `{lang.DIR}`.
`{lang.LANG_SMALL_NAME}`	رمز اللغة للخاصية `lang`، مثل `en-us`.
`{charset}`	ترميز المحارف، وهو `utf-8` دائماً.
`{username}`	اسم الزائر، أو تسمية الضيف.
`{user_is}`	صحيح حين يكون الزائر مسجّل الدخول.
`{user_avatar}`	رابط صورة Gravatar، ويرجع إلى الصورة `images/user_avater.png` في الستايل.
`{userinfo.*}`	صف المستخدم المسجّل.
`{action_login}` و`{H_FORM_KEYS_LOGIN}`	عنوان إرسال نموذج تسجيل الدخول في الترويسة، ومفتاح النموذج.
`{config.*}`	أي إعداد من لوحة التحكم، مثل `{config.sitename}` و`{config.siteurl}`.
`{lang.*}`	العبارات اللغوية من `lang/<code>/`.
`{olang.*}`	العبارات اللغوية التي تضيفها الإضافات.
`{text}`	نص الرسالة في `info.html` و`err.html`.

القوائم والكتل

المتغير	المحتوى
`{top_menu}`	حلقة القائمة العلوية: `{{name}}` و`{{title}}` و`{{url}}` و`{{show}}`.
`{side_menu}`	حلقة قائمة المستخدم، بالحقول نفسها إضافة إلى `{{icon}}`، وهو اسم أيقونة من Font Awesome بدون البادئة `fa-`.
`{go_current}`	اسم الصفحة الحالية، لتعليم عنصر القائمة النشط.
`{extras.header}`	شيفرة إضافية تُحقن فوق المحتوى.
`{extras.footer}`	شيفرة إضافية تُحقن أسفل المحتوى.
`{EXTRA_CODE_META}`	وسوم إضافية داخل `<head>`، وفيها تضيف الإضافات وسوم الميتا.
`{page_stats}`	زمن التوليد وعدد الاستعلامات، عند تفعيلهما.
`{admin_page}`	رابط لوحة التحكم، ولا يُضبط إلا للمستخدمين القادرين على فتحها.
`{run_queue}`	بكسل المهام المجدولة. أبقِه في `footer.html`.
`{googleanalytics}`	شيفرة التحليلات، عند ضبطها.
`{go_back_browser}`	عبارة «العودة» المترجمة.
`{is_embedded}`	صحيح حين تُفتح الصفحة مع `?embedded=1`، للستايلات التي توفّر صفحة رفع قابلة للتضمين.

يجب أن يحتفظ footer.html بالمتغير {run_queue}، فهو يشغّل مهام كليجا المجدولة ومنها حذف الملفات القديمة، وإسقاطه يوقفها بصمت.

صناديق نتائج الرفع

ملف up_boxes.html ليس قالباً عادياً. يقسّمه كليجا إلى كتل مسمّاة ويستبدل فيها المتغيرات {var} استبدالاً نصياً بسيطاً، بلا شروط ولا حلقات ولا عبارات لغوية. وتُحدَّد الكتل بتعليقات HTML.

styles/my_style/up_boxes.html

<!-- BEGIN image -->
    <div class="up-box">
        <div class="up-box-label">{b_title}</div>
        <input type="text" readonly value="{b_url_link}" aria-label="{b_title}">
    </div>
<!-- END image -->

الكتلة	تظهر مع
`image_thumb`	صورة مرفوعة مع مصغّرة.
`image`	صورة مرفوعة، بروابط مباشرة وروابط BBCode.
`file`	ملف مرفوع غير صورة.
`del_file_code`	رمز حذف الملف المرفوع.

المتغيرات المتاحة هي {b_title} و{b_bbc_title} و{b_url_link} و{b_img_link} و{b_code_link}، إضافة إلى {siteurl} و{sitename}. ويجب أن توجد الكتل الأربع كلها، لأن نظام الرفع يطلبها بالاسم. والستايل الوارث الذي لا يملك ملف up_boxes.html خاصاً به يستخدم ملف الأب.

يحذف كليجا كل فاصل أسطر والمسافات البادئة التي تليه قبل استخدام الكتل. أبقِ كل وسم في سطر واحد، وإلا التصقت الخصائص الموزّعة على أسطر منفصلة ببعضها.

وراثة الستايلات

اضبط depend_on في info.txt للبناء على ستايل قائم. يكتب تفعيلُ الابن كلا الإعدادين style وstyle_depend_on، ثم يلتمس المحرك كل قالب ناقص عند الأب.

styles/bootstrap_black/info.txt

name = Bootstrap Black
version = 2.0
kleeja_version = 4.0.0
depend_on = bootstrap

يجري البحث عن القالب بهذا الترتيب:

الستايل النشط

المسار styles/<style>/<template>.html.

الستايل الأب

حين يكون style_depend_on مضبوطاً، يُبحث عن الاسم نفسه داخل مجلد الأب.

الأب هو مسار الرجوع الوحيد، وعلى مستوى واحد فقط: لا يُتّبع depend_on الخاص بالأب. ومن دون depend_on يبحث المحرك في styles/default/، وهو ستايل لم يعد كليجا 4 يشحنه. لذا ابنِ على bootstrap، أو اشحن كل القوالب بنفسك.

داخل الستايل الوارث، حمّل ملفات الأب عبر {STYLE_PATH} وملفاتك عبر {THIS_STYLE_PATH}:

styles/bootstrap_black/header.html

<IF NAME="lang.DIR==rtl">
<link rel="stylesheet" href="{config.siteurl}includes/static_shared_files/bootstrap/css/bootstrap.rtl.min.css">
<ELSE>
<link rel="stylesheet" href="{config.siteurl}includes/static_shared_files/bootstrap/css/bootstrap.min.css">
</IF>
<link rel="stylesheet" href="{config.siteurl}includes/static_shared_files/fontawesome/css/all.min.css">
<link rel="stylesheet" href="{STYLE_PATH}css/stylesheet.css">
<link rel="stylesheet" href="{THIS_STYLE_PATH}css/stylesheet.css">

لا يستطيع الستايل الوارث إضافة ملف تنسيق دون ملف header.html خاص به، لذا ينسخ ترويسة الأب ويضيف وسم <link> واحداً. وحين يتغير ملف header.html الخاص بالأب في إصدار جديد من كليجا، انسخه من جديد وأعد تطبيق تعديلاتك.

الملفات والاتجاه

ضع ملفات التنسيق في css/ والسكربتات في js/ والصور في images/، وأشر إليها عبر متغير مسار كي يبقى الستايل عاملاً بعد إعادة تسميته أو وراثته.

يأتي كليجا بإطار Bootstrap 5.3 مع نسخته الخاصة بالاتجاه من اليمين إلى اليسار، وبأيقونات Font Awesome، داخل includes/static_shared_files/. يحمّلها قالب لوحة التحكم والستايل bootstrap من هناك، ويستطيع ستايلك ذلك أيضاً، فيحمّلها الزوار مرة واحدة.

يأتي كليجا بالعربية والإنجليزية، لذا يجب أن يتعامل الستايل مع الاتجاهين. يحمل المتغير {dir} القيمة rtl أو ltr، ما يتيح لك ضبط اتجاه المستند وتحميل نسخة Bootstrap المناسبة:

styles/my_style/header.html

<html lang="{lang.LANG_SMALL_NAME}" dir="{dir}">
...
<IF NAME="lang.DIR==rtl">
    <link rel="stylesheet" href="{config.siteurl}includes/static_shared_files/bootstrap/css/bootstrap.rtl.min.css">
<ELSE>
    <link rel="stylesheet" href="{config.siteurl}includes/static_shared_files/bootstrap/css/bootstrap.min.css">
</IF>

الوضع الفاتح والداكن

يملك الستايل bootstrap وضع ألوان فاتحاً وداكناً وتلقائياً. يضبط الملف js/color-mode.js الخاصية data-bs-theme على العنصر <html> قبل رسم الصفحة، ويحفظ اختيار الزائر في المتصفح. ويرث الستايل الابن مفتاح التبديل هذا. عرّف ألوانك عبر متغيرات CSS الخاصة بـ Bootstrap، أو بقاعدة [data-bs-theme="dark"]، كي تعمل في الوضعين.

السكربتات

يقرأ الملف js/script.js في الستايل bootstrap نصوصه من الكائن STYLE_LANG الذي يعرّفه footer.html. لذا يجب أن يحتفظ الستايل الابن الذي يستبدل footer.html بذلك الكائن وبوسوم <script>، وإلا توقفت أزرار النسخ وفحوص الرفع عن العمل.

أضف ملف screenshot.png إلى مجلد الستايل للحصول على صورة مصغّرة في قائمة الستايلات. وبدونه تعرض لوحة التحكم أيقونة عامة.

سير العمل أثناء التطوير

تُخزَّن القوالب المترجَمة في مجلد cache/، لذا لا تظهر تعديلاتك على ملف .html حتى يُمسح المخزون المؤقت. أوقف التخزين المؤقت أثناء العمل:

config.php

define('DEV_STAGE', true);

يعيد الثابت DEV_STAGE ترجمة القوالب مع كل طلب، ويُبلغ عن كل أخطاء PHP، ويضيف رابط Debug Info إلى التذييل للمديرين. ولإيقاف التخزين المؤقت وحده دون بقية مخرجات التنقيح، استخدم STOP_TPL_CACHE بدلاً منه.

على الموقع الحيّ، امسح المخزون المؤقت من لوحة التحكم ← الصيانة ← مسح الكاش بعد رفع أي قالب معدَّل. أما تفعيل ستايل فيمسحه تلقائياً.

قراءة الناتج المترجَم

يُترجَم كل قالب إلى cache/tpl_<name>.php، بعد تحويل الاسم إلى حروف صغيرة واستبدال كل محرف خارج النطاق a-z0-9-_ بشرطة. ويُلحق بالقالب الذي تعرضه إضافة من مجلدها الخاص بصمةُ MD5 لذلك المجلد بعد اسمه. وفتح الملف المترجَم أسرع وسيلة لمعرفة إلى ماذا تحوّل الوسم حين يسيء القالب التصرّف.

إدارة الستايلات

يدير المديرون الستايلات من لوحة التحكم ← الستايلات. تعرض الصفحة الستايلات الموجودة في styles/، وتعرض في تبويب المتجر الستايلات المتاحة في متجر كليجا.

الإجراء	الأثر
الاختيار	يكتب `style` و`style_depend_on` ثم يمسح المخزون المؤقت، بعد إجراء فحوص الأب والإصدار والإضافات المطلوبة.
الرفع	يفكّ ضغط ملف `.zip` مرفوع داخل `styles/`.
التنزيل	يجلب الستايل من المتجر ويفكّ ضغطه، مع تراجع تلقائي عند الفشل. لحسابات المؤسسين فقط.
حذف المجلد	يحذف مجلد الستايل. ولا يمكن حذف الستايل النشط.

يفشل التفعيل برسالة محددة في ثلاث حالات: غياب المجلد المسمّى في depend_on، أو كون kleeja_version أحدث من إصدار كليجا العامل، أو غياب إضافة مذكورة في plugins_required أو تعطيلها.

التحزيم والتوزيع

وزّع الستايل كملف .zip يحتوي مجلداً واحداً في جذره، بالبنية نفسها التي في styles/.

Terminal

zip -r my_style.zip my_style -x "*.git*"

يرفع المديرون الأرشيف من لوحة التحكم ← الستايلات، ويفكّ كليجا ضغطه مباشرة داخل styles/ دون إعادة تسميته، لذا يجب أن يحمل المجلد الجذري اسم الستايل. أما الستايل المنزَّل من المتجر فيُعاد تسميته باسمه في الفهرس، لذا يعمل هناك الأرشيف الذي يبنيه GitHub للإصدار، بمجلد مثل my_style-1.0/.

تُثبَّت الستايلات المدرجة في الفهرس العام بنقرة واحدة. يقرأ كليجا 4 الملف kleeja-4-catalog.json، ولكل ستايل فيه مدخل مثل هذا:

kleeja-4-catalog.json

{
  "type": "style",
  "name": "my_style",
  "icon": "https://raw.githubusercontent.com/you/my_style/main/screenshot.png",
  "title": { "en": "My Style", "ar": "ستايلي" },
  "description": { "en": "A clean, responsive style", "ar": "ستايل بسيط ومتجاوب" },
  "developer": "اسمك",
  "website": "https://github.com/you/my_style",
  "kleeja_version": { "min": "4.0.0", "max": "4.9.9" },
  "depend_on": "bootstrap",
  "plugins_required": "",
  "file": {
    "version": "1.0",
    "url": "https://github.com/you/my_style/archive/1.0.zip"
  }
}

فهرس متجر كليجا.

قالب لوحة التحكم

تستخدم لوحة التحكم قالبها الخاص المثبّت في admin/Damask/ والمبني على Bootstrap 5.3، وقوالبه هي الملفات التي تبدأ بـ admin_. ويوجّه المحرك أي اسم قالب يحمل هذه البادئة إلى قالب لوحة التحكم بدل الستايل النشط.

قوالب لوحة التحكم ليست جزءاً من ستايل الواجهة. ولاستبدالها اشحن إضافة تعيد كتابة متغيرات مسار اللوحة من الخطّاف end_common.

راجع توثيق الإضافات للاطلاع على الخطّاف ومثال تجاوز المسارات كاملاً.

ترقية ستايل من كليجا 3

استبدل كليجا 4 محلّل القوالب والستايلات المرفقة به. راجع هذه النقاط عند نقل ستايل:

الوراثة. لم يعد الستايل default موجوداً. اضبط depend_on = bootstrap، أو اشحن كل القوالب.
الإصدار. اضبط kleeja_version = 4.0.0 في info.txt وفي مدخل الفهرس الخاص بك.
Bootstrap. انتقل الستايل bootstrap إلى Bootstrap 5.3 وأصبح يحمّله من includes/static_shared_files/. لذا تحتاج القوالب المنسوخة من ستايل Bootstrap 4 القديم إلى شيفرة جديدة.
الشروط. احذف الخصائص الفارغة AND=""، فهي توقف الصفحة الآن بخطأ قالب. ويجتمع ISSET وEMPTY مع NAME بدونها.
PHP داخل القوالب. الشروط التي كانت تشغّل شيفرة PHP أصبحت false. انقل ذلك المنطق إلى إضافة أو إلى سكربت الصفحة.
أسماء المتصفحات. حُذف flock وأُضيف edge.
قوالب نمت مزاياها. قارن ملفَي header.html وfooter.html لديك بنظيريهما في styles/bootstrap/، فهما يحملان الآن مفتاح تبديل وضع الألوان ونصوص STYLE_LANG.

حلّ المشكلات

العَرَض	السبب
`No Template !`	القالب غير موجود في الستايل ولا في أبيه. تحقق من اسم الملف ومن `depend_on`.
`Template error`	كتلة لم تُغلق، أو وسم في غير موضعه. تذكر الرسالة اسم القالب ورقم السطر.
التعديلات بلا أثر	القالب المترجَم مخزَّن مؤقتاً. فعّل `DEV_STAGE` أو امسح المخزون المؤقت.
متغير `{variable}` يُطبع كما هو	في حالة `{lang.}` و`{olang.}` يعني أن المفتاح مفقود. وفي غيرها يعني أن المتغير العام غير موجود في تلك الصفحة.
الشرط خاطئ دائماً	يحتوي الشرط شيفرة PHP، والقوالب لا تستطيع تشغيلها. يذكر التحذير اسم القالب ورقم السطر.
يظهر `&quot;` في النص	رُمِّز النص المخزَّن مرتين. اطبعه بالمرشّح `\|e`.
تعطُّل JavaScript بعد الترجمة	الأقواس المعقوفة في الشيفرة بدت كوسوم قوالب. غلّف الكتلة بالوسم `<IGNORE>`، واطبع القيم بالمرشّح `\|js`.
توقّف التنظيف المجدول	حُذف المتغير `{run_queue}` من `footer.html`.

المرجع

الوسوم

الوسم	يُترجَم إلى
`{var}` و`{a.b}`	طباعة متغير عام.
`{var\|e}` و`\|url` و`\|js` و`\|int`	طباعة متغير عبر مرشّح.
`{{field}}`	طباعة حقل من صف الحلقة الحالي.
`{%key%}` و`{%value%}`	طباعة مفتاح الحلقة الحالي أو قيمته.
`<LOOP NAME="x"> … </LOOP>`	تكرار `foreach` على مصفوفة.
`<IF NAME="x"> … </IF>`	كتلة شرطية.
`<ELSEIF …>` و`<ELSE>`	سلسلة شروط.
`<UNLESS …> … </UNLESS>`	شرط معكوس.
`(cond?a:b)`	شرط مختصر.
`<IS_BROWSER="x"> … </IS_BROWSER>`	فحص المتصفح، و`!=` لعكسه.
`<ODD="field"> … </ODD>`	العرض عند القيم الفردية.
`<EVEN="field"> … </EVEN>`	العرض عند القيم الزوجية.
`<RAND="a","b">`	المناوبة بين نصّين.
`<INCLUDE NAME="tpl">`	عرض قالب آخر.
`<IGNORE> … </IGNORE>`	إخفاء كتلة عن المحلّل.
`</END>`	وسم إغلاق عام.

واجهة المحرك

الدالة	التوقيع
`display()`	`display(string $template_name, string $style_path = ''): string`
`assign()`	`assign(string $var, mixed $to): void`
`template_exists()`	`template_exists(string $template_name, string $style_path = ''): string\|false`
`kleeja_style_info()`	`kleeja_style_info(string $style_name): array\|false` — في `includes/functions_display.php`
`get_up_tpl_box()`	`get_up_tpl_box(string $box_name, array $extra = []): string` — في `includes/functions_display.php`
`is_browser()`	`is_browser(string $b): bool` — في `includes/functions_display.php`

الإعدادات والثوابت

الاسم	المعنى
`config.style`	اسم مجلد الستايل النشط.
`config.style_depend_on`	اسم مجلد الستايل الأب، أو فارغ.
`ACP_STYLE_NAME`	مجلد قالب لوحة التحكم، وهو `Damask`.
`DEV_STAGE`	يوقف تخزين القوالب مؤقتاً ويفعّل مخرجات التنقيح.
`STOP_TPL_CACHE`	يوقف تخزين القوالب مؤقتاً فقط.
`PATH`	المسار المطلق لجذر كليجا على نظام الملفات، وينتهي بشرطة مائلة.

تحرير هذه الصفحةأوالإبلاغ عن مشكلة

تطوير الإضافات

تعلّم كيفية بناء إضافاتك الخاصة لكليجا.