دليل المصممين – كيفية إعداد ملف settings.json للقوالب

ملف settings.json هو الملف الذي يحدد إعدادات القالب ويتيح التحكم بها من خلال لوحة التحكم بدون الحاجة لتعديل الأكواد يدويًا. يمكنك من خلاله إضافة حقول نصية، خيارات تحديد (Select)، مربعات نصوص كبيرة (Textarea)، أرقام، وغيرها، على الرغم من أن الملف اختياري إلا أنه مفيد جدًا لسلاسلة القالب.

أين يوضع الملف؟

/templates/اسم_القالب/settings.json

الهيكل العام للملف

{
  "site_name": {
    "label": "اسم الموقع",
    "type": "text",
    "default": "موقعي الإخباري",
    "description": "يظهر في العنوان و الـ header"
  },
  "home_sections": {
    "label": "الأقسام في الرئيسية",
    "type": "select",
    "multiple": true,
    "source": {
      "table": "categories",
      "key": "id",
      "value": "name"
    },
    "blocked_values": [1,5],
    "default": [],
    "description": "اختر الأقسام التي ستظهر في الصفحة الرئيسية"
  }
}

شرح عناصر كل حقل

• 1. المفتاح (Key): اسم الحقل (مثل: site_name) ويجب أن يكون فريدًا.
• 2. label: الوصف الظاهر للمستخدم في لوحة التحكم.
• 3. type: نوع الحقل. القيم المدعومة:
  • text – نص قصير
  • number – رقم
  • textarea – نص طويل
  • select – قائمة خيارات
• 4. default: القيمة الافتراضية إذا لم يتم تعديل الحقل من لوحة التحكم.
• 5. description: وصف إضافي يظهر تحت الحقل لتوضيح وظيفته.
• 6. multiple: إذا كان true يسمح باختيار أكثر من خيار (للـ select فقط).
• 7. source: جلب البيانات ديناميكيًا من قاعدة البيانات:

  "source": {
    "table": "categories",
    "key": "id",
    "value": "name"
  }

• 8. blocked_values: مصفوفة تحتوي قيم IDs أو نصوص ممنوعة من الظهور.

أمثلة عملية

حقل نصي:

"site_title": {
  "label": "عنوان الموقع",
  "type": "text",
  "default": "موقعي الرائع",
  "description": "يظهر في شريط العنوان"
}

حقل رقمي:

"posts_per_page": {
  "label": "عدد المقالات في الصفحة",
  "type": "number",
  "default": 10
}

حقل نص طويل:

"footer_text": {
  "label": "نص الفوتر",
  "type": "textarea",
  "default": "حقوق النشر محفوظة © 2025",
  "description": "يظهر في أسفل الموقع"
}

حقل Select بسيط:

"default_theme": {
  "label": "الوضع الافتراضي",
  "type": "select",
  "default": "light",
  "options": {
    "light": "فاتح",
    "dark": "داكن"
  }
}

حقل Select ديناميكي من قاعدة البيانات:

"allowed_categories": {
  "label": "الأقسام المسموح عرضها",
  "type": "select",
  "multiple": true,
  "source": {
    "table": "categories",
    "key": "id",
    "value": "name"
  },
  "blocked_values": [1,5],
  "default": []
}

ملاحظات هامة

الخلاصة

باستخدام settings.json يمكنكم إعطاء حرية للمستخدم لتخصيص القالب بسهولة (ألوان، أقسام، نصوص…) بدون تعديل الأكواد. مجرد تعديل الملف وتحديد الإعدادات بشكل صحيح سيظهر تلقائيًا في لوحة التحكم ليقوم المستخدم بضبطه بسهولة.

مثال: