متغیرها و توابع قالب: اسعار، تاریخ هجری شمسی و ترجمه‌ها

این مرجع متغیرهای متداول‌تر و توابع کمکی موجود در قالب‌های Usystems را فهرست می‌کند. از این‌ها در کد قالب Handlebars (مثلاً {{variable_name}}) برای درج داده‌های سند پویا استفاده کنید.

متغیرهای داده سند (نمونه‌ها بر اساس نوع سند):

کمک‌دهنده قالب‌بندی تاریخ:

برای نمایش تاریخ در تقویم هجری شمسی (تقویم خورشیدی) که در افغانستان و ایران استفاده می‌شود از {{date_jalali variable_name}} استفاده کنید:

<p>تاریخ: {{date_jalali invoice.date}}</p>
<!-- خروجی: تاریخ: 1405-04-12 -->

قالب‌بندی اسعار و اعداد:

برای قالب‌بندی عدد با جداکننده‌های هزارگانی و اعشار طبق اسعار سند از {{currency variable_name}} استفاده کنید:

<p>کل: {{currency total_amount}} {{currency_code}}</p>
<!-- خروجی: کل: 5,000.00 AFN -->

کمک‌دهنده ترجمه (پشتیبانی چندزبانی):

برای درج متن ترجمه‌شده از فایل‌های زبان سازمان خود از {{t "key.path"}} استفاده کنید. این برای اضافه‌کردن برچسب‌ها، عنوان‌ها یا متن استاندارد به زبان ترجیح‌شده کاربر مفید است:

<h1>{{t "invoice.title"}}</h1>
<p>{{t "invoice.due_date_label"}}</p>
<!-- بسته به زبان فعال (انگلیسی، دری یا پشتو) نمایش داده می‌شود -->

کلیدهای ترجمه معمول (نمونه‌ها؛ سیستم شما ممکن است کلیدهای اضافی داشته باشد):

• invoice.title → "فاکتور"
• invoice.due_date_label → "تاریخ سر‌رسید"
• report.page_of → "صفحه X از Y"
• common.total → "کل"
• common.quantity → "مقدار"

منطق شرطی (Handlebars if/else):

برای نشان دادن یا پنهان کردن محتوا بر اساس مقدار فیلد از {{#if condition}}...{{/if}} استفاده کنید:

{{#if discount_amount}}
  <p>تخفیف: {{currency discount_amount}}</p>
{{/if}}
<!-- تخفیف را فقط در صورتی نشان می‌دهد که مقدار تخفیف وجود داشته باشد -->

حلقه‌ها (تکرار بر اقلام خطی):

برای تکرار بلوک HTML برای هر مورد در فهرست از {{#each line_items}}...{{/each}} استفاده کنید:

<table>
  <tr>
    <th>توضیح</th>
    <th>مقدار</th>
    <th>قیمت واحد</th>
    <th>کل</th>
  </tr>
  {{#each line_items}}
  <tr>
    <td>{{item.description}}</td>
    <td>{{item.quantity}}</td>
    <td>{{currency item.unit_price}}</td>
    <td>{{currency item.total}}</td>
  </tr>
  {{/each}}
</table>

نکات:

• متغیرهای نه تمام برای تمام انواع سند در دسترس هستند. برای مثال، {{customer.name}} برای فاکتورها موجود است اما برای اسناد روزنامچه داخلی نیست. اگر متغیر خالی یا گمشده است، به عنوان متن خالی نمایش داده می‌شود.
• همیشه قالب خود را با داده‌های واقعی تست کنید تا متغیرها به‌درستی نمایش داده شوند. از تابع پیش‌نمایش استفاده کنید یا سند آزمایشی چاپ کنید.
• برای متغیرهایی که ممکن است خالی باشند (مثل تخفیف یا یادداشت)، از کمک‌دهنده {{#if}} استفاده کنید تا از چاپ ردیف‌های خالی جلوگیری کنید.