Custom Fields are similar to Excel formulas, but they use our extended version of Shopify's Liquid templating language.
Custom Fields can be used to do simple things like mathematical calculations, extracting line item properties, or displaying metafields. More advanced features include dynamic filter criteria, conditional logic, loops, and format conversions. You can even build an entire template in Liquid, as in this XML example.
The below is intended for a more technical audience, and represents only a subset of the possible uses of the feature.
Our support team is always happy to help setup your calculation, dont hesitate to email xporter@moddapps.com or click the chat bubble in the app for help!
Introduction
We have extended Shopify's standard Liquid with additional filters meant to make common reporting tasks easier . For example, we support using arithmetic operators and parentheses (+, -, *, /) to create complex expressions like
{% assign temporary = ((order.total_spent * 400) + 20)/256 %}
Another major difference between Xporter's liquid and Shopify's is that we follow a convention for naming our liquid variables, so you can figure out the appropriate name of a variable from the fields specified in the template section, rather than having to guess at what they may have been named. There's a simple formula you can follow to figure out what something might be named. But before, we get there, we need to define a couple terms.
Quick Glossary
Liquid Field: When you click "Add Order Customer Field", or "Add Product Customer Field", the box that appears is what we mean by "Liquid Field".
Property: A piece of information, such as "Total Price", or "Total Tax".
Object: Any heading in Shopify under which properties are grouped. Examples are "Order", "Product", "Line Item", etc..
Handle: A single string, all lower case, with no spaces, with no hypens, that is the programmatical name of this field. Examples are "product_id", "total_price".
Index: A single string, all lower case, with no spaces, that represents an absolute path to a property, object or liquid field, ending with its handle. Examples are "order", "product", "order-line_items", "order-line_items-product_id", "order-line_items-liquid_field_1".
Child: An object contained within another object. As an example, "Line Items" is a child of "Order". "Variants" is a child of "Product".
Parent: The opposite of the child relation, described above; the containing object. We also refer to the containing object of a property as a "Parent".
Handlelization & Indexification
Knowing how to convert from a field's name into it's handle is important. Using the following formula will eliminate any guesswork at figuring out what a field's liquid name is.
- Take note of the name of the object/property/field you'd like to indexify (e.g. "Product ID"). In addition to this take note of the parent of the object/property/field you'd indexify. (e.g. "Line Items" is the parent of "Product ID". "Product" is the parent of "Variants".). Note every parent of this parent as well. Now, arrange these parents in a list, in the order of most general to most general to most specific. Then, add the object/property you're looking to index to the end of the list. (e.g. If you're looking for "Product ID" under "Line Items", under "Order", you should have the following list: "Order", "Line Items", "Product ID")
- From this list, lowercase everything, and replace any spaces with underscores. Between list items, put a dash. (e.g. "Order", "Line Items", "Product ID" becomes "order-line_items-product_id".) This is the canonical index of the property.
In order to use the handle in liquid fields, these indices must then be transformed into strings that liquid can understand. The process is as follows:
- From the property's index (as derived above), replace all dashes with periods.
- If you're in a child node, you may use the singular version of the child's name to shorten your index. To do this, replace the child's index in your property index with a singular version of the child's handle (e.g. If you have a "Line Items" liquid field, and you're looking for "Product ID", the canonical index is "order.line_items.product_id". This can be shortened by replacing "order.line_items" with "line_item", making it "line_item.product_id".)
- Qualify plural handles (any object with a + next to their name in the property listing is plural) with a number to represent their position in the sequence. (e.g. In "order-line_items.product_id", "line_items" must be qualified; you must specify which line item you'd like. You can do this by using square brackets and an integer, starting from 0. "order.line_items[0].product_id" would be the product id of the first line item of the order, for example.). This may be not necessary if you've made use of shortening your index, shown in step 2, above (e.g. line_item.product_id, was already shortened, so there are no plurals here, and no need to qualify.)
And that's everything!
Date Handling
Xporter has robust date handling. Every date in Xporter is a full object, and has a bunch of associated functions you can use to work with dates. Comparing dates with <, >, <=, >=, == and != will do what you expect them to do.
In addition, we have introduced two powerful filters to help working with dates, and kept one from shopify; they are as follows:
date_parse: The date_parse filter uses a sophisticated parser to convert dates from strings to actual date objets. For example:
{% assign my_date = "2014-06-07T16:03:54" | date_parse %} {% assign my_date = "Februrary 10th, 1989" | date_parse %}
date: The date filte is a holdover from Shopify that allows you to use the standard strftime patterns to format dates into strings. For example:
{{ "2014-06-07T16:03:54" | date_parse | date: "%Y" }}
Will output "2014".
date_math: The date_math filter takes two arguments, and allows you to do proper date math. The first argument is the numerical offset, and the second is the unit. Valid units are "seconds", "minutes", "hours", "days", "weeks", "months", "years". For example:
{{ "2014-06-07T16:03:54" | date_parse | date_math: -2, "months" | date_math: 6, "seconds" | date: "%B %d, %Y, %H:%M:%S" }}
Will output "April 7th, 2014, 16:03:52".