أمثلة تطبيقية على ExpressionScript

نظرة عامة على ما تم شرحه سابقًا

إذا كنت قد تابعت حتى الآن بنية دليل LimeSurvey، فهذا يعني أنك أصبحت على دراية بـمصطلحات LimeSurvey. بعد ذلك، تناولنا التعبيرات والمتغيرات لنتعلم كيفية تحسين استبياناتنا. وفي الجزء التالي، انتقلنا إلى أنواع ومعاني تمييز الصيغة لنتعلم كيفية تصحيح أخطاء الصيغة.

بعد استعراض هذه المفاهيم الأساسية، يمكننا الانتقال إلى الأمثلة وشرح كيفية عمل التعبيرات داخل LimeSurvey.

تمييز الصيغة

تعرض لقطات الشاشة التالية أمثلة، لكنها لا تُظهر قيم التلميحات. التلميح هو مربع معلومات يظهر عند تمرير مؤشر الماوس فوق أي كلمة ملونة بخط عريض.

بفضل تمييز الصيغة هذا، يسهل كثيرًا كتابة تعبيرات صحيحة، حتى المعقدة منها. ورغم أن فريق LimeSurvey يخطط لمحاولة بناء واجهة رسومية لمنشئ التعبيرات، يمكنك استخدام تمييز الصيغة الحالي لاكتشاف الأخطاء المطبعية وإصلاحها بسرعة. يمكنك أيضًا استخدام التلميحات للتحقق من دقة تعبيراتك (مثلًا، تأكيد أنك اخترت المتغيرات المطلوبة).

في كل مثال من الأمثلة، توجد ثلاثة أعمدة:

1. المصدر - هذا هو النص الخام الذي تدخله في حقل السؤال في LimeSurvey
2. الطباعة المنسقة - هذا هو المكافئ الذي تم تمييز صيغته لما أدخلته
   • لاحظ أن التعبيرات تظهر بخلفية بيج، ولكن دون أقواس معقوصة تحيط بها في هذا التمييز.
   • بما أن EM يدعم الاستبدال التكراري، فإن إظهار الأقواس المعقوصة في التمييز سيتسبب في أخطاء في الصيغة
3. النتيجة - هذا هو الناتج الذي يتم إنشاؤه عندما يعالج EM المصدر
   • يتم استبدال كل ما يمكن استبداله بشكل صحيح
   • تظهر التعبيرات التي تحتوي على أخطاء ضمن النص، مع تمييز الصيغة. وتحاط الأخطاء بمربع بخط أحمر.

الصيغة الصحيحة

يمكنك أدناه الاطلاع على أمثلة للصيغة الصحيحة:

1. القيم: توضح أن المتغيرات المعروفة تُلوَّن بحسب ما إذا كانت قد عُيّنت في الصفحة الحالية.
2. خصائص السؤال: توضح أن الترميز بالنقطة يمكنه الوصول إلى بعض خصائص الأسئلة
3. العمليات الحسابية: توضح أن العمليات الحسابية البسيطة والمعقدة مدعومة
4. معالجة النصوص: تعرض بعض دوال معالجة النصوص المتاحة
5. التواريخ: تعرض اثنتين من الدوال المتاحة المتعلقة بالتواريخ
6. الشرطي: يوضح استخدام الدالة if(). يمكن تضمين الخيارات بعضها داخل بعض.
7. الفقرة المخصصة: يمكنك تخصيص تقرير بالكامل بناءً على القيم السابقة
8. معالجة EM داخل السلاسل النصية: توضح أنه يمكنه إجراء الاستبدالات داخل السلاسل النصية. ينشئ هذا المثال اسم صورة مخصصًا.
9. لا يعالج EM الأقواس المعقوصة مثل هذه: توضح أنه إذا تم تهريب الأقواس المعقوصة، أو وُجدت مسافة بين التعبير والأقواس المعقوصة، فإن ES يتجاهل التعبير.

صيغة EM التي تحتوي على أخطاء

فيما يلي أمثلة على الأخطاء الشائعة عند كتابة تعبيرات ES. لاحظ أن التلميحات توفر معلومات إضافية.

1. شيفرة Javascript ضمن النص نُسيت فيها إضافة مسافات بعد القوس المعقوص
   • بما أن "document.write" تظهر مباشرة بعد قوس معقوص، يعتبرها EM تعبيرًا، ويحيط "document" و"write" بمربع أحمر لأنهما متغير ودالة غير معرّفين على التوالي
2. متغيرات ودوال ومعاملات غير معروفة/بها أخطاء إملائية
   • هنا نسينا أننا نستخدم اسم المتغير "gender" بدلًا من "sex"، لكن EM يكتشف هذا الخطأ. كما يحيط '++' بمربع أحمر، لأنه ليس معاملًا مدعومًا.
3. تحذير عند استخدام = بدلًا من eq، أو عند إجراء تعيين للقيم
   • لاحظ أن '=' و'+=' بنص أحمر بدلًا من الأسود. إذا مررت مؤشر الماوس فوقهما، سترى تحذيرات بأنك تعيّن قيمة.
4. عدد غير صحيح من الوسائط للدوال
   • تأخذ if() ثلاث وسائط، لكن أُعطيت أربعة، لذا فإن تمرير المؤشر فوق "if" المحاطة بمربع أحمر سيشرح الخطأ ويعرض الصيغة المدعومة
   • تأخذ sum() عددًا غير محدود من الوسائط، لكن كانت هناك فاصلة زائدة قبل القوس الختامي، لذلك أُحيطت بمربع أحمر
5. أقواس غير متطابقة
   • هذا أحد أكثر الأخطاء شيوعًا عند كتابة التعبيرات.
   • يعرض هذا مثالين على أقواس ختامية ناقصة، ومثالًا على وجود قوس ختامي زائد.
6. صيغة غير مدعومة
   • إذا استخدمت معاملًا أو علامة ترقيم لا يدعمها ES، فسيحيطها بمربع أحمر.
7. تعيينات غير صالحة
   • بعض المتغيرات قابلة للقراءة والكتابة ويمكن تغيير قيمها. والبعض الآخر للقراءة فقط.
   • إذا حاولت تغيير قيمة متغير للقراءة فقط، فلن تتمكن من ذلك. سيحيط EM المحاولة بمربع أحمر.
   • إذا حاولت تعيين قيمة لمعادلة أو لسلسلة نصية، فستحصل أيضًا على خطأ

أمثلة "حية" على تمييز الصيغة مع تلميحات نشطة

المصدر	الطباعة المنسقة	النتيجة
هذا مثال على صيغة صحيحة مع التلميحات Hello {if(gender=='M','Mr.','Mrs.')} {surname}, it is now {date('g:i a',time())}. Do you know where your {sum(numPets,numKids)} children and pets are?	هذا مثال على صيغة صحيحة مع التلميحات Hello if(gender == 'M','Mr.','Mrs.') surname, it is now date('g:i a',time()). Do you know where your sum(numPets,numKids) children and pets are?	هذا مثال على صيغة صحيحة مع التلميحات Hello Mr. Smith, it is now 6:07 am. Do you know where your 3 children and pets are?
فيما يلي أخطاء شائعة لتتمكن من رؤية التلميحات متغيرات مستخدمة قبل التصريح عنها: {notSetYet} دالة غير معروفة: {iff(numPets>numKids,1,2)} متغير غير معروف: {sum(age,num_pets,numKids)} عدد معاملات خاطئ: {sprintf()},{if(1,2)},{date()} تعيين قيم لمتغيرات للقراءة فقط:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} أقواس غير متوازنة: {pow(3,4},{(pow(3,4)},{pow(3,4))}	فيما يلي أخطاء شائعة لتتمكن من رؤية التلميحات متغيرات مستخدمة قبل تعريفها: notSetYet وظيفة غير معروفة: iff(numPets > numKids,1,2) متغير غير معروف: sum(age,num_pets,numKids) عدد معاملات خاطئ: sprintf(),if(1,2),date() إسناد قيم لمتغيرات للقراءة فقط:TOKEN:ATTRIBUTE_1+=10,name='Sally' أقواس غير متوازنة: pow(3,4,(pow(3,4),pow(3,4))	فيما يلي أخطاء شائعة لتتمكن من رؤية التلميحات متغيرات مستخدمة قبل تعريفها: notSetYet وظيفة غير معروفة: iff(numPets > numKids,1,2) متغير غير معروف: sum(age,num_pets,numKids) عدد معاملات خاطئ: sprintf(),if(1,2),date() إسناد قيم لمتغيرات للقراءة فقط:TOKEN:ATTRIBUTE_1+=10,name='Sally' أقواس غير متوازنة: pow(3,4,(pow(3,4),pow(3,4))
فيما يلي بعض أمثلة بناء الجملة غير المدعوم لا يوجد دعم لـ '++' و'--' و'%' و';': {min(++age, --age,age % 2);} ولا لـ '|' و'&' و'^': {(sum(2 | 3,3 & 4,5 ^ 6)}} ولا المصفوفات: {name[2], name['mine']}	فيما يلي بعض أمثلة بناء الجملة غير المدعوم لا يوجد دعم لـ '++' و'--' و'%' و';': min( ++ age, -- age,age % 2) ; ولا لـ '|' و'&' و'^': (sum(2 | 3,3 & 4,5 ^ 6)} ولا المصفوفات: name [ 2 ] ,name [ 'mine' ]	فيما يلي بعض أمثلة بناء الجملة غير المدعوم لا يوجد دعم لـ '++' و'--' و'%' و';': min( ++ age, -- age,age % 2) ; ولا لـ '|' و'&' و'^': (sum(2 | 3,3 & 4,5 ^ 6)} ولا المصفوفات: name [ 2 ] ,name [ 'mine' ]

أمثلة التخصيص

"عزيزي {Mr}/{Mrs} Smith..."

استخدم الدالة if() لاختيار عرض 'Mr.' أو 'Mrs.' بشكل مشروط.

بناء الجملة هو if(test,do_if_true,do_if_false).

#	الرمز	السؤال	النوع
1	gender	ما هو جنسك؟	نوع
2	example1	عزيزي {if(gender=='M','Mr.','Mrs.')} Smith، ...	نص حر طويل

كما يمكنك أن تلاحظ أدناه، يتم تخصيص "Mr" و"Mrs" وفقًا لما يختاره المشارك كإجابة على السؤال "gender".

"عزيزي {Mr}/{Mrs} Smith..." في البريد الإلكتروني للدعوة

يمكنك استخدام المثال أعلاه في البريد الإلكتروني للدعوة باستخدام السمات من جدول الرموز المميزة. استخدم الدالة if() لاختيار ما إذا كان يجب استخدام 'Mr.' أو 'Mrs.' في البريد الإلكتروني.

بناء الجملة هو "if(test,do_if_true,do_if_false)".

#	السمة	القيمة
1	اسم العائلة	Smith
2	البريد الالكتروني	test@test.com
3	ATTRIBUTE_2	M

النص في البريد الإلكتروني للدعوة:

Dear {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME},

you have been invited to participate in a survey:

https:/...

عرض البريد الإلكتروني:

أمثلة الحسابات / التقييم

احتساب قيم التقييم أثناء التشغيل وتخزين النتائج في بيانات الاستبيان

يستخدم هذا المثال جميع ميزات EM، بما في ذلك الصلة (Relevance) والتخصيص (Tailoring) ونوع السؤال معادلة.

كما يوضح أن جميعها تدعم JavaScript، لذا إذا كانت هذه الميزات موجودة في صفحة ما، فستتغير ديناميكيًا عندما يقوم المشاركون بتحديد إجاباتهم وتغييرها.

#	الرمز	السؤال	النوع	الملاءمة
1	numKids	كم عدد الأطفال لديك؟	المدخل العددي	1
2	kid1	كم عمر طفلك الأول؟	المدخل العددي	numKids >= 1
3	kid2	كم عمر طفلك الثاني؟	المدخل العددي	numKids >= 2
4	kid3	كم عمر طفلك الثالث؟	المدخل العددي	numKids >= 3
5	kid4	كم عمر طفلك الرابع؟	المدخل العددي	numKids >= 4
6	sumKidAges	{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)}	معادلة	1
7	kidSummary	لقد ذكرت أن لديك {numKids}. {if(numKids==1,'child','children')}. {if(numKids>1,implode(' ','The sum of ages of your first ',min(numKids,4),' kids is ',sumKidAges,'.'),' ')}	إظهار المعلومات المكتوبة (النصوص)	1

لتنزيل هذا المثال، يرجى النقر على الرابط التالي: مثال استبيان التقييمات.

يمكنك أدناه الاطلاع على لقطات شاشة لأسئلة تمثيلية. كما ترى، يقوم EM بتمييز بناء الجملة في جميع الحقول التي قد تحتوي على تخصيص. هنا ترى أمثلة على تمييز بناء الجملة في الصلة (Relevance)، ونوع السؤال معادلة، والاستبدالات داخل السؤال. يمكنك أيضًا استخدام الاستبدالات في المساعدة، وعرض رأس المجموعة، ورسالة ترحبية، ورسالة ختامية.

في المثال التالي، بما أن الصلة هي {numKids >= 2)، فلن يكون السؤال مرئيًا إلا إذا ذكر المجيب أن لديه طفلين على الأقل.

يمكنك أن تلاحظ أدناه أن كل متغير مرتبط به اللاحقة .NAOK. يرجع ذلك إلى الطريقة التي يدعم بها EM الصلة المتتالية. إذا لم تستخدم .NAOK، فلن يتم حساب المجموع إلا إذا ذكر الشخص أن لديه 4 أطفال (أي إذا كانت جميع المتغيرات ذات صلة). يعني استخدام .NAOK أننا نريد حساب المجموع حتى لو كانت جميع المتغيرات أو بعضها غير ذات صلة (أي أن "غير قابل للتطبيق" (NA) مقبول (OK)).

ومع ذلك، فإن السمة .NAOK تؤثر فقط على ما إذا كانت المتغيرات تُمرَّر إلى EM. إذا ذكر المجيب في البداية أن لديه 3 أطفال وأدخل أعمارهم، ثم غيّر رأيه وذكر أن لديه طفلين، فلا نريد رؤية مجموع القيم الثلاث المُدخلة - لأن الطفل الثالث أصبح "غير قابل للتطبيق" في حالتنا:

يتم تلوين كل تعبير منفصل بخلفية بنية فاتحة. كما ترى، هناك ثلاثة تعبيرات منفصلة هنا. يحتوي الأخير على رسالة لا تظهر إلا بشرط أن يكون لدى الشخص أكثر من طفل واحد.

والآن، إليك لقطات شاشة للاستبيان أثناء العمل.

عند زيارة الصفحة لأول مرة، سترى هذا. لاحظ أنها تعرض "You have 0 children" بدلاً من "You have 0 child".

إذا غيّرت قيمة عدد الأطفال إلى 1، يتغير العرض فورًا إلى هذا، رغم أنه في الصفحة نفسها:

لاحظ الآن أن القواعد اللغوية صحيحة: "You have 1 child".

الآن أغيّر قيمة عدد الأطفال إلى 3، فيتغير العرض فورًا إلى هذا.

لاحظ أنك ترى الآن الرسالة الشرطية في الأسفل: "The sum of ages of your first 3 kids is 0.".

الآن سأدخل أعمار أطفالي الافتراضيين، فأحصل على هذا العرض الذي يجمع أعمارهم:

مرة أخرى، يتم تحديث النتيجة والعرض فورًا أثناء إدخال القيم، لذا يمكنك استخدام ذلك لعرض المجموع التراكمي لدرجة التقييم.

الآن أغيّر قيمة عدد الأطفال إلى 2. تغيّر العرض إلى هذا:

لاحظ أنه على الرغم من أنني أدخلت القيمة 5.5 للطفل الثالث، فإن التقرير يجمع الآن قيم أول طفلين فقط.

والسبب في ذلك أن القيمة الثالثة أصبحت الآن غير ذات صلة، ويتجاهل EM القيم غير ذات الصلة بشكل فعّال.

إذا أعدت عدد الأطفال إلى 3، فسأرى القيمة 5.5 التي أدخلتها سابقًا مرة أخرى. وبذلك لا أفقد أي معلومات أدخلتها في الصفحة.

ومع ذلك، إذا انتقلت إلى الصفحة التالية أو السابقة، فسيتم تفريغ جميع القيم غير ذات الصلة (NULL) في الجلسة وفي قاعدة البيانات. لذا، إذا أبقيت القيمة 2، وانتقلت إلى الصفحة التالية، ثم عدت وذكرت أن لدي في الواقع 3 أطفال، فلن أرى العمر 5.5 بعد الآن.

أدخل البيانات واطّلع على تقرير يتغير ديناميكيًا لما تم إدخاله في الصفحة نفسها

يعرض هذا المثال عملية التخصيص (Tailoring) في LimeSurvey.

لتنزيل هذا المثال، انقر على الرابط التالي: مثال استبيان التغييرات الديناميكية.

هكذا تبدو الصفحة في البداية. ترى فقط السؤال الذي يسأل عن المدينة التي تعيش فيها:

بمجرد أن تبدأ في إدخال إجابة، تبدأ عملية التخصيص أيضًا:

أثناء إدخال الإجابات، يتم تحديث الجدول في أسفل الصفحة لعرض أكواد الإجابات وقيم إجاباتك.

أمثلة شائعة لتصحيح الأخطاء

عبارات if() المتداخلة (المنطق الشرطي)

يدعم EM الدالة "if(test,do_if_true,do_if_false)" بحيث يمكنك تنفيذ المنطق الشرطي أو التخصيص. يمكن تداخل هذه الدالة للحصول على ما يعادل "if { } else if { } else { }". سيُعلمك EM إذا كانت الأقواس غير متوازنة (مثلًا، إذا كان ينقصك قوس إغلاق أيمن)، أو إذا كان لديك أي أقواس يمنى زائدة. يجب أن تحاول عدّ الأقواس أثناء كتابة عبارات if المتداخلة الطويلة، ثم تقوم بحفظها وفحص أخطاء الصياغة وتصحيحها إن وُجدت. لنفحص معًا المثال التالي.

يمكن الوصول إلى مجموعة الأسئلة المستخدمة أدناه من هنا: مثال استبيان التخصيص .lsg

أولًا، عندما لا يتم إدخال أي شيء، ترى فقط "مرحبا."

إذا أدخلت اسمًا، تظهر العبارة "مرحبا {name}."

إذا أدخلت العمر، تحصل على رسالة مخصصة، بحسب ما إذا كنت طفلًا في سن ما قبل المدرسة أم لا:

في سن المدرسة، أو مراهق، أو بالغ. هذا مراهق يريد أن يبقى مجهول الهوية:

هذا هو ملف المنطق الخاص بالمجموعة. كما ترى في السؤال "المعتمد على if"، توجد عبارات if متداخلة تعتمد على عمر الشخص.

عند تحرير هذا السؤال في البداية، من المحتمل أن يكون عدد الأقواس خاطئًا في مرحلة ما. إليك ما يحدث إذا كان عدد الأقواس أقل من المطلوب:

إذا مررت المؤشر فوق كلمة "if" المحاطة بمربع أحمر، فستظهر رسالة "Parentheses not balanced". في هذه الحالة، يجب أن تكون هناك أربعة أقواس إغلاق بعد "already an adult!"، لكن هناك ثلاثة فقط.

أما إذا كان لديك قوس أيمن زائد، فسيتم إحاطته بمربع أحمر، هكذا:

عند تحرير السؤال فعليًا، يبدو السؤال هكذا: