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

الـ 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.settings.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 المتاحة​

المتغيرالنوعالوصف
widget._idstringمعرف فريد لنسخة الـ widget
widget.settingsobjectقيم إعدادات الـ widget المُعرّفة في schema.json
widget.blocksarrayمصفوفة من نسخ الـ blocks المُضافة للـ widget

متغيرات Block المتاحة​

عند التكرار على widget.blocks، كل block يحتوي على:

المتغيرالنوعالوصف
block._idstringمعرف فريد لنسخة الـ block
block.typestringاسم نوع الـ block (مثل "slide"، "testimonial")
block.settingsobjectقيم إعدادات الـ block المُعرّفة في schema.json

مثال على الاستخدام​

{# معرف Widget الفريد - مفيد لاستهداف نسخ معينة #}
<section id="widget-{{ widget._id }}">

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

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

</section>

استخدام 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 للمحتوى المتكرر (الشرائح، التقييمات، الأسئلة الشائعة)
  • قدم قيم افتراضية معقولة لجميع الإعدادات

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