.. _xml-index:

###########
XML Support
###########

The XML support in |trademark| printers provides a way to select and populate
layouts from any XML data source that conforms to the requirements specified below.

============
Requirements
============

Encoding
========

Data must be :term:`UTF-8` encoded.

XML DTD
=======

The XML data shall conform to this DTD but no actual validation is performed.
This means that other elements will be ignored.

.. code-block:: dtd

    <!ELEMENT labels (label)*>
    <!ATTLIST labels _FORMAT CDATA #IMPLIED>
    <!ATTLIST labels _JOBNAME CDATA #IMPLIED>
    <!ATTLIST labels _QUANTITY CDATA #IMPLIED>
    <!ELEMENT label (variable)*>
    <!ELEMENT variable (#PCDATA)>
    <!ATTLIST variable name CDATA #IMPLIED>

Example:

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <labels _FORMAT="1">
      <label>
        <variable name="serial_number">12345</variable>
        <variable name="lot">ABC123</variable>
      </label>
    </labels>

Example with a custom job id and product count 1:

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <labels _FORMAT="1" _JOBNAME="test_job" _QUANTITY="1">
      <label>
        <variable name="serial_number">12345</variable>
        <variable name="lot">ABC123</variable>
      </label>
    </labels>

.. tip::

    Use ``_QUANTITY`` in the XML to specify the product count for the job. No ``_QUANTITY``
    means unlimited product count.

Transport Channels
==================

XML documents shall be sent over raw TCP to a server on port 9200.
Sending raw data in Windows to a TCP server can e.g. be done with putty.

Layouts
=======

Layouts must refer to file names of layouts stored in the printer.

Variable Substitution
=====================

Variables in text fields and bar codes will be substituted using the variables in the
XML file.

===================================================
Example: Populating a built-in layout with XML data
===================================================

#.  Create a layout with layout name ``test.layout`` containing a text field
    with a variable reference to the product variable ``{{ product }}``. This
    can be done by:

    -   Using the built-in layout editor.
    -   Copying the file below to
        :file:`/home/evolabel/userdata/layouts/test.layout`.

        .. code-block:: json

            {
                "fields": [
                    {
                        "y": 50,
                        "x": 100,
                        "type": "text",
                        "spans": [
                            {
                                "text": "Name: {{ product }}",
                                "font": "FreeSans 10",
                                "template": 1
                            }
                        ]
                    }
                ],
                "layout_version": "2.0",
                "width": 500,
                "height": 200
            }

    -   Downloading the layout using the
        `layouts.put <http://docs.evolabel.com/api/latest/namespace_layouts.html#layouts-put>`_
        JSON-RPC method.


#.  Send the XML data below to activate the layout and populate the product variable.

    .. code-block:: xml

        <?xml version="1.0" encoding="UTF-8"?>
        <labels _FORMAT="test.layout">
          <label>
            <variable name="product">Test Product</variable>
          </label>
        </labels>


==============================================
Example: Populating a ZPL-layout with XML data
==============================================

Named variables in a ZPL layout can be created using ``^FD`` statements followed by a string
representing the variable name.

#.  Send the ZPL data below on port 9100 to store a layout called :file:`SERIAL.ZPL`
    in the layout repository.

    .. code-block:: zpl

        ^XA
        ^LL1115
        ^PW850
        ^DFE:SERIAL.ZPL^FS
        ^MCY
        ^LRN^FWN^CFD,24^LH0,0
        ^CI0^PR2^MNY^MTT^MMT^MD0^PON^PMN
        ^LT0
        ^FO28,49^GB786,106,10^FS
        ^A0N,54,72^FO143,83^CI0^FDSerial Label^FS
        ^FO21,652^GB787,5,5^FS
        ^FO21,830^GB787,5,5^FS
        ^FO21,970^GB787,5,5^FS
        ^FO27,335^GB787,5,5^FS
        ^A0N,34,34^FO38,847^FR^CI0^FDLot Status:^FS
        ^A0N,34,34^FO38,996^FR^CI0^FDSerial Status:^FS
        ^A0N,34,34^FO36,177^FR^CI0^FDItem:^FS
        ^A0N,34,34^FO36,355^FR^CI0^FDLot:^FS
        ^A0N,34,34^FO36,509^FR^CI0^FDSN:^FS
        ^FO24,495^GB787,5,5^FS
        ^A0N,34,34^FO38,683^FR^CI0^FDRev:^FS
        ^A0N,54,72^FO635,82^CI0^FN999^FDorganization^FS
        ^A0N,54,62^FO109,163^CI0^FN998^FDitem^FS
        ^BY2,2.7^FO108,223^B3N,N,95,N,N^FN998^FDitem^FS
        ^A0N,34,34^FO109,357^FR^CI0^FN997^FDlot^FS
        ^BY2,2.7^FO108,395^B3N,N,95,N,N^FN997^FDlot^FS
        ^A0N,34,34^FO107,510^FR^CI0^FN996^FDserial_number^FS
        ^BY2,2.7^FO108,549^B3N,N,95,N,N^FN996^FDserial_number^FS
        ^A0N,34,34^FO108,685^FR^CI0^FN995^FDrevision^FS
        ^BY2,2.7^FO108,727^B3N,N,95,N,N^FN995^FDrevision^FS
        ^A0N,40,40^FO36,904^FR^CI0^FN994^FDlot_status^FS
        ^A0N,40,40^FO40,1048^FR^CI0^FN993^FDserial_number_status^FS
        ^PQ1,0,1,Y
        ^XZ


#.  Send the XML data below to activate the layout and populate the product variables.

    .. code-block:: xml

        <?xml version="1.0" standalone="no"?>
        <!DOCTYPE labels SYSTEM "label.dtd">
        <labels _FORMAT="E:SERIAL.ZPL" _QUANTITY="1" _PRINTERNAME="Printer 1" _JOBNAME="LBL101">
            <label>
                <variable name="organization">611</variable>
                <variable name="item">Nuts</variable>
                <variable name="lot">1234</variable>
                <variable name="serial_number">12345</variable>
                <variable name="revision">V2</variable>
                <variable name="lot_status">1234</variable>
                <variable name="serial_number_status">Active</variable>
            </label>
        </labels>