JourneyApps Print (Android)

Overview

Not recommended

JourneyApps Print is no longer recommended and support for it may be removed in the future. Use the SerialPort API instead to communicate with Zebra Bluetooth printers.

Platform compatibility

• The JourneyApps Print app is only available for Android devices and can be downloaded from the Play Store.

• This feature is currently only available for customers on the Enterprise plan.

The JourneyApps container can print receipts and other documents using a Zebra ZQ500 series mobile Bluetooth printer. This page describes how to create a basic template that can be printed, with the fundamental concepts that need to be understood to print using the JourneyApps Print app.

The JourneyApps Print app

The JourneyApps Print app is a separate application that handles the printing with the Zebra printer. It is currently only available on Android and can be downloaded from the Play Store.

How to print from JourneyApps

The Zebra printer series uses a language called ZPL (Zebra Programming Language) to construct a document. We construct the template for the document in the JourneyApps app using JavaScript/TypeScript, and then we pass the constructed string to the JourneyApps Print app using deep-linking. We use external.uri in JourneyApps to open the JourneyApps Print app as follows:

return external.uri('journeyprint://print?payload='+ generateZPL());

where generateZPL() is any function that generates your ZPL string.

Understanding ZPL

ZPL is a page description language that uses plain text to build the desired document. It uses special characters and commands to distinguish between instructions and text to print. The official documentation of ZPL can be found here.

ZPL Quick Tips

• ZPL is plain text

• All ZPL commands are uppercase

• All ZPL commands begin with a caret ("^")

• A ZPL string begins with ^XA

• A ZPL string ends with ^XZ

Commonly used commands

ZPL Command	Variables	Example	Explanation	Note
^PWa	a = width	^PW800	Printing Width	Must be used before output is printed.
^LHx,y	x = horizontal y = vertical position	^LH20,100	Label Home
^LLy	y = vertical length	^LL1500	Label Length	Must be used before output is printed.
^POa	a = orientation I: inverted, N: normal	^POI	Print Orientation	Must be used before output is printed.
^FOx,y	x = horizontal y = vertical position	^FO50,100	Field Origin	Sets the position of an individual field.
^FD and ^FS		^FDHello^FS	Field Data and Field Stop	Used to print text. The example will print: Hello.
^CFt,s	t = type s = size	^CF0, 28	Change Font	Will change the font for all following text until another ^CF is used.
^FH		^FO10,50^FH^FDSpecial characters _23 and _3E ^FS	Field Hex	Uses ASCII hex codes to print special characters using an underscore. This will print Special characters: # and >.

Example ZPL

Here's a quick example of a ZPL document:

^XA
^POI
^PW875
^LH0,0
^LL150
^CF0,28
^FO10,50^FH^FDThese are special characters: _23 and _3E ^FS
^XZ

Special characters

Since ZPL uses some characters for certain commands, like ^ and #, we must escape certain characters using the Field Hex (^FH) command. If a field has ^FH command in front like the example above, anything following an underscore ("_") will be escaped. The two characters after the underscore are the hex ASCII values for the corresponding character. For example, 3E is the hex value for the ">" sign.

For static text you can escape manually by using the hex ASCII table.

For dynamic text, you can use this function to automatically escape all special characters:

function escapeZPL(toEscape) {
var returnString = "";
    for (var i = 0; i < toEscape.length; i++) {
        var tempCode = toEscape.charCodeAt(i);
        if ((tempCode < 32) || (tempCode > 32 && tempCode < 48) || (tempCode > 57 && tempCode < 65) || (tempCode > 90 && tempCode < 97) || (tempCode > 122)) {
            returnString = returnString + "_"+tempCode.toString(16).toUpperCase();
        } else {
            returnString = returnString + toEscape.charAt(i);
        }
    }
    return returnString;
}

Size Units

The unit of size when printing is dots. The default printing resolution is 8dpmm (dots / mm). If your page is 4.3inch (109mm) wide, the total dots is 8dpmm x 109mm = 872 dots.

Generating ZPL in JavaScript

ZPL uses absolute positioning for layout. Therefore, you must keep track of the position where you want to print, as well as the total length of your document. A good idea is to have a variable called currentHeight and use print lines relative to this. After each line is added, add the height of the line to currentHeight. You can define certain constants to only change one value to change the whole document:

var zplStartString = "^XA\n^PW610\n";
var zplMainString = "";
var zplBottomString = "^XZ";
var currentHeight = 100; //these units are in dots. 100 dots is 12.5mm
var leftMargin = 20;
var lineHeight = 30;
var bottomMargin = 80;

zplMainString += "^FO"+leftMargin+","+currentHeight+"^FH^FDSome text^FS";
currentHeight += lineHeight; // this moves currentHeight on by the specified lineHeight

At the end of our document, we must add the ^LL command to the total string. It must be between zplStartString and zplMainString:

zplStartString += "^LL" + (currentHeight + bottomMargin);
return (zplStartString + zplMainString + zplBottomString);

The Zebra Bluetooth printers have a permanent memory that stores certain values even if the device is turned off. Many of the commands are persistent and should be explicitly defined every time you print. For example, if the previous print had a ^LL100 (label length) command, and you don't specify a new ^LL, it will print the document also with a length of 100.