تنسيق XLSReport
ما هو XLSReport
XLSReport هو تنسيق تأليف قائم على جداول البيانات لبناء تقارير DINO / AJF (Advanced JSON Forms) دون كتابة JSON أو شيفرة برمجية يدويًا. يقوم مؤلف التقرير بتعبئة مصنّف Excel عادي (.xlsx) وفق مجموعة من الاصطلاحات، فيقوم محوّل (xls-report.ts، وهو جزء من مكتبة reports في AJF) بتحليل ذلك المصنّف إلى مخطط JSON من نوع AjfReport يمكن لمنصة DINO عرضه كلوحة معلومات حيّة: جداول، ورسوم بيانية، وأرقام مؤشرات الأداء الرئيسية، وصور، ومخططات، وخرائط حرارية، والمزيد.
أمران يجعلان هذا ممكنًا:
- ربط الأوراق بالعناصر الرسومية — تصبح كل ورقة في المصنّف (مع بعض الاستثناءات الخاصة القليلة) عنصرًا رسوميًا واحدًا في التقرير. وترتيب الأوراق في المصنّف هو ترتيب تكديس العناصر الرسومية في التقرير المعروض.
- لغة صيغ مصغّرة (DSL) ("لغة المؤشرات") — لا تحتوي الخلايا على قيم حرفية فقط؛ بل يحتوي معظمها على تعبيرات قصيرة (مثل
SUM(D04, $persone, $tipo='corso')) مكتوبة بلغة مصغّرة مدمجة ومقيّدة بقائمة بيضاء. تُحلَّل هذه اللغة بواسطةhindikit-parser.tsوتُترجَم إلى JavaScript، ثم تُنفَّذ مقابل بيانات الـ form الأساسية وقت العرض/التحديث باستخدام مكتبة من الدوال المدمجة (expression-utils.ts).
يعني هذا أن XLSReport هو في الحقيقة أمران متراكبان معًا: وصف التخطيط (أي الأوراق تنتج أي العناصر الرسومية، وبأي ترتيب) ووصف الحساب (أي الصيغ تحسب الأرقام والمصفوفات ومجموعات البيانات التي تعرضها تلك العناصر الرسومية). ولأن البيانات الأساسية تأتي من form في Dino (البيانات)، فإن أي صيغة في XLSReport تقرأ في نهاية المطاف من مجموعة بيانات form واحدة أو أكثر وتشكّلها بما يلزم لأي عنصر رسومي (رقم واحد، أو مصفوفة لرسم بياني، أو جدول من الصفوف).
XLSReport محايد تجاه المنصة والمشروع: تنطبق اصطلاحات المصنّف نفسها على أي نسخة من DINO وأي مجموعة من الـ form — لا شيء في التنسيق خاص بمنظمة أو نشر معيّن.
بنية الملف
XLSReport هو مصنّف .xlsx واحد. يمرّ المحوّل على أوراق المصنّف بالترتيب ويقرّر ما سيفعله بكل ورقة من خلال البحث عن كلمة مفتاحية كجزء من نص اسم الورقة (وليس مطابقة تامة) — فمثلًا الورقة المسماة table_activities أو 2_table تُعرَّف كلتاهما كورقة "table" لأن الاسم يحتوي على table.
فئات الأوراق
| يحتوي اسم الورقة على | الدور |
|---|---|
variables (الاسم بالضبط) |
يعلن متغيرات/مجموعات بيانات مُسمّاة تستخدمها الأوراق اللاحقة. لا ينتج عنصرًا رسوميًا بنفسه. |
filter |
يعلن form فلترة (بنمط ODK/XLSForm: survey + choices) مرتبطًا بالورقة التالية في المصنّف. لا ينتج عنصرًا رسوميًا خاصًا به. |
filter و global |
كما سبق، لكن الفلتر الناتج ينطبق على التقرير بأكمله بدلًا من عنصر رسومي واحد. |
choices |
ورقة مرافقة تحتوي قوائم الخيارات (list_name، name، label)، تُستخدم مع أوراق filter. |
table |
عنصر رسومي من نوع DynamicTable أو PaginatedTable. |
chart |
عنصر رسومي من نوع Chart (أعمدة، خطي، دائري، إلخ). |
image |
عنصر رسومي من نوع Image. |
html |
عنصر رسومي من نوع Text يعرض HTML خامًا. |
graph |
عنصر رسومي من نوع Graph (عُقد/شبكة). |
heatmap |
عنصر رسومي من نوع HeatMap. |
single |
عنصر رسومي واحد أو أكثر من نوع Text يشكّل بطاقة مؤشر أداء رئيسي/"رقم كبير". |
paginatedlist |
عنصر رسومي من نوع PaginatedList (كل صف = عنصر جدول مصغّر). |
paginatedDialogList |
عنصر رسومي من نوع PaginatedList تفتح صفوفه مربّع حوار تفاصيل. |
أسماء الأوراق حرّة فيما عدا ذلك — استخدمها لإبقاء المصنّف موثّقًا ذاتيًا (مثل table_beneficiaries_by_month، chart_gender_split). ولأن المطابقة تتم عبر البحث عن نص فرعي، تجنّب اختيار أسماء تحتوي على نحو غير مقصود كلمة مفتاحية أخرى (مثلًا لا تسمِّ ورقة رسم بياني charttable).
اصطلاحات الصفوف داخل الورقة
تُقرأ كل ورقة عنصر رسومي كتحويل عادي من جدول بيانات إلى JSON: الصف الأول يحتوي ترويسات الأعمدة، ومن الصف الثاني فصاعدًا تبدأ البيانات، بكائن JSON واحد لكل صف مفتاحه نص الترويسة. وإلى جانب هذه القاعدة العامة، يحدّد كل نوع ورقة معناه الخاص لصف الترويسة وأول صف أو صفّين من صفوف البيانات (موثّق لكل عنصر رسومي في القسم 5).
التخطيط العام
يُغلَّف المصنّف بأكمله في تخطيط واحد على المستوى الأعلى يحتوي على عمود واحد، وتساهم كل ورقة غير خاصة بعنصر رسومي واحد بالضبط (أو، في حالة single، بعدة عناصر) يُلحق بهذا العمود بترتيب الأوراق. بعبارة أخرى:
- التقرير دائمًا مكدّس رأسي واحد من العناصر الرسومية — لا توجد طريقة على مستوى جدول البيانات لإنشاء أعمدة متجاورة أو حاويات متداخلة؛ التداخل الوحيد الموجود يتولّد داخليًا عبر
paginatedlist/paginatedDialogList(إذ يكون كل صف بحد ذاته عنصر جدول مصغّرًا أو مربّع حوار). - الورقة المسماة
filterتربط فلترها بأي ورقة عنصر رسومي تأتي مباشرة بعدها؛ أما ورقةglobal filterفترتبط بالحاوية الخارجية للتقرير بدلًا من عنصر رسومي واحد.
المخرج العام الشامل: js:
يمكن لأي خلية تُحلَّل عادةً عبر لغة الصيغ DSL أن تبدأ بدلًا من ذلك بـ js: — حيث يُعامَل كل ما يأتي بعد هذه البادئة كـ JavaScript خام ويُمرَّر دون تحليل. يتيح هذا الوصول إلى كل دالة تصدّرها مكتبة الأدوات المساعدة وقت التشغيل، وليس فقط تلك المدرجة في القائمة البيضاء لقواعد اللغة DSL (انظر القسم 4)، وإلى تعبيرات JS اعتباطية (دوال IIFE، واستخدام Set/Map، ودوال مساعدة سطرية مخصّصة، إلخ). استخدمه عندما لا يتوافق حساب ما مع القائمة البيضاء لدوال DSL أو أشكال الوسائط الخاصة بها.
إعلان المتغيرات
ورقة variables هي المكان الذي تحمّل فيه بيانات الـ form وتحسب مسبقًا أي شيء يُعاد استخدامه في عناصر رسومية متعددة لاحقًا في المصنّف (مجموعات بيانات، وفلاتر، وقيم مؤشرات، وتسميات).
الأعمدة
| العمود | المعنى |
|---|---|
name |
معرّف المتغير. يجب أن يكون معرّفًا صالحًا (حروف، أرقام، شرطة سفلية، ولا يبدأ برقم) — تُرفض الأسماء غير الصالحة. |
value |
تعبير، يُحلَّل عبر لغة الصيغ DSL نفسها كما في كل خلية أخرى (أو JavaScript خام بادئته js:). |
isAIPrompt (اختيارية) |
قيمة منطقية؛ تشير إلى أن المتغير نتيجة طلب ذكاء اصطناعي وليس صيغة عادية، بحيث يمكن لاحقًا قراءته بـ PROMPT_RESULT. |
تُتجاهل الصفوف ذات الـ name الفارغ. تُقيَّم المتغيرات من الأعلى إلى الأسفل، ويمكن لكل متغير الإشارة إلى أي متغير معلن أعلاه باسمه المجرّد (بدون بادئة $ — فهذه البادئة محجوزة لـ حقول الـ form، انظر القسم 4).
تحميل بيانات الـ form
تتوفّر دائمًا عمليتا بحث وقت التشغيل:
forms['<form name>']— المصفوفة الخام للبيانات الخاصة بـ form معيّن في Dino.schemas['<form name>']— مخطط الـ form (يُستخدم لحل بنية المجموعة المتكرّرة وتسميات الخيارات).
سلسلة اسم الـ form الواجب استخدامها هي المعرّف الذي تعطيه DINO لذلك الـ form — احصل عليه من إعدادات المسؤول/الـ form في نسختك (سيتطابق عادةً، لكن ليس مضمونًا أن يتطابق تمامًا، مع اسم ملف xlsform الخاص بالـ form؛ تحقّق من فروق المسافات/حالة الأحرف/المسافات الزائدة).
الكتلة الافتتاحية المعيارية لورقة variables تحمّل كل form تحتاجه وتحوّله إلى مجموعة بيانات منظّمة:
name | value
F01 | forms['my_form_name']
S01 | schemas['my_form_name']
D01 | BUILD_DATASET(F01,S01)
يقوم BUILD_DATASET(forms, schema) بتقسيم كل مجموعة بيانات مسطّحة إلى حقول علوية غير متكرّرة بالإضافة إلى كائن reps يجمّع حالات المجموعة المتكرّرة ("repeat"/slide) حسب اسمها الحقيقي للمجموعة (المستخرج من المخطط). وبدون مخطط، يعود إلى أسلوب استدلالي عام. من هذه النقطة فصاعدًا، D01 هو مجموعة البيانات التي تفلترها وتجمّعها وتعرضها.
تحديد نطاق مجموعة بيانات / فلترتها مرة واحدة، لكل استخدام لاحق
من الأنماط الشائعة جدًا والموصى بها فلترة مجموعة بيانات وإعادة إسنادها إلى اسم المتغير نفسه، بحيث يرث تلقائيًا كل تعبير يشير إلى ذلك المتغير من تلك النقطة فصاعدًا الفلتر — بدلًا من تكرار شرط الفلترة في كل صيغة على حدة:
name | value
D01 | FILTER_BY(D01, $status='active')
هذا مهم بشكل خاص لأن مجموعات بيانات الـ form غالبًا ما تكون مشتركة بين أكثر من مشروع أو حملة أو نطاق على نسخة DINO نفسها — لا تفترض أبدًا أن مصفوفة forms['...'] مقتصرة مسبقًا على البيانات التي تهمّك فقط. إذا كانت الـ form لديك تحمل حقل مشروع/نطاق (يعتمد اسمه بالضبط على تصميم الـ form في نسختك، مثل شيء كـ $project_name)، ففلتر كل مجموعة بيانات صراحةً:
scope_name = 'MY PROJECT'
D0X = FILTER_BY(D0X, $project_field = scope_name OR $secondary_project_field = scope_name)
إذا كانت مجموعة بيانات تحتوي مجموعة متكرّرة تحتاج حالاتها الفردية إلى تحديد نطاق خاص بها (مثلًا repeat لـ "المشاركين" حيث يمكن أن يتضمن سجل جماعي واحد مشاركين ينتمون إلى نطاقات مختلفة)، ففلتر على مستوى كل حالة أيضًا، عادةً عبر FLATTEN_REPS مع FILTER_BY على المصفوفة المسطّحة، قبل استخراج القيم التي تحتاجها بـ ALL_VALUES_OF (انظر القسم 4 لهذه الدوال). تحقّق دائمًا من الحقل الذي يحمل فعليًا قيمة تعريف/مرجع الحالة المتكرّرة — فقد لا يحمل ما يوحي به اسمه (مثلًا، قد يخزّن حقل مرجع "المشارك" داخل repeat اسم العرض للسجل المرتبط بدلًا من الرمز/المعرّف الخاص به؛ تحقّق مقابل بيانات مُصدَّرة حقيقية قبل الربط/إزالة التكرار بناءً عليه، واستخدم المفتاح نفسه على طرفي أي مقارنة).
متغيرات طلب الذكاء الاصطناعي
إذا كانت isAIPrompt مضبوطة على صف متغير، فإن قيمته تمثّل نتيجة طلب أنشأه الذكاء الاصطناعي وليس صيغة محسوبة عادية. وفي أي مكان آخر في المصنّف يمكنك استرجاع ذلك النص بـ PROMPT_RESULT(report_data, '<variable name>') وإدراجه في عنصر رسومي من نوع HTML أو مؤشر فردي.
نظرة عامة على لغة الصيغ DSL
تُحلَّل كل خلية غير بادئتها js: بواسطة محلّل صغير تنازلي تعاودي إلى تعبير JavaScript، ثم تُقيَّم مقابل سياق بيانات وقت التشغيل.
البنية الأساسية
| البنية | المعنى |
|---|---|
$fieldname |
مرجع لحقل في الـ form. يُترجَم إلى form.fieldname (حيث form هو السجل الذي في النطاق في ذلك الجزء من التعبير). |
bareIdentifier |
مرجع إلى اسم في ورقة variables، أو اسم دالة، أو كلمة مفتاحية حرفية. |
'text' / "text" |
نص حرفي. |
123، 1.5، 1e3 |
رقم حرفي. |
[a, b, c] |
مصفوفة حرفية. |
func(arg1, arg2, ...) |
استدعاء دالة — تُقبل أسماء الدوال المدرجة في القائمة البيضاء فقط (انظر أدناه)؛ وأي شيء آخر يجب أن يمرّ عبر js:. |
= |
يساوي (يُترجَم إلى == في JS). |
!= |
لا يساوي. |
+ - * / ، < <= > >= |
حسابي / مقارنة، بالمعنى نفسه كما في JavaScript. |
AND / OR |
و / أو المنطقية (تُترجَم إلى && / \|\|). |
!expr |
النفي المنطقي. |
(expr) |
تجميع. |
IF(cond, thenExpr, elseExpr) |
شرط ثلاثي — صيغة خاصة مدمجة، وليست دالة عادية. |
مثال:
IF($age >= 18 AND $status = 'active', 'adult-active', 'other')
→ (form.age >= 18 && form.status == 'active' ? 'adult-active' : 'other')
أنواع الوسائط
لأن لغة DSL تُترجَم إلى JavaScript لكن يجب أن تعرف كيف تُفسّر كل وسيطة دالة، فإن لكل دالة مدرجة في القائمة البيضاء توقيع وسائط ثابت مكوّن من هذه الأنواع:
arg— يُحلَّل كتعبير عادي ويُمرَّر كما هو (بحيث يصبح$fieldهوform.field، أي قيمة الحقل).field— يُحلَّل كتعبير؛ وإذا تبيّن أنه مرجع مجرّد لـ$field، يُحوَّل إلى سلسلة اسم الحقل المُقتبسة بدلًا من قيمة الحقل (مثلًا$age←'age')، لأن الدالة تتوقع معرفة أي حقل ستعمل عليه، لا قيمةً.func(form)،func(elem)،func(elemA, elemB)— تُحلَّل كتعبير (عادةً شرط منطقي/علائقي مكتوب بـ$field)، ثم تُغلَّف في دالة سهمية JS بأسماء المعاملات المذكورة، فمثلًا$gender = 'male'كوسيطةfunc(form)تصبح(form) => form.gender == 'male'.- علامة
?اللاحقة على وسيطة تشير إلى أنها اختيارية — إذا حذفتها حذفت كل ما يأتي بعدها.
معرفة نوع الوسيطة تخبرك متى تكتب $field (للإشارة إلى القيمة الحالية لحقل) مقابل متى تتحول بنية $field نفسها بصمت إلى سلسلة اسم حقل.
مرجع الدوال
تحميل مجموعات البيانات وتشكيلها
| الدالة | التوقيع (الأنواع) | الوصف |
|---|---|---|
BUILD_DATASET |
(arg, arg?) |
يقسّم البيانات المسطّحة إلى حقول علوية + reps (حالات المجموعات المتكرّرة)، باستخدام المخطط إن وُجد. |
FLATTEN_REPS |
(arg, arg) |
ينتج صف إخراج واحد لكل حالة من مجموعة متكرّرة مُسمّاة، دامجًا الحقول العلوية للأصل مع حقول تلك الحالة. |
FROM_REPS |
(arg, func(form)) |
يقيّم تعبيرًا مرة واحدة لكل حالة مجموعة متكرّرة (عبر كل السجلات المعطاة)، جامعًا النتائج غير الفارغة في مصفوفة مسطّحة. |
APPLY |
(arg, field, func(form)) |
يعيد نسخة من مجموعة البيانات مع حقل جديد/مشتق مضبوط على كل سجل (وحالات التكرار الخاصة به). |
APPLY_LABELS |
(arg, arg, arg) |
يستبدل قيم الخيارات الخام بتسمياتها المقروءة بشريًا (من المخطط) لقائمة أسماء الحقول المعطاة، على كل سجل وحالات تكراره. |
GET_LABELS |
(arg, arg) |
بحث مستقل: يربط مصفوفة من قيم الخيارات الخام بتسمياتها باستخدام مخطط. |
MAP |
(arg, func(elem)) |
دالة map عادية للمصفوفات. |
OP |
(arg, arg, func(elemA, elemB)) |
يقرن مصفوفتين عنصرًا بعنصر، دامجًا كل زوج بتعبير ثنائي. |
JOIN_FORMS |
(arg, arg, field, field?) |
ربط أيسر لمجموعتي بيانات عبر مطابقة حقل مفتاح على كل طرف. |
JOIN_REPEATING_SLIDES |
(arg, arg, field, field, field, field?) |
مثل JOIN_FORMS، لكنه يربط أيضًا حالات المجموعة المتكرّرة لكل زوج متطابق عبر مفتاح فرعي. |
الفلترة
| الدالة | التوقيع | الوصف |
|---|---|---|
FILTER_BY |
(arg, func(form)) |
يعيد نسخة مفلترة من مجموعة بيانات؛ يحتفظ بسجل إذا طابق على المستوى العلوي، أو يحتفظ فقط بحالات المجموعة المتكرّرة المطابقة إذا كانت المطابقة على ذلك المستوى. |
العدّ والتجميع
| الدالة | التوقيع | الوصف |
|---|---|---|
COUNT_FORMS |
(arg, func(form)?) |
يعدّ السجلات المطابقة لشرط، محاسبًا كل سجل مرة واحدة حتى لو طابق الشرط أكثر من حالة تكرار واحدة فيه. |
COUNT_REPS |
(arg, func(form)?) |
يعدّ كل سجل علوي مطابق وكل حالة تكرار مطابقة كلٌّ على حدة — استخدمه لـ "عدد مرات الحدوث" بدلًا من "عدد السجلات". |
SUM |
(arg, field, func(form)?) |
مجموع حقل رقمي عبر السجلات وحالات التكرار، مع فلتر اختياري. |
MEAN / MEDIAN / MODE / MIN / MAX |
(arg, field, func(form)?) |
إحصاءات تجميعية معيارية مع فلتر اختياري. |
ALL_VALUES_OF |
(arg, field, func(form)?) |
يجمع كل قيمة يأخذها حقل عبر السجلات وحالات التكرار المطابقة لفلتر اختياري، مع إزالة التكرار. الأداة المعيارية لـ "عدّ X المتميزة": غلّفها بـ LEN(...). |
LEN |
(arg) |
طول مصفوفة. |
REMOVE_DUPLICATES |
(arg) |
يزيل التكرار من مصفوفة (بمطابقة التساوي العميق)، مع الحفاظ على الترتيب. |
INCLUDES |
(arg, arg) |
هل تحتوي مصفوفة (أو سلسلة) على قيمة. |
التواريخ
| الدالة | التوقيع | الوصف |
|---|---|---|
TODAY |
() |
تاريخ اليوم، YYYY-MM-DD. |
ADD_DAYS |
(arg, arg) |
تاريخ زائد N يومًا. |
DAYS_DIFF |
(arg, arg) |
فرق الأيام الكاملة بين تاريخين. |
GET_AGE |
(arg, arg?) |
العمر بالسنوات الكاملة بناءً على تاريخ الميلاد (وتاريخ مرجعي اختياري، افتراضه اليوم). |
IS_BEFORE / IS_AFTER |
(arg, arg) |
مقارنات تواريخ. |
IS_WITHIN_INTERVAL |
(arg, arg, arg) |
فحص نطاق تاريخي شامل للطرفين. |
COMPARE_DATE |
(arg, arg, arg, arg?) |
يصنّف تاريخًا كسابق/داخل/لاحق لنطاق، مع تسميات مخصّصة اختيارية. |
الأرقام والتنسيق
| الدالة | التوقيع | الوصف |
|---|---|---|
ROUND |
(arg, arg?) |
يقرّب رقمًا إلى N منزلة عشرية (افتراضيًا 0). |
PERCENT |
(arg, arg) |
a/b كنسبة مئوية نصية. |
PERCENTAGE_CHANGE |
(arg, arg) |
نسبة التغيّر بين قيمة وقيمة مرجعية. |
CHART_TO_DATA |
(arg, arg) |
يقرن مصفوفتي تسميات/قيم متوازيتين في كائن واحد. |
FORMAT_TABLE_ROWS / FORMAT_TABLE_COLS / FORMAT_TABLE_FIELDS |
متعدّدة | تعرض مصفوفة من الصفوف/الأعمدة/السجلات كسلسلة HTML <table>، مفيدة داخل عناصر html. |
الاختيار
| الدالة | التوقيع | الوصف |
|---|---|---|
FIRST / LAST |
(arg, func(form), field?) |
يجد السجل الأبكر/الأحدث حسب حقل تاريخ (افتراضيًا حقل "تاريخ الإنشاء" المعياري) ويقيّم تعبيرًا عليه. |
الذكاء الاصطناعي / التنقيح
| الدالة | التوقيع | الوصف |
|---|---|---|
PROMPT_RESULT |
(arg, arg) |
يسترجع النص الذي أنتجه متغير isAIPrompt. |
CONSOLE_LOG |
(arg) |
يسجّل قيمة في وحدة التحكم ويعيدها دون تغيير — مفيدة لتنقيح صيغة ضمن السطر. |
مهملة (محتفظ بها للتوافق الخلفي؛ يُفضّل البديل المذكور)
| الدالة | يُفضّل بدلًا منها |
|---|---|
FILTER_BY_VARS |
FILTER_BY |
COUNT_FORMS_UNIQUE |
LEN(ALL_VALUES_OF(...)) |
ISIN |
INCLUDES |
REPEAT |
MAP |
EVALUATE |
IF |
خارج القائمة البيضاء
تقبل لغة DSL الدوال المذكورة أعلاه فقط (إضافة إلى IF). وتكشف مكتبة وقت التشغيل الأساسية دوال مساعدة إضافية (مساعدات إحصائية مثل الانحراف المعياري، وبانيات داخلية للجداول/مجموعات بيانات العناصر الرسومية يستخدمها المحوّل نفسه، إلخ) لا يمكن الوصول إليها عبر بنية الصيغة العادية — فقط عبر المخرج الشامل لـ JavaScript الخام js: الموصوف في القسم 2.4.
العناصر الرسومية المدعومة وخصائصها
table — جدول ديناميكي
الصف الأول: تسميات ترويسات الأعمدة. الصف الثاني: رمز نمط قصير لكل عمود، [colspan][alignment][sortable]:
- الحرف الأول: colspan (رقم، عادةً
1). - الحرف الثاني:
l= يسار،r= يمين، أي شيء آخر = توسيط. - الحرف الثالث:
s= عمود قابل للفرز، إغفاله/أي شيء آخر = غير قابل للفرز.
من الصف الثالث فصاعدًا، تعمل الورقة بإحدى وضعيتين:
أ. جدول قائمة form (مرتبط بمجموعة بيانات) — يُستخدم عند وجود عمود dataset:
| عمود الإعداد | المعنى |
|---|---|
| (العمود الخاص بكل ترويسة) | اسم الحقل الواجب عرضه في ذلك العمود، المستخرج من كل سجل في مجموعة البيانات. |
dataset |
اسم المتغير (ذو القيمة المصفوفية) الواجب التكرار عليه — عادةً مجموعة بيانات بُنيت في variables. |
pagination |
قيمة صادقة ← ينتج جدولًا مُصفّحًا بالصفحات بدلًا من جدول عادي. |
dialog_fields / dialog_fields_labels |
أسماء حقول/تسميات إضافية مفصولة بفواصل تُعرض في مربّع حوار تفاصيل "اقرأ المزيد" لكل صف. |
link_field / link_position |
الحقل الواجب استخدامه كعنوان URL للرابط، وفهرس العمود الذي يجب أن يعرضه كرابط. |
ب. جدول ثابت / محسوب (بدون عمود dataset) — كل صف متبقٍّ هو صف إخراج حرفي، وكل خلية بحد ذاتها صيغة (أو قيمة حرفية، أو تعبير js:)؛ ضع السلسلة الحرفية بين علامتي اقتباس حتى لا تُخطئ بوصفها مرجعًا لمتغير مجرّد (مثلًا "140" للنص 140، مقابل my_indicator لعرض قيمة متغير محسوب).
تُنسَّق خلايا الترويسة موسّطة، عريضة، بنص أبيض على خلفية صلبة؛ وتتبادل خلايا المتن ألوان خلفية الصفوف تلقائيًا.
chart
الصف الأول فقط (باستثناء Scatter/Bubble، انظر أدناه). أعمدة الخيارات المعروفة (تُزال من الصف قبل معاملة البقية كسلاسل بيانات):
chartType، title، stacked، beginAtZeroX، beginAtZeroY، axisLabelX، axisLabelY، axisMinX، axisMinY، axisMaxX، axisMaxY، removeZeroValues، mainDataNumberThreshold.
- يجب أن تكون
chartTypeواحدة من:Line،Bar،HorizontalBar،Radar،Scatter،Doughnut،Pie،PolarArea،Bubble. labels(اختيارية) — صيغة تنتج مصفوفة تسميات الفئات/المحاور.- كل ترويسة عمود أخرى تسمّي سلسلة بيانات واحدة؛ وقيمة خليتها صيغة تنتج مصفوفة الأرقام لتلك السلسلة.
- تحتاج رسوم
Scatterإلى صفّي بيانات بالضبط (قيم X، قيم Y)؛ وتحتاج رسومBubbleإلى ثلاثة بالضبط (X، Y، نصف القطر)؛ وتحتاج كل أنواع الرسوم الأخرى إلى صف بيانات واحد بالضبط. - تُسنَد الألوان تلقائيًا من لوحة ألوان مدمجة (لون لكل سلسلة، أو لون لكل نقطة بيانات في الرسوم الدائرية/المجوّفة/القطبية).
image
الصف الأول فقط. مطلوب: url (صيغة تنتج عنوان URL للصورة، أو سلسلة حرفية؛ اسبقها بـ js: لتعبير JS خام). اختياري: align (left/center/right)، width، height (سلاسل أطوال CSS).
html
الصف الأول فقط، بعمود واحد html، يحمل سلسلة HTML خام (لا تحلّلها لغة الصيغ DSL). يدعم علامات إدراج [[expression]] ذات القوسين المزدوجين، التي تُقيَّم وتُستبدل وقت العرض — استخدمها لتضمين قيمة متغير محسوب داخل ترميز ثابت otherwise.
single — بطاقة مؤشر أداء رئيسي / رقم كبير
الصف الأول فقط:
| العمود | المعنى |
|---|---|
html (اختيارية) |
ترويسة تُعرض أعلى الرقم. |
current_value |
مطلوب. المتغير/التعبير الذي تُعرض قيمته كرقم كبير (يُعرض عبر [[current_value]]). |
percentage_change (اختيارية) |
إن وُجد، يضيف مؤشر اتجاه (سهم صاعد/هابط/مستوٍ مع لون) بناءً على إشارته، يُعرض كـ [[percentage_change]]%. |
ولأن نص الخلية نفسه يُعاد استخدامه كقيمة مُدرَجة وكتعبير مقارنة خام معًا، يُستحسن عمومًا أن يكون current_value / percentage_change أسماء متغيرات مجرّدة معرّفة في ورقة variables، لا صيغًا سطرية كاملة.
graph
يحتاج كل صف إلى عمود id غير فارغ. وكل عمود في كل صف (بخلاف id) يُحلَّل كصيغة، منتجًا مجموعة بيانات عقدة رسم بياني واحدة لكل صف.
heatmap
الصف الأول فقط، وكل الأعمدة اختيارية بقيم افتراضية معقولة: values (سلسلة JS خام/صيغة تنتج بيانات الشدة — لا تُحلَّل عبر DSL الأقواس، ويجب أن تكون صالحة مسبقًا)، idProp (افتراضيًا 'id')، features (سلسلة GeoJSON)، startColor، endColor، highlightColor، showVisualMap.
paginatedlist
الصف الأول: نسبة عرض عمود رقمية لكل عمود. الصف الثاني (صف الإعداد): اسم الحقل لكل عمود، إضافة إلى dataset، title، pageSize (افتراضيًا 10)، link_field/link_position، cellStyles، rowStyle (قيمة كائن نمط حرفية خام)، backgroundColorA/backgroundColorB (ألوان التخطيط المخطّط). ويُعرض كل صف ناتج كعنصر جدول مدمج خاص به بدلًا من جدول واحد كبير.
paginatedDialogList
الإعداد نفسه الخاص بـ paginatedlist، إضافة إلى صفّين إضافيين (عند وجودهما): تسميات حقول مربّع الحوار، ثم أسماء حقول مربّع الحوار — حيث يؤدي النقر على صف إلى فتح نافذة منبثقة تسرد تلك الحقول كأزواج تسمية/قيمة.
filter / global filter
منظّمة كورقة survey بنمط ODK/XLSForm (مع ورقة choices مرافقة في المصنّف نفسه)، وتُحوَّل إلى مخطط form وتُربط كعنصر تحكم تفاعلي للفلترة:
- الورقة المسماة
filter(لكن ليسglobal) ترتبط بعنصر رسومي في الورقة التالية مباشرة. - الورقة المسماة بـ
filterوglobalمعًا ترتبط بالتقرير بأكمله بدلًا من عنصر رسومي واحد.
قائمة تحقّق سريعة لبناء XLSReport جديد
- حدّد form في DINO الذي تحتاجه وأسماء الـ form/المخططات الدقيقة له في نسختك.
- ابدأ ورقة
variables: حمّل كل form بـforms[...]/schemas[...]، وابنِ مجموعات البيانات بـBUILD_DATASET، وطبّق أي فلاتر مشروع/نطاق فورًا (بإعادة إسناد اسم المتغير نفسه). - احسب مسبقًا أي شيء يُعاد استخدامه في أكثر من عنصر رسومي كمتغير مسمّى خاص به.
- أضف ورقة لكل عنصر رسومي، مسماة بالكلمة المفتاحية الصحيحة، بالترتيب الذي تريد ظهورها به.
- فضّل القائمة البيضاء لـ DSL في القسم 4.3؛ ولا تلجأ إلى
js:إلا عندما لا يتوافق حساب ما معها. - تحقّق مزدوجًا من أسماء الحقول وقيم الخيارات مقابل المخطط الفعلي/البيانات المُصدَّرة في نسختك بدلًا من افتراض أنها تطابق أسماء حقول xlsform المصدرية تمامًا.