Skip to main content

Creating an XML template using Liquid

Updated

Basics

XML (eXtensible Markup Language) is a way to format data; many modern systems will use JSON, but older/legacy systems still support/use XML. 

It is Extensible and nondescript, meaning that it can encapsulate as many objects, or as many levels of an object as it needs to; and that it doesn't have a hard structure.

<?xml version="1.0" encoding="UTF-8"?>
<Customer>
    <FirstName>John</FirstName>
    <LastName>Doe</LastName>
    <Email>john.doe@eshopadmin.com</Email>
    <Address default="true">
        <Address1>123 Fake Street</Address1>
        <Address2>Suite 000</Address2>
        <PostalCode>H4B 5G0</PostalCode>
        <City>Montreal</City>
        <Province>Quebec</Province>
    </Address>
</Customer>

 

Header

<?xml version="1.0" encoding="UTF-8"?>

  • Used to define the specifications of the document.
  • This will rarely change, and the above is the standard default.

Open and closing tags

<Customer></Customer>

  • Every object must have an opening and closing tag.
  • The names are case sensitive and the closing tag is started with a '/'.
  • All data or sub-objects for a given object must live within the opening and closing tags.

Nested objects

<Customer>

<Email></Email>

</Customer>

  • Any data attributed to an object should live within that object so the association is assumed.

Attributes

<Customer active=”true”></Customer>

  • 'active' here is an attribute, and 'true' is its value.
  • Attributes live within a tag.
  • Attributes are not used often, but they are supported by the format.

In Liquid

{% capture xml %}

<?xml version="1.0" encoding="UTF-8"?>
<Orders>
    {% for order in orders %}<order>
        <name>{{ order.name }}</name>
    </order>{% endfor %}
</Orders>

{% endcapture %}

In liquid we can output xml. Above is an example of how we can do that.

Use of the 'capture' tag is not needed in all cases.

Whitespace matters

Where you put your liquid tags and newlines will effect the output of the xml.

While in general the newline formatting of xml shouldn't matter, it can make it hard to read.

In some cases the software parsing the xml may not like the new lines.

Xporter

Professional Plan template setup

  1. Choose Main Row  (Customer,Order,Product,etc)
  2. Add 1 empty liquid field
  3. Add filters as normal
  4. In Advanced Settings, change the row format type to '*.txt'
    1. If you are automatically generating the file, you can and should change the attachment type and/or path name extension to '*.xml' over '*.txt' or '{{ report.extension  }}.
  5. Use the 'Hide Column Names' tweak in section 13
  6. Add a Liquid Row, drag it to the top, and enter your liquid there

Extras

  • You should replace your newlines with literal '\n', you can do this a few ways, one is in the Extras section.
  • A note on 4. this is so the system doesn't try to format your output.
  • Calculated fields
    • These may not show up in the superheader, this is due to them not being calculated by the system.
    • If this is the case you want to force it to calculate by using it in the liquid field.
    • Do not output anything, just assign the field you want to a dummy variable. {% assign tmp = order.total_shipping %}
  • You do not need to use the 'capture' tag in Xporter
  • A note on the file type/extension: Since xml files are just structure text files you can just manually change the extension of the file (rename it) if you manually generate an xml report.
    • The name will have no effect on the content of the file.

Related articles