थर्मल प्रिंटर टेम्पलेट

थर्मल टेम्पलेट XML फ़ॉर्मैट का उपयोग करते हैं, जिससे एक ही टेम्पलेट से स्क्रीन पूर्वावलोकन और ESC/POS प्रिंटर कमांड दोनों बनते हैं। डेटा बाइंडिंग के लिए ये HTML टेम्पलेट जैसे ही {{variable}} प्लेसहोल्डर उपयोग करते हैं।

यदि आपका रसीद प्रिंटर प्रिंटर सेटअप के माध्यम से जुड़ा है, तो यह इंजन चुनें।

XML तत्व

रूट तत्व

हर थर्मल टेम्पलेट की शुरुआत एक <receipt> रूट से होती है:

<receipt paper-width="48">
  <!-- 48 characters = 80mm paper -->
  <!-- 32 characters = 58mm paper -->
</receipt>

पाठ और फ़ॉर्मैटिंग

<text>Plain text</text>
<bold>Bold text</bold>
<underline>Underlined text</underline>
<invert>Inverted (white on black)</invert>

संरेखण

<align mode="left">Left aligned</align>
<align mode="center">Centered</align>
<align mode="right">Right aligned</align>

पाठ का आकार

पाठ की चौड़ाई और ऊँचाई को स्वतंत्र रूप से स्केल करें:

<size width="2" height="2">Double-size text</size>
<size width="2" height="1">Wide text</size>
<size width="1" height="2">Tall text</size>

सारणीबद्ध लेआउट

Logo embed करने के लिए <row> और <col> संरेखित कॉलम के लिए:

<row>
  <col width="24">Item name</col>
  <col width="8" align="right">Qty</col>
  <col width="16" align="right">Price</col>
</row>

कॉलम की चौड़ाई अक्षरों में मापी जाती है। शेष जगह लेने वाले फ़्लेक्स कॉलम के लिए width="*" का उपयोग करें — इससे टेम्पलेट बिना बदलाव के अलग-अलग कागज़ चौड़ाइयों पर काम करते हैं:

<row>
  <col width="*">{{name}}</col>
  <col width="12" align="right">{{line_total_display}}</col>
</row>

विभाजक और रिक्ति

<line />                       <!-- Default single rule -->
<line style="double" />        <!-- Printer-native double rule -->
<line style="dashed" />        <!-- Character dashes across the width -->
<line style="dotted" />        <!-- Character dots across the width -->
<feed lines="2" />             <!-- Blank lines -->

<line/> (या style="single") और style="double" प्रिंटर की अपनी विभाजक रेखा प्रिंट करते हैं। dashed और dotted सक्रिय कॉलम की पूरी चौड़ाई में अक्षर-आधारित विभाजक प्रिंट करते हैं — जब आप ऐसा स्पष्ट विभाजक चाहते हों जो थर्मल पूर्वावलोकन के स्क्रीनशॉट में भी दिखे, तो ये उपयोगी हैं।

प्रिंटर कमांड

<cut />              <!-- Full paper cut -->
<cut mode="partial" /> <!-- Partial cut (leaves a tab) -->
<drawer />           <!-- Open cash drawer -->

बारकोड और QR कोड

<barcode type="code128" height="40">{{order.number}}</barcode>
<barcode type="qrcode" scale="3">{{fiscal.qr_payload}}</barcode>

उदाहरण: सरल 80mm रसीद

<receipt paper-width="48">
  <align mode="center">
    <size width="2" height="2">{{store.name}}</size>
  </align>
  <feed lines="1" />
  <align mode="center">
    <text>{{store.address_1}}</text>
    <text>{{store.city}} {{store.state}} {{store.postcode}}</text>
    {{#store.phone}}<text>{{store.phone}}</text>{{/store.phone}}
  </align>
  <line />

  <text>Order: #{{order.number}}</text>
  <text>Date: {{order.created.datetime}}</text>
  {{#cashier.name}}<text>Cashier: {{cashier.name}}</text>{{/cashier.name}}
  <line />

  <!-- Column headers -->
  <row>
    <col width="*"><bold>Item</bold></col>
    <col width="4" align="right"><bold>Qty</bold></col>
    <col width="12" align="right"><bold>Total</bold></col>
  </row>
  <line />

  <!-- Line items -->
  {{#lines}}
  <row>
    <col width="*">{{name}}</col>
    <col width="4" align="right">{{qty}}</col>
    <col width="12" align="right">{{line_total_display}}</col>
  </row>
  {{/lines}}

  <line />

  <!-- Totals -->
  <row>
    <col width="*">Subtotal</col>
    <col width="16" align="right">{{totals.subtotal_display}}</col>
  </row>
  {{#totals.tax_total}}
  <row>
    <col width="*">Tax</col>
    <col width="16" align="right">{{totals.tax_total_display}}</col>
  </row>
  {{/totals.tax_total}}
  <row>
    <col width="*"><bold>TOTAL</bold></col>
    <col width="16" align="right"><bold>{{totals.total_display}}</bold></col>
  </row>

  <line />

  {{#payments}}
  <row>
    <col width="*">{{method_title}}</col>
    <col width="16" align="right">{{amount_display}}</col>
  </row>
  {{#tendered}}
  <row>
    <col width="*">Tendered</col>
    <col width="16" align="right">{{tendered_display}}</col>
  </row>
  <row>
    <col width="*">Change</col>
    <col width="16" align="right">{{change_display}}</col>
  </row>
  {{/tendered}}
  {{/payments}}

  <feed lines="2" />
  <align mode="center">
    <text>Thank you for your purchase!</text>
  </align>
  <feed lines="3" />
  <cut />
</receipt>

तारांकन-चौड़ाई वाले कॉलम

width="*" सुविधा टेम्पलेट को कागज़ की चौड़ाई से स्वतंत्र बनाती है। किसी खास कागज़ आकार के लिए कॉलम की चौड़ाइयाँ हार्डकोड करने के बजाय, जिस कॉलम को फैलना चाहिए उसके लिए * का उपयोग करें:

<!-- Works on 58mm (32 char) AND 80mm (48 char) printers -->
<row>
  <col width="*">{{name}}</col>
  <col width="10" align="right">{{line_total_display}}</col>
</row>

80mm प्रिंटर (48 अक्षर) पर आइटम के नाम को 38 अक्षर मिलते हैं। 58mm प्रिंटर (32 अक्षर) पर उसे 22 अक्षर मिलते हैं। दोनों में निश्चित कॉलम का आकार समान रहता है।

पुराना StarPRNT निश्चित-लेआउट अडैप्टर हटाया गया

पुराना StarPRNT निश्चित-लेआउट आउटपुट अडैप्टर v1.10 में हटा दिया गया है। यदि कोई टेम्पलेट इस पर निर्भर था, तो उसे मौजूदा थर्मल टेम्पलेट (इस पृष्ठ का XML इंजन) पर स्विच करें, जो साझा थर्मल लेआउट के माध्यम से Star आउटपुट बनाता है। लेआउट को इसके साथ फिर से बनाएँ <row>/<col> और width="*" न कि निश्चित अडैप्टर के साथ।

टेम्पलेट पूर्वावलोकन

टेम्पलेट संपादक बदलाव करते समय लाइव थर्मल पूर्वावलोकन दिखाता है। पूर्वावलोकन आपके XML को शैलीयुक्त मोनोस्पेस HTML के रूप में रेंडर करके दिखाता है कि कागज़ पर रसीद कैसी दिखेगी। बदलाव थोड़ी देरी के बाद अपडेट होते हैं (300ms पर डिबाउंस)।

यही टेम्पलेट पूर्वावलोकन और ESC/POS प्रिंटर आउटपुट दोनों बनाता है — अलग "print" टेम्पलेट की आवश्यकता नहीं है। बारकोड और QR कोड पूर्वावलोकन में इनलाइन SVG के रूप में और प्रिंटर पर मूल ESC/POS कमांड (या रास्टर छवियों) के रूप में रेंडर होते हैं।

लेखन के सुझाव और आम गलतियाँ

थर्मल प्रिंटिंग में कुछ ऐसी पेचीदगियाँ हैं जो HTML में नहीं होतीं। लेखक अक्सर इन्हीं से टकराते हैं।

लाइन ब्रेक के लिए स्टाइल किए गए शीर्षकों को <text> में लपेटें

स्टाइल किए गए कंटेनर — <bold>, <size>, <underline>, <align> — अपने-आप लाइन ब्रेक नहीं देते। केवल <text> और ब्लॉक तत्व (<line/>, <row>, <feed>) ऐसा करते हैं।

<!-- ❌ Bug: the heading runs together with whatever follows -->
<bold>{{i18n.bill_to}}</bold>
{{customer.name}}

<!-- ✅ Fix: wrap the inner content in <text> -->
<bold><text>{{i18n.bill_to}}</text></bold>
<text>{{customer.name}}</text>

शामिल 80mm गैलरी टेम्पलेट हर शीर्षक के लिए यही पैटर्न अपनाते हैं।

संकीर्ण पंक्तियों में <size width="2"> से बचें

दोगुनी चौड़ाई वाला पाठ प्रभावी अक्षर-गणना को दोगुना कर देता है। 80mm प्रिंटर पर फिट होने वाला शीर्षक सामान्य 42-कॉलम 80mm प्रिंटर पर सीमा से बाहर जा सकता है, और 58mm कागज़ पर केवल 16 अक्षरों की जगह छोड़ता है।

प्रमुख मानों (बड़े योग, रसोई ऑर्डर नंबर) के लिए उन्हें कई कॉलम वाले लेआउट में लपेटने के बजाय अलग से स्केल की गई पंक्ति में दिखाएँ <row>:

<!-- For store names, prefer normal-width, double-height -->
<bold><size height="2"><text>{{store.name}}</text></size></bold>

<!-- For a bold total, put it on its own line above the row -->
<align mode="right">
  <bold><size height="2"><text>{{totals.total_display}}</text></size></bold>
</align>

कागज़ की चौड़ाई से स्वतंत्र लेआउट के लिए width="*" का उपयोग करें

width="*" (तारांकन) कॉलम निश्चित-चौड़ाई वाले कॉलमों के बाद बची जगह लेता है। वही टेम्पलेट बिना बदलाव के 32-कॉलम (58mm), 42-कॉलम (मानक 80mm), और 48-कॉलम (चौड़ा 80mm) प्रिंटरों पर सही ढंग से रेंडर होता है:

<!-- Works on 58mm AND 80mm without changes -->
<row>
  <col width="*">{{name}}</col>
  <col width="10" align="right">{{line_total_display}}</col>
</row>

यदि आप हार्डकोड की गई संख्यात्मक चौड़ाइयाँ इस्तेमाल करते हैं, तो उन्हें 42 के अनुसार रखें, 48 के अनुसार नहीं। जिन पंक्तियों का योग 48 होता है, वे आम 42-कॉलम 80mm प्रिंटरों पर अगली पंक्ति में टूटेंगी।

<align> ब्लॉक के भीतर केंद्रित स्टाइल वाले शीर्षक

इसके भीतर <align mode="center"> (या right), सीधे रखा गया स्टाइल वाला शीर्षक — <bold>, <size>, <underline>, <invert> सीधे इसके भीतर रखा गया <align> — जिसके बाद दूसरी पंक्ति हो, तो वह अपने-आप अपनी अलग पंक्ति में बंद हो जाता है। केंद्रित पते के ऊपर केंद्रित स्केल किया गया स्टोर नाम साफ़ प्रिंट होता है, भले ही स्पष्ट <text> रैप बनाए रखें।

संरेखण ब्लॉक के बाहर <text> रैप बनाए रखें।

ESC/POS विराम-चिह्न सामान्यीकरण

जब प्रिंटर की भाषा ESC/POS होती है, तो एनकोडर लिखने से पहले टाइपोग्राफ़िक विराम-चिह्नों को सुरक्षित ASCII में बदलता है:

• एन डैश, एम डैश, फ़िगर डैश, यूनिकोड माइनस → -
• घुमावदार उद्धरण चिह्न → सीधे उद्धरण चिह्न
• नॉन-ब्रेकिंग स्पेस → सामान्य स्पेस

इसलिए Mon–Sat 9:00–18:00 और "open" उन प्रिंटरों पर भी सही प्रिंट होते हैं जिनमें यूनिकोड फ़ॉन्ट नहीं है। Star प्रिंटर (star-line / star-prnt) मूल टाइपोग्राफ़ी को ज्यों का त्यों रखते हैं, इसलिए ऐसे अक्षरों का उपयोग करें जिन्हें प्रिंटर का फ़ॉन्ट समर्थन करता हो।

गैर-लैटिन और दाएँ-से-बाएँ लिपियाँ

थर्मल प्रिंटर पाठ को अंतर्निहित फ़ॉन्ट और कोड पेज से प्रिंट करते हैं, इसलिए अरबी, हिब्रू, फ़ारसी, उर्दू और अन्य गैर-लैटिन लिपियाँ तभी सही प्रिंट होती हैं जब प्रिंटर पर मेल खाता कोड पेज सेट हो (उदाहरण के लिए अरबी के लिए CP864 / Windows-1256) — अन्यथा खाली या बिगड़े हुए अक्षर दिखेंगे।

इन लिपियों के लिए भरोसेमंद तरीका पूरी रसीद का रास्टर है, जो पूरी रसीद को छवि के रूप में रेंडर करता है ताकि प्रिंटर के अंतर्निहित फ़ॉन्ट की परवाह किए बिना वह बिल्कुल डिज़ाइन के अनुसार प्रिंट हो। रास्टर मोड चालू करने के लिए प्रिंटर सेटअप देखें।

थर्मल हार्डवेयर के लिए थर्मल टेम्पलेट आवश्यक है

Thermal printer full-page HTML template print नहीं कर सकता — job को ESC/POS या Star commands में render होना पड़ता है, जिसे HTML व्यक्त नहीं कर सकता। Thermal hardware के लिए thermal template उपयोग करें; full-page A4/Letter HTML के लिए system/PDF printer या PrintNode के माध्यम से print करें।

Logos और images

Logo embed करने के लिए <image> उपयोग करें:

<align mode="center">
  <image src="data:image/png;base64,..." />
</align>

WCPOS client पर images को rasterise करता है — decode करना, transparency को white पर flatten करना, printer dot budget के अनुसार resize करना, monochrome में बदलना (logos के लिए Atkinson dithering, barcodes के लिए threshold), और फिर ESC/POS या Star image commands भेजना।

• Dot budgets: 58mm के लिए 384 dots wide, 80mm के लिए 576 dots wide।
• Accepted sources: data:image/png और data:image/jpeg data URLs, absolute http(s) URLs, और same-origin root-relative paths। Protocol-relative //, backslashes, और percent-encoded .. traversal reject किए जाते हैं।
• Recommended format: transparent या white background वाला high-contrast PNG। JPEG काम करता है, लेकिन compression artefacts noise की तरह print हो सकते हैं।
• SVG अभी raw thermal output के लिए supported नहीं है।

Tips

• Gallery template से शुरू करें — gallery के thermal templates ऊपर के सभी patterns उपयोग करते हैं और real printers पर validate किए गए हैं।
• यदि आपके stores अलग printers उपयोग करते हैं तो दोनों paper sizes test करें, या width="*" columns पर टिके रहें।
• Currency के लिए _display fields उपयोग करें — वे पहले से locale-aware हैं।
• सरल रखें — thermal में HTML की तुलना में कम formatting tools हैं। <row> + <col width="*"> पर भरोसा करें और printer को काम करने दें।