StarXpand SDK Manual

Step.1 印刷データの生成：テンプレート印刷機能

テンプレート印刷機能は、印刷レイアウトを定義するテンプレートと、テンプレート中の指定箇所を任意の文字列に置き換えるフィールドデータの２つを組み合わせて印刷データを生成する機能です。
印刷に使用するデータをテンプレートとフィールドデータに分離することで、印刷ごとに可変なデータを簡単に扱える、印刷レイアウトが再利用できるといった利点があります。

テンプレート印刷機能の便利な４大機能

1. フィールドデータをJSONフォーマットで指定可能
トランザクションごとに可変なデータをWeb APIなど外部から取得し印刷する際のデータフォーマット変換の手間を減らします。

2. 印刷レイアウトの再利用が可能
トランザクションごとに変わらない部分をテンプレートにすることで、一度作成した印刷レイアウトを容易に再利用できます。

3. 配列のフィールドデータに対応
テンプレート側に配列要素のフィールドデータを指すフィールドを一回指定しておけば、自動的に配列の全要素を印刷できます。

４. 柔軟な数値フォーマット仕様
整数・小数の切り替え、桁数指定での数値の印刷など細かな制御をC言語ライクなフォーマット指定により行えます。

テンプレート機能を利用した印刷データ作成処理の実装

以下の画像はテンプレート印刷機能を利用した印刷サンプルです。

テンプレート印刷機能を利用してこの印刷を行うには、以下の手順(*)に従ってテンプレートを作成し、フィールドデータを用意してください。
* テンプレート作成処理の説明に必要ないAPI呼び出しの説明は省略しています。

ページ下部にテンプレート・フィールドデータのサンプルコードがあります。

1テンプレートを作成するためのStarXpandCommandBuilderインスタンスを生成します。
addDocumentメソッドを呼び出して DocumentBuilderを追加し、addPrinterメソッドを呼び出してPrinterBuilderを追加します。 PrinterBuilderの各メソッドを呼び出して、テンプレートを作成していきます。

var builder = new StarXpandCommand.StarXpandCommandBuilder();
builder.addDocument(new StarXpandCommand.DocumentBuilder()
.addPrinter(new StarXpandCommand.PrinterBuilder()

2store_nameキーの値（" Star Cafe "）を印刷するため、置き換え指定子を含んだ文字列を渡してactionPrintTextメソッドを呼び出します。

.actionPrintText("${store_name}\n")

3order_numberキーの値（”#2-007”）を印刷するため、置き換え指定子を含んだ文字列を渡してactionPrintTextメソッドを呼び出します。
この場合のように通常のテキストと置き換え指定子を混在させることができます。
また、actionPrintTextメソッドにより印字される文字数を指定するため、TextParameterクラスのsetWidthメソッドを呼び出します。これにより、文字列の印字位置と幅を固定し、文字数の増減によるレイアウトの崩れを防ぐことができます。

.actionPrintText(
    "Order ${order_number}",
    new StarXpandCommand.Printer.TextParameter()
        .setWidth(
            16
        )
)

Memo
フィールドデータの文字数が変わることによってレイアウトが崩れないよう、actionPrintTextメソッドのparameter引数により、あらかじめ印刷する文字数を指定する機能があります。
この機能の詳細は、TextParameterクラスのsetWidthメソッドと、 TextWidthParameterクラスのAPIリファレンスを参照してください。

4配列要素のフィールドデータを印刷するため、繰り返すテンプレートの範囲を指定します。
まずTemplateExtensionParameterクラスのsetEnableArrayFieldDataメソッドを引数にtrueを渡して呼び出します。次にPrinterParameterクラスのsetTemplateExtensionメソッドに先ほどのTemplateExtensionParameterインスタンスを渡して呼び出します。そしてそのPrinterParameterインスタンスをPrinterBuilderのコンストラクタに渡して呼び出します。
このPrinterBuilderに対するAPI呼び出しは、手順5で指定する配列要素の要素数分だけ繰り返されます。

.add(
   new StarXpandCommand.PrinterBuilder(
       new StarXpandCommand.Printer.PrinterParameter()
           .setTemplateExtension(
               new StarXpandCommand.TemplateExtensionParameter()
                   .setEnableArrayFieldData(true)
           )
   )

5配列要素のフィールドデータを印刷するため、配列要素（item_listキーの値）のフィールドデータを指定した置き換え指定子を含んだ文字列を渡してactionPrintTextメソッドを呼び出します。

.actionPrintText(
    "${item_list.quantity}",
    new StarXpandCommand.Printer.TextParameter()
        .setWidth(2)
)
.actionPrintText(
    "${item_list.name}",
    new StarXpandCommand.Printer.TextParameter()
        .setWidth(24)
)
.actionPrintText(
    "${item_list.unit_price%6.2lf}\n",
    new StarXpandCommand.Printer.TextParameter()
        .setWidth(6)
)

6数値型のsubtotalキーの値（8.24）をフォーマット指定で印刷するため、数値フォーマットを指定した置き換え指定子を含んだ文字列を渡してactionPrintTextメソッドを呼び出します。

.actionPrintText(
    "${subtotal%6.2lf}\n",
    new StarXpandCommand.Printer.TextParameter()
        .setWidth(
            6,
            new StarXpandCommand.Printer.TextWidthParameter()
                .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
        )
)

7transaction_idキーの値（” 0123456789”）のバーコードを印刷するため、置き換え指定子を含んだ文字列を渡してactionPrintBarcodeメソッドを呼び出します。

.actionPrintBarcode(
    new StarXpandCommand.Printer.BarcodeParameter("${transaction_id}", StarXpandCommand.Printer.BarcodeSymbology.Code128)
        .setPrintHri(true)
)

8テンプレートを取得するため、getCommandsメソッドを呼び出します。

var template = await builder.getCommands();

9JSONフォーマットのフィールドデータを用意します。このフィールドデータでテンプレート側の指定箇所を置き換えます。

このセクションで作成したテンプレートを使用し、フィールドデータをプリンターに送信する方法はStep2を参照してください。

サンプルコード

フィールドデータ


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

テンプレート作成処理


var builder = new StarXpandCommand.StarXpandCommandBuilder();

builder.addDocument(
    new StarXpandCommand.DocumentBuilder()
        .addPrinter(
            new StarXpandCommand.PrinterBuilder()
                .styleInternationalCharacter(StarXpandCommand.Printer.InternationalCharacterType.Usa)
                .styleCharacterSpace(0.0)
                .actionPrintImage(new StarXpandCommand.Printer.ImageParameter("logo_01.png", 406))
                .add(
                    new StarXpandCommand.PrinterBuilder()
                        .styleAlignment(StarXpandCommand.Printer.Alignment.Center)
                        .styleBold(true)
                        .styleInvert(true)
                        .styleMagnification(new StarXpandCommand.MagnificationParameter(2, 2))
                        .actionPrintText("${store_name}\n")
                )
                .actionFeed(1.0)
                .actionPrintText(
                    "Order ${order_number}",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            16
                        )
                )
                .actionPrintText(" ")
                .actionPrintText(
                    "${time}\n",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            15,
                            new StarXpandCommand.Printer.TextWidthParameter()
                                .setAlignment(StarXpandCommand.Printer.TextAlignment.Right)
                                .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
                        )
                )
                .actionPrintText(
                    "Sale for ${sales_type}",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(16)
                )
                .actionPrintText(" ")
                .actionPrintText(
                    "Served by ${server}\n",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            15,
                            new StarXpandCommand.Printer.TextWidthParameter()
                                .setAlignment(StarXpandCommand.Printer.TextAlignment.Right)
                                .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
                        )
                )
                .actionPrintText(
                    "Transaction #${transaction_id}\n"
                )
                .actionPrintRuledLine(
                    new StarXpandCommand.Printer.RuledLineParameter(48.0)
                )
                .add(
                    new StarXpandCommand.PrinterBuilder(
                        new StarXpandCommand.Printer.PrinterParameter()
                            .setTemplateExtension(
                                new StarXpandCommand.TemplateExtensionParameter()
                                    .setEnableArrayFieldData(true)
                            )
                    )
                        .actionPrintText(
                            "${item_list.quantity}",
                            new StarXpandCommand.Printer.TextParameter()
                                .setWidth(2)
                        )
                        .actionPrintText(
                            "${item_list.name}",
                            new StarXpandCommand.Printer.TextParameter()
                                .setWidth(24)
                        )
                        .actionPrintText(
                            "${item_list.unit_price%6.2lf}\n",
                            new StarXpandCommand.Printer.TextParameter()
                                .setWidth(6)
                        )
                )
                .actionPrintRuledLine(
                    new StarXpandCommand.Printer.RuledLineParameter(48.0)
                )
                .actionPrintText(
                    "Subtotal",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(26)
                )
                .actionPrintText(
                    "${subtotal%6.2lf}\n",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            6,
                            new StarXpandCommand.Printer.TextWidthParameter()
                                .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
                        )
                )
                .actionPrintText(
                    "Tax",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(26)
                )
                .actionPrintText(
                    "${tax%6.2lf}\n",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            6,
                            new StarXpandCommand.Printer.TextWidthParameter()
                                .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
                        )
                )
                .add(
                    new StarXpandCommand.PrinterBuilder()
                        .styleBold(true)
                        .actionPrintText(
                            "Total",
                                new StarXpandCommand.Printer.TextParameter()
                                    .setWidth(26)
                        )
                        .actionPrintText(
                            "${total%6.2lf}\n",
                            new StarXpandCommand.Printer.TextParameter()
                                .setWidth(
                                    6,
                                    new StarXpandCommand.Printer.TextWidthParameter()
                                        .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
                                )
                        )
                )
                .actionPrintRuledLine(
                    new StarXpandCommand.Printer.RuledLineParameter(48.0)
                )
                .actionPrintText(
                    "${credit_card_number}",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(26)
                )
                .actionPrintText(
                    "${total%6.2lf}\n",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            6,
                            new StarXpandCommand.Printer.TextWidthParameter()
                                .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
                        )
                )
                .actionPrintText(
                    "Approval Code",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(16)
                )
                .actionPrintText(
                    "${approval_code}\n",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            16,
                            new StarXpandCommand.Printer.TextWidthParameter()
                                .setAlignment(StarXpandCommand.Printer.TextAlignment.Right)
                        )
                )
                .actionPrintRuledLine(
                    new StarXpandCommand.Printer.RuledLineParameter(48.0)
                )
                .actionPrintText(
                    "Amount",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(26)
                )
                .actionPrintText(
                    "${amount%6.2lf}\n",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            6,
                            new StarXpandCommand.Printer.TextWidthParameter()
                                .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
                        )
                )
                .actionPrintText(
                    "Total",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(26)
                )
                .actionPrintText(
                    "${total%6.2lf}\n",
                    new StarXpandCommand.Printer.TextParameter()
                        .setWidth(
                            6,
                            new StarXpandCommand.Printer.TextWidthParameter()
                                .setEllipsizeType(StarXpandCommand.Printer.TextEllipsizeType.End)
                        )
                )
                .actionPrintRuledLine(
                    new StarXpandCommand.Printer.RuledLineParameter(48.0)
                )
                .actionPrintText(
                    "Signature\n"
                )
                .add(
                    new StarXpandCommand.PrinterBuilder()
                        .styleAlignment(StarXpandCommand.Printer.Alignment.Center)
                        .actionPrintImage(
                            new StarXpandCommand.Printer.ImageParameter("signature.png", 256)
                        )
                )
                .actionPrintRuledLine(
                    new StarXpandCommand.Printer.RuledLineParameter(32.0)
                        .setX(8.0)
                )
                .actionPrintRuledLine(
                    new StarXpandCommand.Printer.RuledLineParameter(48.0)
                )
                .actionPrintText("\n")
                .styleAlignment(StarXpandCommand.Printer.Alignment.Center)
                .actionPrintText(
                    "${address}\n"
                )
                .actionPrintText(
                    "${tel}\n"
                )
                .actionPrintText(
                    "${mail}\n"
                )
                .actionFeed(1.0)
                .actionPrintText(
                    "${url}\n"
                )
                .actionPrintRuledLine(
                    new StarXpandCommand.Printer.RuledLineParameter(48.0)
                )
                .actionFeed(2.0)
                .actionPrintText(
                    "Powered by Star Micronics\n"
                )
                .actionPrintBarcode(
                    new StarXpandCommand.Printer.BarcodeParameter("${transaction_id}", StarXpandCommand.Printer.BarcodeSymbology.Code128)
                        .setPrintHri(true)
                )
                .actionCut(StarXpandCommand.Printer.CutType.Partial)
        )
)

var template = builder.getCommands()

テンプレート・フィールドデータ仕様

テンプレート

テンプレートとは、固定の印刷データと置き換え指定子を組み合わせて定義する、StarXpandCommandBuilderで作成する印刷レイアウトです。
置き換え指定子によりテンプレート内にフィールド（置き換え箇所）を定義します。置き換え指定子にはJSON形式のフィールドデータから同じキーを持つ値を代入できます。

以下の例のように、PrinterBuilder.actionPrintTextメソッド等の文字列（content引数）の中に置き換え指定子を埋め込んでください。通常のテキストと混在させることができます。

new StarXpandCommand.PrinterBuilder()
    .actionPrintText(
        "Date:${date}    Time:${time}\n"
    )

置き換え指定子のフォーマット

"${key-string}" のように、キー文字列を ${ と } で囲んだものを置き換え指定子として扱います。
フィールドデータ内に ’key-string' に一致するキーがあれば、そのキーの値で "${key-string}" 部分を置き換えます。
一致するキーがなければ、"${key-string}" 部分は無視して印字しません。

キー指定子

フィールドデータ内のキーを指定し、置き換えたいフィールドデータを特定します。
キーに使用可能な文字はASCII文字のみです。

ネストした要素のケース

ネストした要素を指定する場合はキーをピリオド(.)で接続します。

ネストした要素を指定する例

“${store.name}"

フィールドデータ

{
    "store" : {
        "name" : "Star Store",
        "address" : "123 Star Road, City, State 12345"
    }
}

配列要素のケース

キー指定子で配列要素を指すキーを指定することで、ひとつのフィールドに対して配列の要素数分の置き換えを行うことができます。

その場合、同時に配列の要素数分だけ繰り返すテンプレートの範囲を指定します。配列フィールドデータの使用を有効にしたTemplateExtensionParameterをセットしたPrinterParameter/PageModeParameterをPrinterBuilder/PageModeBuilderのコンストラクタに渡すことで、テンプレートのうちそのPrinterBuilder/PageModeBuilderが配列の要素数分だけ繰り返されます。

下記の例では、キー指定子で配列要素の子要素のキー（文字列型、数値型）を指定し、TemplateExtensionParameterで配列要素の繰り返し指定を行っています。その結果、繰り返し指定を行ったPrinterBuilderによる印刷が、フィールドデータの配列要素数４回だけ実行されます。

テンプレート（一部省略）

new StarXpandCommand.PrinterBuilder()
    .add(
    // このPrinterBuilderを配列の要素数分だけ繰り返す
       new StarXpandCommand.PrinterBuilder(
           new StarXpandCommand.Printer.PrinterParameter()
               .setTemplateExtension(
                   new StarXpandCommand.TemplateExtensionParameter()
                       .setEnableArrayFieldData(true)
               )
       )
       .actionPrintText(
           "${item_list.name}\t${item_list.unit_price%6.2lf}\n"
       )
       .add(new StarXpandCommand.PrinterBuilder()
           .styleUnderLine(true)
           .actionPrintText("\t\tx${item_list.quantity}\n")
       )
    )

フィールドデータ

{
    "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関数のフォーマット指定子のサブセットです。数値フォーマット指定子は省略することができます。省略した場合は %d（符号あり整数の10進出力）指定時と等価となります。

オプション指定	意味
♯	代わりの形に変換（16進数の場合、先頭に0xを付ける）
0	ゼロ埋めを行う
SP(空白文字)	符号付き変換において、正の値のとき左側に1文字空白を付加する
+	正の値のとき+記号を付加する
−	左詰め
表示桁数	[ 全体桁数 ] . [ 小数点以下の桁数 ] 例）　8.3　：　全体8桁、うち小数点以下に3桁を割り当てる

出力フォーマット指定子	意味
d	符号あり整数の10進出力
u	符号なし整数の10進出力
f	実数の出力
x	整数の16進小文字出力
X	整数の16進大文字出力
ld	符号あり倍精度整数の10進出力
lu	符号なし倍精度整数の10進出力
lf	倍精度実数の出力
lx	倍精度整数の16進小文字出力
lX	倍精度整数の16進大文字出力

エスケープ文字

置き換え指定子の開始の意味を持つ ${ を印刷したい場合、;を末尾に付けてエスケープ（${;）してください。

テンプレート印刷機能のために特別な意味を持つ下記の文字をフィールドデータのキーに含めたい場合、キー指定子の中で使用するときにその文字の前に\を付けてエスケープしてください。

% . ; }

テンプレート印刷機能対応API

置き換え指定子によりフィールドを定義できるAPIは下記のとおりです。

クラス	メソッド
PrinterBuilder	actionPrintText
	actionPrintBarcode
	actionPrintPdf417
	actionPrintQRCode
PageModeBuilder	actionPrintText
	actionPrintBarcode
	actionPrintPdf417
	actionPrintQRCode
DisplayBuilder	actionShowText（*）

* 配列要素を指定することはできません。

フィールドデータ

フィールドデータとは、JSON形式で記述する印刷毎に異なる印刷データセットです。テンプレート印刷機能を利用することで、テンプレート内の置き換え指定子が指定するフィールドデータの値が代入され、印字データが作成されます。

キーの仕様

キーに使用可能な文字はASCII文字のみです。

値の仕様

フィールドがどのような文字列に置き換えられるかは、下記のようにフィールドデータの値の型により決定します。

JSONの値の型	置き換え時の文字列
文字列型	値の文字列
数値型	数値フォーマット指定子に従った文字列
null型	キー指定子が指す値がnull型の場合は印字しない
真偽値型	trueの場合“true”、falseの場合”false”の文字列
オブジェクト型	キー指定子が指す値がオブジェクト型の場合は印字しない
配列型	キー指定子配列要素のケースに従う