2.4المعاملات والدعوات (Prompts)
الأساسي في 30 ثانية
- المعامل (Parameter) = قيمة تُطلَب عند التنفيذ: اسم، ودعوة واضحة، ونوع — التقرير يتكيف مع الإدخال.
- الاستعمال الأول = الترشيح: المعامل يغذي التحديد — قالب واحد لكل السنوات والمناطق.
- قائمة + افتراضي + خادم: قائمة قيم، وقيمة حالية معبأة مسبقاً، ومرشح جهة القاعدة — موجَّه وسريع وبلا خطأ.
حالة مستمرة — فارس واثنتا عشرة نسخة من نفس التقرير
يصون فارس نسخة من تقريره لكل سنة ولكل منطقة: اثنا عشر ملفاً شبه متطابق، كل تصحيح يجب تكراره في كل مكان. ينشئ معامل السنة (دعوة « اختر السنة »، نوع رقم، قائمة 2024-2026، افتراضي 2026) ومعامل المنطقة (قائمة قيم)، ثم يدمجهما في تحديده: يختار المستخدم عند التنفيذ، وقالب واحد يخدم كل الحالات. بل يعرض السنة المختارة في العنوان (« مبيعات 2026 — الشمالية »). في 2.5 سيضيف معامل « إظهار التفاصيل؟ » للتبديل بين الملخص والتفاصيل دون تكرار التقرير.
تتمة الخيط 2.3: مرشح فارس الثابت يصبح تفاعلياً — ويستمر في 2.5.
1. قيمة تُطلَب عند التنفيذ
المعامل (Parameter) قيمة يطلبها Crystal Reports من المستخدم عند تنفيذ التقرير (« أي سنة؟ »، « أي عميل؟ »، « الحد الأدنى للمبلغ؟ »). يدخل المستخدم قيمة أو يختارها، فيتكيف التقرير. ننشئ معاملاً في مستكشف الحقول (« حقول المعامل ← جديد »): نعطيه اسماً ودعوة (prompt) — النص المعروض: « اختر السنة » — ونوعاً (رقم، نص، تاريخ، منطقي…) وخيارات (قيمة وحيدة أو متعددة، قائمة قيم، قيمة افتراضية). ينشئ فارس {?Annee} و{?Region} لتقرير مبيعاته.
2. الاستعمال الأول: الترشيح
الأكثر شيوعاً: المعامل يغذي تحديد السجلات (2.3) — مثلاً « تاريخ الطلب في سنة {?Annee} » — لعرض وحده البيانات المختارة. تقرير واحد يخدم هكذا كل السنوات وكل العملاء، بدل تقرير لكل حالة. استعمالات أخرى: عرض القيمة المختارة في التقرير (« مبيعات {?Annee} — {?Region} ») للعنونة حسب الإدخال، أو قيادة الصيغ والتنسيق (المستوى 3). يستبدل فارس قيمته الثابتة 2026 بـ {?Annee}: تقرير 2025 أو 2026 أو الشمالية أو الجنوبية يخرج من نفس القالب.
3. الخيارات والممارسات الجيدة
خيارات مهمة: قيم متعددة (اختيار عدة عملاء معاً، مرشح « ضمن القائمة »)، ونطاق (بين تاريخين)، وقائمة قيم (قائمة منسدلة: ثابتة، أو ديناميكية من القاعدة — المستوى 5)، وقيمة افتراضية، ومعامل اختياري. تُجمَع المعاملات (سنة ET منطقة ET عتبة). ممارسات جيدة: دمج المعامل في المرشح مع البقاء جهة الخادم (الأداء، 2.3)؛ والعناية بـ الدعوة (نص واضح)؛ واقتراح قائمة قيم متى أمكن (تتجنب أخطاء الإدخال « الشمالية » مقابل « شمالية »). يسرد فارس المناطق ويعبئ مسبقاً السنة الجارية.
🔎 مثال ملموس — 🔎 مثال عملي — قالب واحد لكل السنوات
تقرير فارس، من القيمة الثابتة إلى المعامل:
قبل (ثابت): Year({Commandes.DateCommande}) = 2026 ← تقرير لكل سنة.
بعد (معامل): Year({Commandes.DateCommande}) = {?Annee}
and {Clients.Region} = {?Region} ← يختار المستخدم؛ وقالب واحد.القراءة: المعامل يعوض القيمة الثابتة في صيغة التحديد.
الدرس: اقترح قائمة قيم + قيمة افتراضية لتوجيه الإدخال.
مفردات القسم
- المعامل (Parameter)
- قيمة تُطلَب من المستخدم عند التنفيذ (سنة، عميل، عتبة)؛ يتكيف التقرير مع الإدخال. يُنشَأ في المستكشف (حقول المعامل).
مثال بسيط: ينشئ فارس {?Annee}: يختار المستخدم 2025 أو 2026 عند التنفيذ.
ما ليس كذلك: قيمة ثابتة جامدة في المرشح.
رد فعل: حالات متعددة = معامل، لا نسخة.
- الدعوة (prompt)
- النص المعروض للمستخدم لإدخال المعامل (« اختر السنة »)؛ يُحرَّر بوضوح.
مثال بسيط: دعوة فارس تقول « اختر السنة »، لا « Param1 ».
ما ليس كذلك: الاسم التقني الداخلي للمعامل.
رد فعل: الدعوة = جملة عمل واضحة.
- معامل الترشيح
- الاستعمال الأكثر شيوعاً: المعامل يغذي تحديد السجلات لعرض وحده البيانات المختارة.
مثال بسيط: تحديد فارس يستعمل {?Annee} و{?Region} بدل القيم الثابتة.
ما ليس كذلك: معامل مُنشَأ لكنه غير مربوط أبداً.
رد فعل: المعامل = مربوط بالتحديد.
- خيارات المعامل
- النوع، قيمة وحيدة/متعددة، النطاق، قائمة القيم (ثابتة أو ديناميكية)، القيمة الافتراضية، الاختياري.
مثال بسيط: يسمح فارس بعدة مناطق ويعبئ مسبقاً السنة الجارية.
ما ليس كذلك: إدخال حر غامض دون توجيه.
رد فعل: القائمة + الافتراضي أولاً.
في التطبيق — عملياً — إنشاء معاملات تفاعلية
- أنشئ معاملاً (المستكشف ← حقول المعامل ← جديد): اسم، ودعوة واضحة (« اختر السنة »)، ونوع، وخيارات (وحيد/متعدد، نطاق، قائمة قيم، افتراضي).
- ادمجه في تحديد السجلات (« تاريخ الطلب في سنة {?Annee} ») — مع البقاء جهة الخادم إن أمكن.
- اعرض عند الحاجة القيمة المختارة في التقرير (عنوان « مبيعات {?Annee} — {?Region} »).
- اختبر عند التنفيذ: تظهر الدعوة، وتدخل/تختار، فيتكيف التقرير. قالب واحد يخدم كل الحالات.
نص جاهز — بِع القالب الوحيد (30 ثانية)
« انتهت النسخ الاثنتا عشرة: تقرير مبيعات واحد، مع سؤالين عند الإطلاق — السنة والمنطقة. تختارون، فيرشح التقرير ويعنوِن تبعاً لذلك. ملفات أقل، وتصحيح واحد، ولا خطأ إدخال بفضل القوائم. جربوا: شغلوه لـ 2025 الشمالية ثم 2026 الجنوبية. »
يُقال مع تشغيل تقرير فارس مرتين بزوجين مختلفين، مع العنوانين.
قالب نسخ-لصق — تحديد يقوده المعامل
Year({Commandes.DateCommande}) = {?Annee}
Year({Commandes.DateCommande}) = {?Annee} and {Clients.Region} = {?Region}
{Commandes.DateCommande} in {?PlageDates}
{Clients.Ville} in {?Villes} // معامل بقيم متعددةنطاق تواريخ
يقترح فارس نطاقاً من 01/01 إلى 31/12: يدخل المستخدم حدين للفترة.
عدة عملاء
معامل بقيم متعددة: يختار فارس ثلاثة عملاء دفعة واحدة، مرشح « ضمن القائمة ».
عتبة المبلغ
معامل عتبة بافتراضي 1000: لا يحتفظ فارس إلا بالطلبات المعتبرة، قابلة للتعديل عند التنفيذ.
دعوة غامضة
دعوة « Param1: »: لا أحد يعرف ماذا يدخل — يعيد فارس كتابتها « اختر المنطقة ».
✓ ممارسات جيدة
- اقترح قائمة قيم (منسدلة) بدل إدخال حر.
- وفّر قيمة افتراضية معقولة (السنة الجارية).
- ادمج المعامل في المرشح مع البقاء جهة الخادم (الأداء).
✗ أخطاء شائعة
- إدخال حر مصدر أخطاء (فضل قائمة قيم).
- معامل غير مدمج في المرشح (التقرير لا يتكيف).
- دعوة غامضة تربك المستخدم.
النقاط الأساسية
- المعامل قيمة تُطلَب من المستخدم عند التنفيذ عبر دعوة؛ والتقرير يتكيف.
- الاستعمال الأول: الترشيح — المعامل يغذي التحديد. تقرير واحد يخدم كل الحالات (عام، قابل لإعادة الاستخدام).
- الخيارات: قيم متعددة، نطاق، قائمة قيم (ثابتة/ديناميكية)، قيمة افتراضية. تُجمَع المعاملات.
- ممارسات جيدة: البقاء جهة الخادم، والعناية بالدعوة، واقتراح قائمة قيم. ويمكنه أيضاً عنونة التقرير.
تحدي 48 ساعة — طبّق غداً
على تقريرك المرشح الثابت: أنشئ معاملاً (دعوة واضحة، قائمة، افتراضي)، اربطه بالتحديد، واعرضه في العنوان، ثم اختبر قيمتين مختلفتين عند التنفيذ.
- أستطيع إنشاء معامل (اسم، دعوة، نوع، قائمة، افتراضي).
- أعرف ربطه بالتحديد (تقرير يتكيف).
- أختبر عند التنفيذ بقيم متعددة (قابلية إعادة الاستخدام مثبتة).
أسئلة شائعة
كيف يجعل المعامل التقرير قابلاً لإعادة الاستخدام، وكيف أرشح به؟
دون معامل، مرشح ثابت (التاريخ في 2026) يجبر على تعديل التقرير أو نسخه لكل حالة. المعامل قيمة تُطلَب عند التنفيذ: يختار المستخدم، فيتكيف التقرير — قالب واحد يخدم كل الحالات. للترشيح: (1) أنشئ المعامل (المستكشف ← حقول المعامل ← جديد: اسم، دعوة، نوع، خيارات)؛ (2) ادمجه في تحديد السجلات بتعويض القيمة الثابتة: « Year({Commandes.DateCommande}) = {?Annee} ». عند التنفيذ، تظهر الدعوة ولا يعرض التقرير إلا السنة المختارة. ممارسات جيدة: البقاء جهة الخادم، واقتراح قائمة قيم وقيمة افتراضية، وعرض القيمة المختارة في العنوان.
ما خيارات المعامل لتجربة جيدة؟
اختر النوع الصحيح (رقم، تاريخ، نص، منطقي). قيمة وحيدة لاختيار واحد؛ وقيم متعددة لاختيار عدة (مرشح « ضمن القائمة »). ونطاق للفاصل (« بين تاريخين »). وقائمة قيم (ثابتة أو ديناميكية — من القاعدة) للتوجيه وتجنب أخطاء الكتابة: إنه الخيار الأكثر تحسيناً للتجربة. وقيمة افتراضية للحالة الشائعة؛ ومعامل اختياري لمرشح غير إلزامي. حرر دعوات واضحة. فضّل قوائم القيم على الإدخال الحر، وغطِّ الحاجات الحقيقية (متعدد/نطاقات) دون مضاعفة التنفيذات.
ما الفائدة الرئيسية للمعامل؟