الدوال

دوال السلاسل النصية link

يدعم rtSurvey دوالاً متنوعة، تشمل:

1. string(field): تحوّل حقلاً إلى سلسلة نصية.

   • مثال: string(34.8) ستُحوَّل إلى '34.8'.

2. string-length(field): تُعيد طول حقل سلسلة نصية.

   • مثال: string-length(.) > 3 and string-length(.) < 10 يمكن استخدامه للتأكد من أن الحقل الحالي يتراوح بين 3 و10 أحرف.

3. substr(fieldorstring, startindex, endindex): تُعيد سلسلة فرعية تبدأ من startindex وتنتهي قبل endindex. تبدأ الفهارس من 0 للحرف الأول في السلسلة.

   • مثال: substr(${phone}, 0, 3) ستُعيد أول ثلاثة أرقام من رقم الهاتف.

4. concat(a, b, c, ...): تدمج الحقول (و/أو السلاسل النصية) معاً.

   • مثال: concat(${firstname}, ' ', ${lastname}) ستُعيد الاسم الكامل بدمج القيم في حقلَي firstname وlastname.

5. linebreak(): تُعيد حرف فاصل سطر.

   • مثال: concat(${field1}, linebreak(), ${field2}, linebreak(), ${field3}) ستُعيد قائمة من ثلاث قيم حقول مع فواصل أسطر بينها.

6. lower(): تحوّل سلسلة نصية إلى أحرف صغيرة بالكامل.

   • مثال: lower('Street Name') ستُعيد “street name”.

7. upper(): تحوّل سلسلة نصية إلى أحرف كبيرة بالكامل.

   • مثال: upper('Street Name') ستُعيد “STREET NAME”.

دوال select_one وselect_multiple link

1. count-selected(field): تُعيد عدد العناصر المحددة في حقل select_multiple.

   • مثال: count-selected(.) = 3 يمكن استخدامه كتعبير قيد للتأكد من اختيار ثلاثة خيارات بالضبط.

2. selected(field, value): تُعيد true أو false بحسب ما إذا كانت القيمة المحددة قد اختيرت في حقل select_one أو select_multiple.

   • مثال: selected(${color}, 'Blue') يمكن استخدامه كتعبير ملاءمة لإظهار مجموعة أو حقل فقط إذا اختار المستجيب “Blue” كلونه المفضل.
   • ملاحظة: يجب أن تُحدد المعلمة الثانية دائماً قيمة الخيار، وليس تسمية الخيار.

3. selected-at(field, number): تُعيد العنصر المحدد في الموضع المحدد في حقل select_multiple. عند تمرير 0، تُعيد أول عنصر محدد؛ عند تمرير 1، تُعيد العنصر الثاني المحدد، وهكذا.

   • مثال: selected-at(${fruits}, 0) = 'Apple' يمكن استخدامه كتعبير ملاءمة لإظهار مجموعة أو حقل فقط إذا كان أول خيار محدد هو “Apple”.

4. choice-label(field, value): تُعيد التسمية لخيار حقل select_one أو select_multiple، كما هو محدد في ورقة عمل choices.

   • مثال 1: choice-label(${country}, ${country}) ستُعيد تسمية الخيار للخيار المحدد حالياً في الحقل المسمى country.
   • مثال 2: choice-label(${languages}, selected-at(${languages}, 0)) ستُعيد التسمية للخيار الأول المحدد في الحقل المسمى languages.

دوال الحقول المتكررة link

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

1. join(string, repeatedfield): لحقل داخل مجموعة تكرار، تُنشئ قائمة مفصولة بسلسلة نصية من القيم. تُحدد المعلمة الأولى المحدد المستخدم لفصل القيم.

   • مثال: join(', ', ${member_name}) ستُنشئ قائمة واحدة مفصولة بفواصل من جميع الأسماء المُدخلة.

2. join-if(string, repeatedfield, expression): تعمل تماماً مثل join()، إلا أنها تتحقق من كل مثيل في مجموعة التكرار باستخدام التعبير الموفر. إذا قيّم التعبير بـ false، سيُحذف العنصر من الإخراج.

   • مثال: join-if(', ', ${member_name}, ${age} >= 18) ستُنشئ قائمة مفصولة بفواصل من أسماء الأعضاء البالغين فقط (أولئك الذين تبلغ أعمارهم 18 وما فوق).

3. count(repeatgroup): تُعيد العدد الحالي لمرات تكرار مجموعة التكرار.

   • مثال: count(${groupname}) ستُعيد عدد مثيلات المجموعة.

4. count-if(repeatgroup, expression): تعمل تماماً مثل count()، إلا أنها تتحقق من كل مثيل في مجموعة التكرار باستخدام التعبير الموفر. إذا قيّم التعبير بـ false، سيُحذف العنصر من الإخراج.

   • مثال: count-if(${members}, ${age} >= 18) ستُعيد عدد الأعضاء البالغين بناءً على حقل العمر داخل مجموعة التكرار “members”.

5. sum(repeatedfield): لحقل داخل مجموعة تكرار، تحسب مجموع جميع القيم.

   • مثال: sum(${loan_amount}) ستُعيد إجمالي قيمة جميع القروض.

6. sum-if(repeatedfield, expression): تعمل تماماً مثل sum()، إلا أنها تتحقق من كل مثيل في مجموعة التكرار باستخدام التعبير الموفر. إذا قيّم التعبير بـ false، سيُحذف العنصر من الإخراج.

   • مثال: sum-if(${loan_amount}, ${loan_amount} > 500) ستُعيد إجمالي قيمة جميع القروض التي تزيد عن 500.

7. min(repeatedfield): لحقل داخل مجموعة تكرار، تحسب الحد الأدنى لجميع القيم.

   • مثال: min(${member_age}) ستُعيد عمر أصغر عضو في المجموعة.

8. min-if(repeatedfield, expression): تعمل تماماً مثل min()، إلا أنها تتحقق من كل مثيل في مجموعة التكرار باستخدام التعبير الموفر.

   • مثال: min-if(${member_age}, ${member_age} >= 18) ستُعيد عمر أصغر بالغ في المجموعة.

9. max(repeatedfield): لحقل داخل مجموعة تكرار، تحسب الحد الأقصى لجميع القيم.

   • مثال: max(${member_age}) ستُعيد عمر أكبر عضو في المجموعة.

10. max-if(repeatedfield, expression): تعمل تماماً مثل max()، إلا أنها تتحقق من كل مثيل في مجموعة التكرار باستخدام التعبير الموفر.

    • مثال: max-if(${member_age}, ${member_age} >= 18) ستُعيد عمر أكبر بالغ في المجموعة.

11. index(): تُستدعى داخل مجموعة تكرار، تُعيد رقم الفهرس للمجموعة أو المثيل الحالي.

    • مثال: index() عند استخدامها داخل مجموعة تكرار ستُعيد 1 للمثيل الأول، 2 للثاني، وهكذا.

12. indexed-repeat(repeatedfield, repeatgroup, index): تستشير حقلاً أو مجموعة داخل مجموعة تكرار من خارج تلك المجموعة. تُحدد المعلمة الأولى الحقل أو المجموعة المتكررة المطلوبة، والثانية تُحدد مجموعة التكرار التي يوجد بها الحقل أو المجموعة، والثالثة تُحدد رقم المثيل داخل مجموعة التكرار.

    • مثال 1: indexed-repeat(${name}, ${names}, 1) ستُعيد الاسم الأول المتاح عندما يكون حقل الاسم داخل مجموعة تكرار سابقة تُسمى “names”.
    • مثال 2: indexed-repeat(${name}, ${names}, index()) ستسحب الاسم المقابل لرقم المثيل لمجموعة التكرار الحالية.

13. rank-index(index, repeatedfield): تحسب هذه الدالة الترتيب الترتيبي للمثيل المحدد من الحقل المتكرر للاستخدام خارج مجموعة التكرار. يُسند الترتيب 1 للمثيل ذي القيمة الأعلى، والترتيب 2 للمثيل التالي، وهكذا.

    • مثال: rank-index(1, ${random_draw}) يحسب ترتيب المثيل الأول بناءً على قيمة حقل random_draw مقارنةً بقيم المثيلات الأخرى.

14. rank-index-if(index, repeatedfield, expression): تعمل هذه الدالة مماثلةً لـ rank-index()، لكنها تتحقق من كل مثيل في مجموعة تكرار الحقل المتكرر باستخدام التعبير الموفر.

    • مثال: rank-index-if(1, ${age}, ${age} >= 18) يحسب ترتيب العمر ضمن مجموعة البالغين.

دوال الأرقام link

يدعم rtSurvey دوال الأرقام، تشمل:

• number(field): تحوّل قيمة الحقل إلى رقم.

  • مثال: number('34.8') = 34.8

• int(field): تحوّل قيمة الحقل إلى عدد صحيح.

  • مثال: int('39.2') = 39

• min(field1, ..., fieldx): تُعيد القيمة الدنيا بين الحقول الممررة.

  • مثال: min(${father_age}, ${mother_age}) ستُعيد عمر الأب أو الأم، أيهما أصغر.

• max(field1, ..., fieldx): تُعيد القيمة القصوى بين الحقول الممررة.

  • مثال: max(${father_age}, ${mother_age}) ستُعيد عمر الأب أو الأم، أيهما أكبر.

• format-number(field): تُنسّق قيمة حقل عدد صحيح أو عشري وفقاً لإعدادات لغة المستخدم.

  • مثال: format-number(${income}) قد تُنسّق “120000” كـ “120,000”.

• round(field, digits): تُقرّب قيمة الحقل الرقمية إلى عدد محدد من الأرقام بعد الفاصلة العشرية.

  • مثال: round(${interest_rate}, 2)

• abs(number): تُعيد القيمة المطلقة لرقم.

• pow(base, exponent): تُعيد قيمة المعلمة الأولى مرفوعة إلى قوة المعلمة الثانية.

• log10(fieldorvalue): تُعيد اللوغاريتم الأساسي عشرة للحقل أو القيمة الممررة.

• sin(fieldorvalue): تُعيد الجيب للحقل أو القيمة الممررة، معبراً عنه بالراديان.

• cos(fieldorvalue): تُعيد جيب التمام للحقل أو القيمة الممررة، معبراً عنه بالراديان.

• tan(fieldorvalue): تُعيد الظل للحقل أو القيمة الممررة، معبراً عنه بالراديان.

• asin(fieldorvalue): تُعيد قوس الجيب للحقل أو القيمة الممررة، معبراً عنه بالراديان.

• acos(fieldorvalue): تُعيد قوس جيب التمام للحقل أو القيمة الممررة، معبراً عنه بالراديان.

• atan(fieldorvalue): تُعيد قوس الظل للحقل أو القيمة الممررة، معبراً عنه بالراديان.

• atan2(x, y): تُعيد الزاوية بالراديان المحصورة عند الأصل للنقطة ذات الإحداثيات (x, y) والمحور السيني الموجب. تكون النتيجة في النطاق من -pi() إلى pi().

• sqrt(fieldorvalue): تُعيد الجذر التربيعي غير السالب للحقل أو القيمة الممررة.

• exp(x): تُعيد قيمة e^x.

• pi(): تُعيد قيمة pi.

دوال التاريخ والوقت link

1. today(): تُعيد تاريخ اليوم كسلسلة نصية بتنسيق YYYY-MM-DD. تُقيَّم مرة واحدة عند فتح النموذج.

   • مثال: today() → '2024-03-15'

2. now(): تُعيد التاريخ والوقت الحاليين كسلسلة ISO 8601. تُقيَّم في كل مرة يُحسب فيها التعبير.

   • مثال: now() → '2024-03-15T14:32:00.000+03:00'

3. date(value): تحوّل قيمة (سلسلة نصية أو رقم) إلى سلسلة تاريخ.

   • مثال: date('2024-03-15') → '2024-03-15'

4. date-time(value): تحوّل قيمة إلى سلسلة تاريخ ووقت.

   • مثال: date-time(${event_timestamp})

5. decimal-date-time(value): تحوّل سلسلة تاريخ أو تاريخ ووقت إلى رقم عشري يمثل الميلي ثانية منذ حقبة Unix مقسومة على 86400000 (أي أيام كسرية منذ 1970-01-01). استخدم هذا لإجراء العمليات الحسابية على التواريخ.

   • مثال: المدة بالأيام بين تاريخين: decimal-date-time(${end_date}) - decimal-date-time(${start_date})
   • مثال: المدة بالدقائق بين وقتين: (decimal-date-time(${end_time}) - decimal-date-time(${start_time})) * 1440

6. format-date(date, format): تُنسّق قيمة تاريخ باستخدام سلسلة نمط.

   • رموز التنسيق: %Y (السنة 4 أرقام), %y (السنة رقمان), %m (الشهر 01–12), %d (اليوم 01–31), %a (اختصار يوم الأسبوع), %b (اختصار اسم الشهر)
   • مثال: format-date(today(), '%d/%m/%Y') → '15/03/2024'

7. format-date-time(datetime, format): تُنسّق قيمة تاريخ ووقت باستخدام سلسلة نمط. تقبل جميع رموز format-date بالإضافة إلى:

   • %H (الساعة 00–23), %h (الساعة 01–12), %M (الدقائق 00–59), %S (الثواني 00–59), %3 (الميلي ثانية), %P (ص/م)
   • مثال: format-date-time(now(), '%d/%m/%Y %H:%M') → '15/03/2024 14:32'

دوال Boolean link

1. boolean(value): تحوّل أي قيمة إلى boolean. تُعيد true للسلاسل غير الفارغة والأرقام غير الصفرية وtrue؛ تُعيد false للسلاسل الفارغة و0 وfalse.

2. boolean-from-string(string): تُعيد true إذا كانت السلسلة '1' أو 'true' (غير حساسة لحالة الأحرف)؛ تُعيد false بخلاف ذلك.

3. true(): تُعيد القيمة boolean true.

4. false(): تُعيد القيمة boolean false.

5. not(expression): تُعيد النفي المنطقي للتعبير. تُعيد true إذا كان التعبير false، والعكس صحيح.

   • مثال: not(${consent} = 'yes') — عرض تحذير عندما لم تُعطَ الموافقة.

دوال سلاسل نصية إضافية link

1. starts-with(string, prefix): تُعيد true إذا كانت string تبدأ بـ prefix.

   • مثال: starts-with(${phone}, '+254') تتحقق من أن رقم الهاتف يبدأ برمز كينيا الدولي.

2. contains(string, substring): تُعيد true إذا كانت string تحتوي على substring.

   • مثال: contains(${email}, '@') تتحقق من أن عنوان البريد الإلكتروني يحتوي على إشارة @.

3. substring-before(string, needle): تُعيد الجزء من string الذي يظهر قبل أول ظهور لـ needle.

4. substring-after(string, needle): تُعيد الجزء من string الذي يظهر بعد أول ظهور لـ needle.

5. normalize-space(string): تُزيل المسافات البيضاء في البداية والنهاية وتُقلّص جميع تسلسلات المسافات البيضاء الداخلية إلى مسافة واحدة.

6. translate(string, search_chars, replace_chars): تستبدل كل حرف في string يظهر في search_chars بالحرف المقابل في replace_chars.

دوال رياضيات إضافية link

1. floor(number): تُعيد أكبر عدد صحيح أقل من أو يساوي number.

   • مثال: floor(4.9) = 4

2. ceiling(number): تُعيد أصغر عدد صحيح أكبر من أو يساوي number.

   • مثال: ceiling(4.1) = 5

3. random(): تُعيد رقماً عشرياً عشوائياً بين 0.0 (شامل) و1.0 (غير شامل).

   • مثال: int(random() * 6) + 1 → رقم عشوائي من 1 إلى 6

4. coalesce(a, b): تُعيد a إذا كانت a غير فارغة؛ وإلا تُعيد b. مفيدة كخيار احتياطي عندما قد يكون الحقل فارغاً.

5. once(value): تُقيّم value وتخزنها، لكن فقط إذا كان الحقل الحالي فارغاً. إذا كان الحقل يحتوي بالفعل على قيمة، تُعيد once() القيمة الموجودة دون تغيير.

   • مثال: once(uuid()) يُنشئ UUID مرة واحدة ويُبقيه ثابتاً عبر إعادة التعديل.

دوال الجغرافيا link

1. area(geoshape_value): تحسب المساحة بالمتر المربع المحاطة بقيمة geoshape (مضلع).

   • مثال: area(${field_boundary}) — حساب مساحة حقل مُساحَح.
   • مثال: round(area(${field_boundary}) div 10000, 2) — التحويل إلى هكتار.

2. distance(coordinates): تحسب إجمالي طول المسار بالمتر لـ geotrace (خط)، أو المسافة بين نقطتَي geopoint.

   • مثال: round(distance(${road_trace}) div 1000, 3) — طول الطريق بالكيلومتر.

دوال التحقق link

1. regex(value, pattern): تُعيد true إذا كانت value تطابق نمط التعبير النمطي pattern. استخدم في عمود constraint للتحقق المبني على النمط.

   • مثال: regex(., '^[0-9]{10}$') — التحقق من رقم مكوّن من 10 أرقام.
   • مثال: regex(., '^[A-Z]{2}[0-9]{6}$') — التحقق من تنسيق رقم جواز سفر.

2. checklist(min, max, v1, v2, ...): تُقيّم قائمة من تعبيرات boolean وتُعيد true إذا كان عدد القيم true بين min وmax (شامل).

   • مثال: checklist(2, 3, ${q1} = 'yes', ${q2} = 'yes', ${q3} = 'yes') — تنجح إذا كانت 2 أو 3 من الشروط الثلاثة صحيحة.

3. weighted-checklist(min, max, v1, w1, v2, w2, ...): مثل checklist()، لكن لكل قيمة وزن. يجب أن يكون مجموع أوزان القيم true بين min وmax.

دوال مساعدة link

1. uuid(): يُنشئ UUID عشوائياً (تنسيق RFC 4122 v4) كسلسلة نصية.

   • يُستخدم عادةً مع once() لإنشاء معرّف فريد ثابت: once(uuid())

2. version(): تُعيد قيمة سمة version للنموذج كما هو محدد في ورقة عمل settings.

3. position(): عند الاستدعاء داخل مجموعة تكرار، تُعيد الفهرس يبدأ من 1 لمثيل التكرار الحالي.

4. thousandsep(length, separator, value): تُنسّق رقماً بفاصل آلاف.

   • مثال: thousandsep(0, ',', 1234567) → '1,234,567'

5. substr-jsonpath(value, jsonpath): تستخرج سلسلة فرعية من سلسلة JSON باستخدام تعبير JSONPath.

   • مثال: substr-jsonpath(${api_response}, '$.data.name') — استخراج حقل name من سلسلة JSON المخزنة في api_response.