Skip to content

Add report field codes, filters, and radar chart docs #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add report field codes, filters, and radar chart docs #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 108 additions & 0 deletions ar/features/report.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ openyida append-chart APP_XXXXXX REPORT_XXXXX '{
| **pivot** | جدول محوري متقاطع | تحليل متعدد الأبعاد |
| **gauge** | مقياس | تتبع التقدم أو الأهداف |
| **funnel** | رسم بياني قمعي | التحويل عبر المراحل |
| **radar** | رسم بياني رادار | مقارنة متعددة المتغيرات |

---

Expand Down Expand Up @@ -179,6 +180,99 @@ openyida append-chart APP_XXXXXX REPORT_XXXXX '{
}
```

### مؤشر (KPI)

```json
{
"type": "indicator",
"title": "Total Revenue",
"cubeCode": "form_uuid",
"kpiField": "numberField_amount",
"aggregation": "sum"
}
```

### مقياس

```json
{
"type": "gauge",
"title": "Completion Rate",
"cubeCode": "form_uuid",
"kpiField": "numberField_rate",
"aggregation": "avg"
}
```

### رسم بياني رادار

```json
{
"type": "radar",
"title": "Performance Overview",
"cubeCode": "form_uuid",
"xField": "selectField_category_value",
"yField": [
{ "fieldCode": "numberField_score1", "aggregateType": "AVG" },
{ "fieldCode": "numberField_score2", "aggregateType": "AVG" }
]
}
```

---

## رموز الحقول في التقارير

عند الإشارة إلى حقول النموذج في تعريفات الرسوم البيانية للتقارير، تستخدم معظم أنواع الحقول معرّف الحقل مباشرة (مثل `textField_abc123`). ومع ذلك، تتطلب الحقول من نوع الاختيار — مثل `SelectField` و `RadioField` و `CheckboxField` و `EmployeeField` و `DepartmentSelectField` — إضافة اللاحقة `_value` إلى معرّف الحقل.

| Field type | Field ID example | Report field code |
|------------|------------------|-------------------|
| TextField | textField_abc123 | textField_abc123 |
| NumberField | numberField_abc123 | numberField_abc123 |
| DateField | dateField_abc123 | dateField_abc123 |
| SelectField | selectField_abc123 | selectField_abc123_value |
| RadioField | radioField_abc123 | radioField_abc123_value |
| CheckboxField | checkboxField_abc123 | checkboxField_abc123_value |
| EmployeeField | employeeField_abc123 | employeeField_abc123_value |
| DepartmentSelectField | departmentSelectField_abc123 | departmentSelectField_abc123_value |

<Tip>
استخدم `openyida get-schema` للحصول على هيكل النموذج وتحديد رموز الحقول الصحيحة لرسومك البيانية.
</Tip>

<Warning>
استخدام معرّف الحقل بدون اللاحقة `_value` للحقول من نوع الاختيار سيؤدي إلى بيانات فارغة أو غير صحيحة في الرسم البياني.
</Warning>

---

## تنسيق الحقل البديل

بدلاً من استخدام `xField` و `yField` كسلاسل نصية، يمكنك استخدام مصفوفة `fields` لتحديد مقاييس متعددة مع أنواع تجميع فردية:

```json
{
"type": "bar",
"title": "Multi-measure Chart",
"cubeCode": "form_uuid",
"xField": "selectField_category_value",
"yField": [
{ "fieldCode": "numberField_amount", "aggregateType": "SUM" },
{ "fieldCode": "numberField_count", "aggregateType": "COUNT" }
]
}
```

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

---

## المرشحات

تُنشئ الحقول من نوع الاختيار (SelectField و RadioField و CheckboxField وغيرها) مرشحات تلقائيًا في التقرير. عندما يستخدم الرسم البياني حقلاً من نوع الاختيار كـ `xField`، تعرض واجهة التقرير قائمة منسدلة للتصفية تتيح للمستخدمين تصفية بيانات الرسم البياني بشكل تفاعلي.

لا حاجة لأي تكوين إضافي — يتم إنشاء المرشحات بناءً على نوع الحقل في هيكل النموذج.

---

## دوال التجميع
Expand All @@ -190,6 +284,7 @@ openyida append-chart APP_XXXXXX REPORT_XXXXX '{
| **count** | العد |
| **max** | القيمة القصوى |
| **min** | القيمة الدنيا |
| **count_distinct** | عدد القيم الفريدة |

---

Expand Down Expand Up @@ -248,9 +343,22 @@ openyida create-report APP_XXXXXX "Sales Analysis Report" ./sales-report-charts.

---

## التحقق من التكوين

قبل إنشاء التقرير، تحقق من تكوين الرسوم البيانية لتجنب الأخطاء الشائعة:

1. **تحقق من رموز الحقول** — قم بتشغيل `openyida get-schema` للتحقق من معرّفات الحقول والتأكد من أن الحقول من نوع الاختيار تتضمن اللاحقة `_value`.
2. **تحقق من مصدر البيانات** — تأكد من أن `dataSource` أو `cubeCode` يطابق UUID نموذج صالح في تطبيقك.
3. **تحقق من أنواع التجميع** — تأكد من أن دالة التجميع متوافقة مع نوع الحقل (مثلاً، `sum` يعمل فقط على الحقول الرقمية).
4. **اختبر برسم بياني واحد** — ابدأ برسم بياني واحد للتحقق من التكوين قبل إضافة عدة رسوم بيانية.

---

## أفضل الممارسات

1. **اختر نوع الرسم البياني المناسب** - الاتجاهات بالخطي، المقارنات بالعمودي، النسب بالدائري
2. **تحكم في عدد الرسوم البيانية** - يُنصح بعدم تجاوز 6 رسوم بيانية لكل تقرير
3. **استخدم جداول البيانات** - أكمل الرسوم البيانية بجداول لفحص البيانات المفصلة
4. **اضبط أحجام الصفحات المناسبة** - يُنصح بـ 10-20 سجلًا لكل صفحة للجداول
5. **استخدم get-schema لاكتشاف الحقول** - قم بتشغيل `openyida get-schema` للحصول على رموز الحقول الصحيحة قبل بناء تعريفات الرسوم البيانية
6. **استفد من المرشحات التلقائية** - تُنشئ الحقول من نوع الاختيار مرشحات تقارير تلقائيًا، استخدمها كـ `xField` للوحات المعلومات التفاعلية
2 changes: 1 addition & 1 deletion ar/features/skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ openyida create-form create <appType> "<اسم النموذج>" <JSON الحقو
# تحديث النموذج
openyida create-form update <appType> <formUuid> <JSON التعديلات>

# الحصول على Schema النموذج
# الحصول على Schema النموذج (يُرجع معرّفات الحقول ورموز حقول التقارير)
openyida get-schema <appType> <formUuid>

# تحديث تكوين النموذج
Expand Down
108 changes: 108 additions & 0 deletions de/features/report.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ openyida append-chart APP_XXXXXX REPORT_XXXXX '{
| **pivot** | Kreuz-Pivottabelle | Mehrdimensionale Analyse |
| **gauge** | Messgerät-Diagramm | Fortschritts- oder Zielverfolgung |
| **funnel** | Trichterdiagramm | Stufenweise Konversion |
| **radar** | Radardiagramm | Mehrvariablenvergleich |

---

Expand Down Expand Up @@ -179,6 +180,99 @@ Das Setzen von `w` oder `h` auf `0` ist gültig und wird berücksichtigt. Bei Au
}
```

### Kennzahl (KPI)

```json
{
"type": "indicator",
"title": "Total Revenue",
"cubeCode": "form_uuid",
"kpiField": "numberField_amount",
"aggregation": "sum"
}
```

### Tachometer

```json
{
"type": "gauge",
"title": "Completion Rate",
"cubeCode": "form_uuid",
"kpiField": "numberField_rate",
"aggregation": "avg"
}
```

### Radardiagramm

```json
{
"type": "radar",
"title": "Performance Overview",
"cubeCode": "form_uuid",
"xField": "selectField_category_value",
"yField": [
{ "fieldCode": "numberField_score1", "aggregateType": "AVG" },
{ "fieldCode": "numberField_score2", "aggregateType": "AVG" }
]
}
```

---

## Feldcodes für Berichte

Beim Referenzieren von Formularfeldern in Berichts-Diagrammdefinitionen verwenden die meisten Feldtypen ihre Feld-ID direkt (z.B. `textField_abc123`). Auswahlfelder — wie `SelectField`, `RadioField`, `CheckboxField`, `EmployeeField` und `DepartmentSelectField` — erfordern jedoch das Anhängen des Suffixes `_value` an die Feld-ID.

| Field type | Field ID example | Report field code |
|------------|------------------|-------------------|
| TextField | textField_abc123 | textField_abc123 |
| NumberField | numberField_abc123 | numberField_abc123 |
| DateField | dateField_abc123 | dateField_abc123 |
| SelectField | selectField_abc123 | selectField_abc123_value |
| RadioField | radioField_abc123 | radioField_abc123_value |
| CheckboxField | checkboxField_abc123 | checkboxField_abc123_value |
| EmployeeField | employeeField_abc123 | employeeField_abc123_value |
| DepartmentSelectField | departmentSelectField_abc123 | departmentSelectField_abc123_value |

<Tip>
Verwenden Sie `openyida get-schema`, um das Formularschema abzurufen und die korrekten Feldcodes für Ihre Berichtsdiagramme zu ermitteln.
</Tip>

<Warning>
Die Verwendung einer Feld-ID ohne das Suffix `_value` für Auswahlfelder führt zu leeren oder falschen Daten im Diagramm.
</Warning>

---

## Alternatives Feldformat

Anstatt `xField` und `yField` als Zeichenketten zu verwenden, können Sie ein `fields`-Array verwenden, um mehrere Kennzahlen mit individuellen Aggregationstypen anzugeben:

```json
{
"type": "bar",
"title": "Multi-measure Chart",
"cubeCode": "form_uuid",
"xField": "selectField_category_value",
"yField": [
{ "fieldCode": "numberField_amount", "aggregateType": "SUM" },
{ "fieldCode": "numberField_count", "aggregateType": "COUNT" }
]
}
```

Dieses Format ist besonders nützlich für Kombi-Diagramme und Radardiagramme, die mehrere Kennzahlen in derselben Visualisierung anzeigen müssen.

---

## Filter

Auswahlfelder (SelectField, RadioField, CheckboxField usw.) erzeugen automatisch Filter im Bericht. Wenn ein Diagramm ein Auswahlfeld als `xField` verwendet, zeigt die Berichts-UI ein Filter-Dropdown an, mit dem Benutzer die Diagrammdaten interaktiv filtern können.

Es ist keine zusätzliche Konfiguration erforderlich — Filter werden basierend auf dem Feldtyp im Formularschema automatisch generiert.

---

## Aggregationsfunktionen
Expand All @@ -190,6 +284,7 @@ Das Setzen von `w` oder `h` auf `0` ist gültig und wird berücksichtigt. Bei Au
| **count** | Anzahl der Datensätze |
| **max** | Maximalwert |
| **min** | Minimalwert |
| **count_distinct** | Anzahl eindeutiger Werte |

---

Expand Down Expand Up @@ -248,9 +343,22 @@ openyida create-report APP_XXXXXX "Sales Analysis Report" ./sales-report-charts.

---

## Konfigurationsvalidierung

Bevor Sie einen Bericht erstellen, validieren Sie Ihre Diagrammkonfiguration, um häufige Fehler zu vermeiden:

1. **Feldcodes prüfen** — Führen Sie `openyida get-schema` aus, um Feld-IDs zu überprüfen und sicherzustellen, dass Auswahlfelder das Suffix `_value` enthalten.
2. **Datenquelle überprüfen** — Stellen Sie sicher, dass `dataSource` oder `cubeCode` einer gültigen Formular-UUID in Ihrer Anwendung entspricht.
3. **Aggregationstypen validieren** — Bestätigen Sie, dass die Aggregationsfunktion mit dem Feldtyp kompatibel ist (z.B. `sum` funktioniert nur bei Zahlenfeldern).
4. **Mit einem einzelnen Diagramm testen** — Beginnen Sie mit einem Diagramm, um die Konfiguration zu überprüfen, bevor Sie mehrere hinzufügen.

---

## Best Practices

1. **Wählen Sie den passenden Diagrammtyp** - Liniendiagramme für Trends, Balkendiagramme für Vergleiche, Kreisdiagramme für Anteile
2. **Begrenzen Sie die Diagrammanzahl** - Maximal 6 Diagramme pro Bericht
3. **Verwenden Sie Datentabellen** - Ergänzen Sie Diagramme mit Tabellen zur detaillierten Datenprüfung
4. **Legen Sie angemessene Seitengrößen fest** - Für Datentabellen 10-20 Zeilen pro Seite
5. **Verwenden Sie get-schema zur Felderkennung** - Führen Sie `openyida get-schema` aus, um korrekte Feldcodes vor dem Erstellen von Diagrammdefinitionen abzurufen
6. **Nutzen Sie automatische Filter** - Auswahlfelder erzeugen automatisch Berichtsfilter, verwenden Sie sie als `xField` für interaktive Dashboards
2 changes: 1 addition & 1 deletion de/features/skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ openyida create-form create <appType> "<Formularname>" <FelderJSON> \
# Formular aktualisieren
openyida create-form update <appType> <formUuid> <ÄnderungenJSON>

# Formular-Schema abrufen
# Formular-Schema abrufen (gibt Feld-IDs und Berichts-Feldcodes zurück)
openyida get-schema <appType> <formUuid>

# Formularkonfiguration aktualisieren
Expand Down
Loading