> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# سياق تعبير قالب المستند

> استخدم تعبيرات KayanOS في قوالب المستندات مع جذور السجل الصحيحة وعمليات البحث المضبوطة والطوابع الزمنية ووضع المتصل/المدير.

## ابدأ بسياق السجل

عندما ينشئ KayanOS قالب مستند مُداراً لسجل كيان، فإنه يزوّد:

![إعدادات قالب مستند مُدار في KayanOS مع تعبير اسم ملف يعتمد السجل ووضع صلاحيات المتصل.](https://kayanos.app/docs-images/ar/reference/expressions-document-template-context.png)

| الجذر               | المعنى                                                  |
| ------------------- | ------------------------------------------------------- |
| `$record`           | سجل الكيان الحالي بشكل مسطح.                            |
| `$inverseRelations` | سجلات العلاقات العكسية المهيأة مجمعة حسب الكيان والحقل. |
| `$organization`     | كائن المنظمة وفيه `id`.                                 |
| `$member`           | كائن العضو المتصل وفيه `id`.                            |
| `$now`              | طابع ISO زمني ملتقط لهذا التنفيذ.                       |

```jexl theme={null}
`Acknowledgement {{ $record.request_id }} — {{ $record.status || "received" }}`
```

استخدم `$record` لا جذر قواعد الكيان `$`. تتحول قيمة `null` أو`undefined` داخل الإدراج إلى فراغ، لذلك أضف بديلاً مراجعاً في المستندات العامة أو الرسمية.

## الوقت الثابت والتنسيق

استخدم `$now` عندما يجب أن يعرض كل جزء من المستند الطابع نفسه. تتاح `now()` كدالة أيضاً، لكنها تقيم من قبل العارض وقد تختلف قليلاً بين التعبيرات.

```jexl theme={null}
dateFormat($now, "YYYY-MM-DD")
```

تشترك القوالب مع كتالوج الدوال العامة، بما فيه دوال التاريخ والنص والقوائم والمقارنة والمشاريع والتخطيط. لكنها لا ترث البدائل القديمة الخاصة بالمنشئ ولا دوال النموذج فقط. راجع [بنية لغة التعبيرات](/ar/reference/expressions/language-syntax) وملاحظات التوافر في صفحات الدوال.

## البحث المضبوط عن السجلات

تتلقى دالة `getRecords` الخاصة بالقالب كائناً واحداً:

```jexl theme={null}
getRecords({
  entityKey: "service_requests",
  filters: [["status", "eq", "approved"]],
  limit: 20,
  sorting: [{ field: "created", direction: "desc" }]
})
```

الخصائص المدعومة هي `entityKey` و`q` الاختيارية و`filters` و`limit` و`sorting` و`search`. تكون قيمة `sorting` قائمة كائنات، يحوي كل منها `field` و`direction: "asc" | "desc"`؛ وليست كائناً مفهرساً باسم الحقل. يحصر كل استدعاء `limit` بين 1 و500. اجعل البحث ضيقاً، واختر البيانات اللازمة للمستند فقط، واجعل غياب النتيجة مفهوماً.

```jexl theme={null}
getRecords({
  entityKey: "service_requests",
  filters: [["applicant_id", "eq", $record.applicant_id]],
  limit: 5
})
```

### وضعي المتصل والمدير

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

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

قبل نشر قالب يستخدم `getRecords`:

1. اختر وضع المتصل ما لم يوافق مالك الخدمة على حاجة إدارية أضيق.
2. في وضع المدير اضبط قائمة **غير فارغة** من الكيانات المسموحة بأشد شكل ممكن؛ لا تتركها فارغة متوقعاً أنها قيد.
3. اختبر بعضو ينبغي أن يرى أقل كمية بيانات، ثم اختبر كياناً خارج القائمة غير الفارغة وتأكد من رفض البحث.
4. افحص المستند الناتج بحثاً عن بيانات شخصية أو مالية أو تشغيلية غير مقصودة.
5. لا تجعل البحث الفارغ ينتج عبارة مضللة.

يملك العارض حداً قدره 500 صف لكل استدعاء بحث و10,000 تكرار حلقي و20 مستوى تداخل وخمسة مستويات قالب فرعي ومهلة 15 ثانية. لا تفترض حداً إجمالياً آخر لصفوف البحث ليس جزءاً من العقد العام.

## البيانات المرتبطة والحلقات

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

```jexl theme={null}
$inverseRelations.inspections.request_id
```

استخدم العلاقة بعد تأكيد تجميع الكيان/الحقل الذي يكشفه السياق. ليست العلاقة العكسية غير المهيأة دليلاً موثوقاً على عدم وجود سجلات مرتبطة.

## تعبيرات اسم الملف

تستخدم تعبيرات اسم الملف سياق قالب المستند نفسه. اجعل الاسم ثابتاً ومقروءاً وخالياً من القيم الحساسة التي لا يلزم أن تظهر في اسم التنزيل.

```jexl theme={null}
$record.request_id + "-acknowledgement"
```

يضيف نوع المخرج امتداد المستند عند الحاجة. لا تضع مساراً أو رمز وصول أو معرفاً وطنياً أو ملاحظة خاصة حرة في اسم الملف.

## اختبر القالب كسجل لا كفقرة

| الاختبار                 | النتيجة المتوقعة                                                      |
| ------------------------ | --------------------------------------------------------------------- |
| سجل مكتمل                | تحل كل الوسوم المقصودة بالتنسيق الصحيح.                               |
| قيمة اختيارية مفقودة     | يظهر بديل مراجع أو فراغ مقصود.                                        |
| علاقة/قائمة فارغة        | يبقى المستند صادقاً ومقروءاً.                                         |
| وضع المتصل               | لا يكشف القالب بيانات تتجاوز غرض خدمة العضو.                          |
| وضع المدير — قائمة مقيدة | يُرفض بحث كيان خارج القائمة غير الفارغة المعتمدة.                     |
| وضع المدير — قائمة فارغة | يدرك المراجع أن القائمة الفارغة/المحذوفة وصول إداري واسع وليست قيداً. |
| بيانات كبيرة صالحة       | تحترم حدود الحلقة والتداخل وحجم المخرج والمهلة.                       |

## أدلة ذات صلة

* [قوالب المستندات](/ar/build/document-templates)
* [وسوم قوالب المستندات والتصيير](/ar/build/document-template-tags-and-rendering)
* [دالة بحث قالب المستند](/ar/reference/expressions/helpers/document-templates)
* [سياقات وتوافر التعبيرات](/ar/reference/expressions/contexts)