1基本的な使い方
Store_nameキーの値（”Star Cafe”）を印刷するために、置き換え指定子を含んだ文字列を記述します。
2マークアップタグとの組み合わせ
order_numberキーの値("#2-007")およびtimeキーの値("10/16 11:13PM")を2列のレイアウトで印字するため、置き換え指定子を含んだ文字列を[column]タグのパラメーターに記述します。
この例のleftパラメーターのように、通常のテキストと置き換え指定子を混在させることができます。
また、vl (variable-left) オプションを指定することにより、leftパラメーターに置き換えられる文字列の文字数が増加した場合でも自動で文字数を削減し、レイアウトの崩れを防ぐことができます。
オプションの詳細はタグリファレンスをご参照ください。
[column: vl; left Order ${order_number}; right ${time}]
3配列要素のフィールドデータ
配列要素のフィールドデータを印刷するため、繰り返しを行うテンプレートの範囲を[templateArray]タグで指定します。
繰り返しの開始位置に[templateArray: start]タグを、終了位置に[templateArray: end]タグを記述します。
[templateArray]タグで囲まれた範囲に記述された、配列要素(item.listキーの値)のフィールドデータを指定した置き換え指定子を含む文字列は、配列の要素数だけ繰り返して印字されます。
[templateArray: start]
[column: vl; left ${item_list.quantity%-2d} ${item_list.name}; right ${item_list.unit_price%6.2lf}]
[templateArray: end]\
4数値フォーマット指定
数値型のsubtotalキーの値(8.24)をフォーマット指定で印刷するため、数値フォーマットを指定した文字列を記述します。
[column: vl; left Subtotal; right ${subtotal%6.2lf}]
5マークアップタグとの組み合わせ
transaction_idキーの値（”0123456789”）のバーコードを印刷するため、置き換え指定子を含んだ文字列を[barcode]タグのdataパラメータに記述します。
[barcode: type code39; data ${transaction_id}; height 15mm; module 0; hri]\
このセクションで作成したテンプレートとフィールドデータをプリンターコマンドに変換するには以下のライブラリまたはツールを利用します。
サンプルコード
フィールドデータ：JSON
{
"store_name" : "Star Cafe",
"order_number" : "#2-007",
"time" : "10/16 11:13PM",
"sales_type" : "Walk-in",
"server" : "Jane",
"transaction_id" : "0123456789",
"item_list" : [
{
"name" : "Vanilla Latte",
"unit_price" : 4.99,
"quantity" : 1
},
{
"name" : "Chocolate Chip Cookie",
"unit_price" : 3.25,
"quantity" : 1
}
],
"subtotal" : 8.24,
"tax" : 0.73,
"total" : 8.97,
"credit_card_number" : "VISA 0123",
"approval_code" : "OK2443",
"amount" : 8.97,
"address" : "123 Star Road, City,\nState 12345",
"tel" : "123-456-7890",
"mail" : "info@star-m.jp",
"url" : "star-m.jp"
}
テンプレート：Starドキュメントマークアップ
[align: center]\
[font: a]\
[image: url https://star-emea.com/wp-content/uploads/2015/01/logo.jpg; width 60%; min-width 48mm]\
[magnify: width 2; height 2]
${store_name}\
[plain]\
[align: left]\
[column: vl; left Order ${order_number}; right ${time}]
[column: vl; left Sale for ${sales_type}; right Served by ${server}]\
Transaction #${transaction_id}
[fixedWidth: text ------------------------------------------------]\
[templateArray: start]
[column: vl; left ${item_list.quantity%-2d} ${item_list.name}; right ${item_list.unit_price%6.2lf}]
[templateArray: end]\
[fixedWidth: text ------------------------------------------------]\
[column: vl; left Subtotal; right ${subtotal%6.2lf}]
[column: vl; left Tax; right ${tax%6.2lf}]
[bold: on]\
[column: vl; left Total; right ${total%6.2lf}]\
[bold: off]\
[fixedWidth: text ------------------------------------------------]\
[column: vl; left ${credit_card_number}; right ${total%6.2lf}]
[column: vl; left Approval Code; right ${approval_code}]\
[fixedWidth: text ------------------------------------------------]\
[column: vl; left Amount; right ${amount%6.2lf}]
[column: vl; left Total; right ${total%6.2lf}]\
[fixedWidth: text ------------------------------------------------]\
Signature\
[align: center]\
------------------------
${address}
${tel}
${mail}
${url}\
[fixedWidth: text ------------------------------------------------]\
Powered by Star Micronics\
[barcode: type code39; data ${transaction_id}; height 15mm; module 0; hri]\
[cut: feed; partial]
テンプレート
テンプレートとは、固定の印刷データと置き換え指定子を組み合わせて定義する、Starドキュメントマークアップで作成する印刷レイアウトです。
置き換え指定子を利用することで、印刷レイアウトであるテンプレート内にフィールド（置き換え箇所）を定義します。
置き換え指定子にはJSON形式のフィールドデータから同じキーを持つ値を代入できます。
プレーンテキストに置き換え指定子を記述してください。通常のテキストと混在させることができます。
Date:${date} Time:${time}
置き換え指定子のフォーマット
"${key-string}" のように、キー文字列を ${ と } で囲んだものを 置き換え指定子 として扱います。
フィールドデータ内に ’key-string' に一致するキーがあれば、そのキーの値で "${key-string}" 部分を置き換えます。
一致するキーがなければ、"${key-string}" 部分は無視して印字しません。
キー指定子
フィールドデータ内のキーを指定し、置き換えたいフィールドデータを特定します。
キーに使用可能な文字はASCII文字のみです。
ネストした要素のケース
ネストした要素を指定する場合はキーをピリオド(.)で接続します。
ネストした要素を指定する例
フィールドデータ
{
"store" : {
"name" : "Star Store",
"address" : "123 Star Road, City, State 12345"
}
}
配列要素のケース
キー指定子で配列要素を指すキーを指定することで、ひとつのフィールドに対して配列の要素数分の置き換えを行うことができます。
その場合、同時に配列の要素数分だけ繰り返すテンプレートの範囲を指定します。
配列フィールドデータが存在する場合の繰り返し範囲を指定する[templateArray]タグを利用することで、繰り返しの範囲が指定でき、この範囲が配列の要素数文だけ繰り返されます。
下記の例では、キー指定子で配列要素の子要素のキー（文字列型、数値型）を指定し、[templateArray]タグで配列要素の繰り返し指定を行っています。
その結果、繰り返し指定を行った[templateArray]タグで囲まれた箇所の印刷が、フィールドデータの配列要素数４回だけ実行されます。
テンプレート
[templateArray: start]
[column: left ${item_list.name}; right ${item_list.unit_price%6.2lf}
[underline: on]\
[column: left ; right x${item_list.quantity}]
[underline: off]\
[templateArray: end]
[cut: feed; partial]
フィールドデータ
{
"item_list" : [
{
"name" : "BLT",
"unit_price" : 13.0,
"quantity" : 1
},
{
"name" : "Chicken Noodle",
"unit_price" : 7.5,
"quantity" : 1
},
{
"name" : "Caesar salad",
"unit_price" : 10.0,
"quantity" : 2
},
{
"name" : "Coffee",
"unit_price" : 3.5,
"quantity" : 2
}
]
}
印字結果
数値フォーマット指定子
フィールドデータの値が数値型の場合、数値フォーマット指定子により表示形式を指定することができます。数値フォーマット指定子はC言語のprintf関数のフォーマット指定子のサブセットです。
数値フォーマット指定子は省略することができます。省略した場合は変換は行わず、数値がそのまま文字列化されます。
| オプション指定 | 意味 |
|---|
| ♯ | 代わりの形に変換（16進数の場合、先頭に0xを付ける） |
| 0 | ゼロ埋めを行う |
| SP(空白文字) | 符号付き変換において、正の値のとき左側に1文字空白を付加する |
| + | 正の値のとき+記号を付加する |
| − | 左詰め |
| 表示桁数 | [ 全体桁数 ] . [ 小数点以下の桁数 ]
|
| 出力フォーマット指定子 | 意味 |
|---|
| d | 符号あり整数の10進出力 |
| u | 符号なし整数の10進出力 |
| f | 実数の出力 |
| x | 整数の16進 小文字出力 |
| X | 整数の16進 大文字出力 |
| ld | 符号あり倍精度整数の10進出力 |
| lu | 符号なし倍精度整数の10進出力 |
| lf | 倍精度実数の出力 |
| lx | 倍精度整数の16進 小文字出力 |
| lX | 倍精度整数の16進 大文字出力 |
エスケープ文字
置き換え指定子の開始の意味を持つ ${ を印刷したい場合、;を末尾に付けてエスケープ（${;）してください。
テンプレート印刷機能のために特別な意味を持つ下記の文字をフィールドデータのキーに含めたい場合、
キー指定子の中で使用するときにその文字の前に\\を付けてエスケープしてください。
テンプレート印刷機能対応タグ
置き換え指定子によりフィールドを定義できるタグは下記のとおりです。
| タグ | パラメーター |
|---|
| プレーンテキスト | |
[barcode] | data |
[column] | left, right, short |
[fixedWidth] | text |
