انتقل إلى المحتوى الرئيسي

الـ Widgets

الـ Widgets هي اللبنات الأساسية لصفحات قالبك. كل widget هو مكون قائم بذاته مع إعداداته الخاصة، قالبه، واختيارياً blocks قابلة للتكرار.

هيكل مجلد Widget​

كل widget له مجلد مخصص داخل widgets/:

widgets/
├── hero-slider/
│   ├── schema.json    # تكوين وإعدادات الـ widget
│   └── widget.njk     # قالب HTML للـ widget (Nunjucks)
├── testimonials/
│   ├── schema.json
│   └── widget.njk
└── product-details/
    ├── schema.json
    └── widget.njk

إنشاء Widget جديد​

لإنشاء widget جديد وإضافته مباشرة لصفحة محددة:

qumra gen widget <widget-name>

سترى قائمة بالصفحات المتاحة لإضافة الـ widget إليها:

? Select the page to add the widget to:
❯ index.json
  product.json
  collection.json
  cart.json
  blog.json

بعد الاختيار:

✅ Widget '<widget-name>' created and added to '<page>.json' successfully.
اصطلاح التسمية

أسماء الـ widgets يجب أن تكون بأحرف صغيرة مع أحرف وأرقام وشرطات فقط (مثل hero-slider, product-grid).

مخطط Widget (schema.json)​

المخطط يحدد اسم الـ widget، إعداداته، blocks، وpresets.

هيكل المخطط الأساسي​

{
  "name": "Hero Slider",
  "settings": {
    "autoplay": {
      "type": "boolean",
      "label": "تفعيل التشغيل التلقائي",
      "default": true
    },
    "speed": {
      "type": "number",
      "label": "سرعة الانتقال (ثواني)",
      "default": 5,
      "min": 3,
      "max": 15
    },
    "titleColor": {
      "type": "color",
      "label": "لون العنوان",
      "default": "#ffffff"
    }
  }
}

أنواع الإعدادات المتاحة​

النوعالوصفخصائص إضافية
stringنص سطر واحد-
textنص متعدد الأسطر-
numberإدخال رقميmin, max, step
booleanتبديل تشغيل/إيقاف-
colorمنتقي ألوان-
selectاختيار منسدلoptions: [{label, value}]
mediaمنتقي صور/وسائط-
rangeعنصر تحكم منزلقmin, max, step, unit
productsمنتقي منتجات-
menuمنتقي قوائم-

مثال Select​

{
  "contentPosition": {
    "type": "select",
    "label": "موضع المحتوى",
    "default": "center",
    "options": [
      { "label": "يسار", "value": "left" },
      { "label": "وسط", "value": "center" },
      { "label": "يمين", "value": "right" }
    ]
  }
}

مثال Range​

{
  "opacity": {
    "type": "range",
    "label": "شفافية التراكب",
    "default": 50,
    "min": 0,
    "max": 100,
    "step": 5,
    "unit": "%"
  }
}

الـ Blocks (المحتوى المتكرر)​

الـ Blocks تسمح للمستخدمين بإضافة عناصر متعددة من نفس النوع (مثل الشرائح، الشهادات، الأسئلة الشائعة).

مخطط مع Blocks​

{
  "name": "الشهادات",
  "settings": {
    "title": {
      "type": "string",
      "label": "عنوان القسم",
      "default": "ماذا يقول عملاؤنا"
    }
  },
  "blocks": {
    "testimonial": {
      "name": "شهادة",
      "settings": {
        "customerName": {
          "type": "string",
          "label": "اسم العميل",
          "default": ""
        },
        "review": {
          "type": "text",
          "label": "نص التقييم",
          "default": ""
        },
        "rating": {
          "type": "number",
          "label": "التقييم (1-5)",
          "default": 5,
          "min": 1,
          "max": 5
        },
        "avatar": {
          "type": "media",
          "label": "صورة العميل",
          "default": ""
        }
      }
    }
  }
}

استخدام Blocks في القالب​

<section class="testimonials">
  <h2>{{ widget.data.title }}</h2>

  {% for block in widget.blocks %}
    <div class="testimonial-card">
      {% if block.settings.avatar %}
        <img src="{{ block.settings.avatar }}" alt="{{ block.settings.customerName }}">
      {% endif %}
      <p class="review">{{ block.settings.review }}</p>
      <div class="rating">★ {{ block.settings.rating }}/5</div>
      <span class="name">{{ block.settings.customerName }}</span>
    </div>
  {% endfor %}
</section>

الـ Presets (التكوينات الافتراضية)​

الـ Presets توفر نسخ widget مُعدة مسبقاً مع بيانات نموذجية:

{
  "name": "قسم الأسئلة الشائعة",
  "settings": { ... },
  "blocks": { ... },
  "presets": [
    {
      "category": "Content",
      "name": "قسم الأسئلة الشائعة",
      "blocks": [
        {
          "block": "faq",
          "name": "سؤال الشحن",
          "settings": {
            "question": "كم تستغرق مدة الشحن؟",
            "answer": "الشحن العادي يستغرق 3-5 أيام عمل."
          }
        },
        {
          "block": "faq",
          "name": "سؤال الإرجاع",
          "settings": {
            "question": "ما هي سياسة الإرجاع؟",
            "answer": "نقبل الإرجاع خلال 30 يوماً من الشراء."
          }
        }
      ]
    }
  ]
}

قالب Widget (widget.njk)​

الوصول لبيانات الـ widget في قالب Nunjucks الخاص بك:

{# إعدادات مستوى Widget #}
<h1 style="color: {{ widget.data.titleColor }}">
  {{ widget.data.title }}
</h1>

{# إعدادات القالب العامة #}
<div style="background: {{ settings.mainColor }}">
  ...
</div>

{# التكرار على blocks #}
{% for block in widget.blocks %}
  <div class="block-{{ block.type }}">
    {{ block.settings.content }}
  </div>
{% endfor %}

استخدام Widgets في الصفحات​

أضف widgets لـ JSON صفحتك مع الإعدادات والـ blocks:

{
  "layout": "layout",
  "title": "الصفحة الرئيسية",
  "widgets": [
    {
      "name": "hero-slider",
      "widget": "hero-slider",
      "settings": {
        "autoplay": true,
        "speed": 5,
        "titleColor": "#ffffff"
      },
      "blocks": [
        {
          "block": "slide",
          "name": "الشريحة 1",
          "settings": {
            "title": "مرحباً بكم في متجرنا",
            "buttonText": "تسوق الآن",
            "buttonUrl": "/collections"
          }
        },
        {
          "block": "slide",
          "name": "الشريحة 2",
          "settings": {
            "title": "وصول جديد",
            "buttonText": "اكتشف",
            "buttonUrl": "/collections/new"
          }
        }
      ]
    }
  ]
}

ملفات الوسائط المحلية​

عند استخدام ملفات وسائط محلية، أضف بادئة qumra://:

{
  "image": "qumra://banner.png",
  "video": "qumra://promo.mp4"
}

نصائح سريعة​

أفضل الممارسات
  • استخدم أسماء widgets وصفية (hero-slider, product-grid, testimonials)
  • حدد جميع الإعدادات في schema.json واستخدمها في القالب
  • استخدم blocks للمحتوى المتكرر (الشرائح، التقييمات، الأسئلة الشائعة)
  • قدم قيم افتراضية معقولة لجميع الإعدادات

عرض جميع أنواع الحقول والخصائص ←