FAQ: Template Content

Q: What is the difference between a variable and a helper in templates?

A: A variable is a placeholder that inserts data from your document (e.g., {{invoice.number}}). A helper is a function that transforms or formats data (e.g., {{date_jalali invoice.date}} converts a date to Jalali format, {{currency total_amount}} formats a number with thousand separators). Variables just display data; helpers apply logic or formatting.

---

Q: My template shows blank spaces where variables should be. Why?

A: The variable either doesn't exist, is misspelled, or has no value in the document. Double-check the variable name against the variables reference. For example, if a customer hasn't entered a phone number, {{customer.phone}} will be empty. Use the {{#if}} helper to hide blank fields: {{#if customer.phone}}<p>Phone: {{customer.phone}}</p>{{/if}}.

---

Q: Can I add conditional logic (if/else) to templates?

A: Yes. Use Handlebars {{#if}}...{{/if}} syntax to show or hide content based on a condition:

{{#if discount_amount}}
  <p>Discount: {{currency discount_amount}}</p>
{{/if}}

This displays the discount paragraph only if a discount amount exists. You can also use {{#unless}} for the opposite: {{#unless is_paid}}<p>This invoice is unpaid.</p>{{/unless}}.

---

Q: How do I add a company logo to every document?

A: Add an <img> tag with the path to your logo:

<img src="https://example.com/logo.png" alt="Company Logo" style="max-width: 150px;" />

Or use a partial (reusable section) to include the logo in multiple templates. See reusable headers and footers.

---

Q: Can I include line items (invoices lines, bill lines) in my template?

A: Yes, use the {{#each}} loop to iterate over line items:

{{#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}}

This repeats the <tr> block for each line item in the document.

---

Q: Do barcodes or QR codes slow down printing?

A: No. Barcodes and QR codes are generated at template render time and are embedded as images in the PDF or print output. They have negligible performance impact. However, ensure your QR code data (e.g., URL) is reasonable in length (~100–2000 characters); extremely long data may slow generation slightly.

---

Q: What currencies does the {{currency}} helper support?

A: The {{currency}} helper automatically formats numbers according to the document's currency setting. If the document is in AFN (Afghan Afghani), amounts display with AFN formatting (e.g., "5,000.00 AFN"). If the document is in USD, it displays in USD format. You do not need to specify the currency in the helper; it uses the document's active currency.

---

Q: Can I translate template text into multiple languages?

A: Yes. Use the translation helper {{t "key"}}:

<h1>{{t "invoice.title"}}</h1>
<p>{{t "invoice.due_date"}}</p>

When the template is printed in English, it shows English text. When printed in Dari, it shows Dari text. Check your product's translation key reference to find the available keys, or contact your administrator for custom translation keys.

---

Q: How do I repeat a header or footer on every page of a long document?

A: Most print systems (HTML-to-PDF converters) support CSS @page rules. Add this to your <style> block:

@page {
  margin-top: 20mm;
  margin-bottom: 20mm;
}
@page :first {
  margin-top: 50mm; /* Extra space on first page for title */
}

Then use <header> and <footer> tags (or positioned <div> elements with position: fixed) to place content that repeats. Test with actual multi-page documents to confirm behavior.

---

Q: Can I use custom fonts in templates?

A: Most templates support web-safe fonts (Arial, Times New Roman, Verdana, etc.). Some systems allow you to embed custom fonts using @font-face in your CSS:

@font-face {
  font-family: 'MyCustomFont';
  src: url('https://example.com/font.woff2') format('woff2');
}
body { font-family: 'MyCustomFont', Arial, sans-serif; }

However, embedded fonts may not work in all printers. Stick to standard fonts unless you know your print system supports custom fonts. Contact your administrator if unsure.