Table of Content

Install & Usage

Develop

F&Q

SpiritWeb Development Manual

This document will introduce how to use SpiritWeb for printing on your website. Before reading, it's recommended to first design a label using SpiritDesigner to obtain a label ID.

To quickly learn the API, it's recommended to use the Interactive Testing Sandbox.

Print Spirit offers a JavaScript-based printing API, making it easy to handle printing tasks directly in the browser, especially for high-quality label printing.

Quick Start

1. Include JS

To use the Print Spirit JS API, you need to include spirit.js. This JS file will automatically inject a global class: SPIRIT, which you can use to call the JS API.

For HTTP, Spirit listens on two ports to avoid issues with port occupancy by other programs.

<script src="http://127.0.0.1:9011/js/spirit.js"></script>
<script src="https://127.0.0.1:19011/js/spirit.js"></script>

For HTTPS, if your application is using HTTPS, include Spirit using HTTPS.

<script src="https://127.0.0.1:9443/js/spirit.js"></script>
<script src="https://127.0.0.1:19443/js/spirit.js"></script>

2. Execute Printing

Printing involves three steps:

  1. Use the SPIRIT.open command to obtain a printing instance p. You can use SPIRIT to check if the print control is installed and prompt users to download it if not.
  2. Complete the printing with p.PrintLabel(). The first parameter is the template ID (How to get the template ID), the second parameter is a list of variables that will replace the corresponding variables in the template during printing (What are template variables?), and the third parameter is the URL for template data, defaulting to the current website.
  3. Close the printing instance p using p.close().

Here's a sample code:

SPIRIT.open(opt, function(p) {
p.PrintLabel(labelID, {var1:xxx, var2:xxx, ...});
p.close();
})

To avoid excessive callback functions, equivalent Promise and async/await syntax is supported, for example:

const p = await SPIRIT.open(opt);
p.PrintLabel(labelID, {var1:xxx, var2:xxx, ...});
p.close();

The opt parameter for SPIRIT.open specifies printer settings including printer name, type, resolution, font, etc., which can override default values. Using an empty object will apply the default configuration.

Parameter Description Example Note
name Printer name
type Printer type ZPL/CPCL/WIN
dpi Printer resolution (dpi) 203 dpi/dpmm can be chosen
dpmm Printer resolution (dpmm) 8
font Printer font MHEIGB18.TTF Not valid for Windows printers
cache Use template cache false Default is not used
imgcache Use image cache true Default is used
col Number of labels per row 1 Default is 1, auto calculates based on paper/label size
row Number of rows per page 1 Default is 1, auto calculates based on paper/label size
master For master-slave mode, set the master server IP Refer to Enterprise Intranet Solution

3. A Complete Example

This example demonstrates how to use a shared template, set template variables on a webpage, and complete the printing process. The template (View) ID is: 953745b5-90f3-4852-805d-d11f994d2374, with two defined template variables: name and phone.

For this example, you need a printer (ZPL, CPCL, or Windows printer) and the print control installed. If not installed, you will be prompted to download and install it during the first print attempt.

<!DOCTYPE html>
<html>
  <head>
      <title>Print Test</title>
      <!-- for http-->
      <script src="http://127.0.0.1:9011/js/spirit.js"></script>
      <script src="http://127.0.0.1:19011/js/spirit.js"></script>
      <!-- for https -->
      <!--script src="https://127.0.0.1:9443/js/spirit.js"></script-->
      <!--script src="https://127.0.0.1:19443/js/spirit.js"></script-->
  </head>
  <body>
  <script type="text/javascript">
    function do_print() {
      if (!SPIRIT) {
        if (!confirm('no spirit found, install now？')) return;
        window.location.href='http://www.printspirit.cn/download/spirit-web-setup.exe';
      }

      vars= {
        name:document.getElementById("name").value, 
        phone:document.getElementById("phone").value
      };
      SPIRIT.open({dpi:203, cache:true}, function(p) {
        p.PrintLabel("953745b5-90f3-4852-805d-d11f994d2374", vars);
        p.close();
      })
    }
  </script>
  <p>name<input id="name" ></p>
  <p>phone<input id="phone" ></p>
  <p><Button onclick="do_print()">PRINT</Button></p>
  </body>
</html>

Note Print Spirit supports both HTTP and HTTPS protocols. The protocol of the print.js script should match that of your main website.
To prevent local port conflicts, if port 9011 (or 9443 for HTTPS) is occupied, Print Spirit will attempt to open port 19011 (or 19443 for HTTPS). You can include both ports' print.js scripts to achieve adaptive port handling.

Other Printing Modes

In addition to supporting label template printing, the control also supports two other printing modes for advanced users.

Command Mode

In Command Mode, you can directly send print commands to the printer.

For example, the following code uses the Text command to print "测试文本" (test text) with 4 Chinese characters. More print commands can be found in the JS API Manual.

SPIRIT.open(opt, function(p){
    p.initLabel(80, 210);
    p.Text(0, 0, "Test Text");
    p.print();
    p.close();
})

Raw Mode

Raw Mode sends raw print commands, allowing direct control over the printing process. For instance, you can use a dot matrix printer for continuous printing.

SPIRIT.open(opt, function(p){
    prn = p;
})

...

p.printRaw(data)

...

Leave Your Message

login