Customizing Templates

Heather Haleen
Heather Haleen
  • Updated
Note: For an overview of templates, please click here

You can customize your Packing Slips and other templates. Whiplash uses liquid markup to allow access to some Order variables and logic, along with standard HTML and CSS.

  • Templates should be valid HTML documents.

  • If you make changes to the barcode in the template, ( {{order.barcode}} ), they will be reverted manually. Additionally, the order barcode CSS should not be overridden.

  • Templates should include CSS directly in the <head> or should link to an externally hosted stylesheet.

  • Aside from your logo, other images should be hosted externally and reference using absolute links.

  • It is recommended that all external files are available via both HTTP and HTTPS, and are referenced. For example: //your-external-asset.jpg (i.e. without specifying a protocol).

  • The Whiplash Team cannot assist with Template Customization. To use Templates, customers need in-house or hired HTML & CSS expertise.

Previewing

As you work, you may want to Preview the results. We'll pick a few recent Orders to choose from. If you want to see a particular Order or Package previewed, paste its unique ID in the URL:

Whiplash Liquid Objects

Whiplash Liquid Objects are referenced:

 {{order.number}}, {{customer.logo}}, {{order_item.sku}}

Order

  • id - the Whiplash Order id

  • number - the incoming Order number

  • barcode - order barcode

  • status - order status

  • created_at - when the order was added to Whiplash

  • updated_at - when the order was last updated in Whiplash

  • date - short format Order date

  • shipping_address - you can grab the Shipping Address all at once

  • ship_method - order full Shipping Method name

    • using {{ order.ship_method | replace:'Whiplash','' }} will remove the word "Whiplash" from some utility shipping methods.
  • shipping_carrier - order Shipping Carrier

  • shipping_service - order Shipping Service

  • order_items - the individual items in an order (see below for order item methods)

  • total - total order cost

  • ship_price - shipping cost

  • grand_total - order cost + shipping cost

  • paid - amount paid

  • balance - remaining balance

  • notes - any additional order notes

  • notes? - check if there are order notes

  • ship_notes - some Shopify orders have the gift notes here instead of notes
  • ship_notes? - check if there are ship notes
  • return_url - URL to web-based return/exchange form

  • domestic? - is this order domestic?

  • international? - is this order international?

  • greeting - attempts to return the shipping first name; falls back to "Friend"

  • tracking_numbers - an array of tracking numbers

  • tracking_link - the first or only tracking link for an order

  • tracking_links - a comma separated list of hyperlinked tracking numbers

  • billing_name

  • billing_street1

  • billing_street2

  • billing_city

  • billing_state

  • billing_state_abbr

  • billing_country

  • billing_zip

  • billing_phone

  • shipping_name

  • shipping_street1

  • shipping_street2

  • shipping_city

  • shipping_state

  • shipping_state_abbr

  • shipping_country

  • shipping_zip

  • shipping_phone

Order Item

  • sku - item SKU

  • quantity - how many were ordered

  • weight - item weight

  • price - item price

  • total - quantity x price

  • description - item description

Customer

  • name - customer name

  • logo - customer logo image

  • logo_url - logo image URL, if you'd like to use your own image tag or CSS

  • logo? - check if there is a customer logo uploaded

Warehouse

  • name - the name of the warehouse

  • shipping_address_1

  • shipping_address_2

  • shipping_city

  • shipping_state

  • shipping_zip - the postal code of the warehouse

  • shipping_country - the full name of the country, like "United States"

  • shipping_country_iso2 - the iso2 code for the country, like "US"

Liquid Reference

There are two types of markup in Liquid: Output and Tag.

  • Output markup (which may resolve to text) is surrounded by:
{{ matched pairs of curly brackets (ie, braces) }}
  • Tag markup (which cannot resolve to text) is surrounded by:
{% matched pairs of curly brackets and percent signs %}

Output

Here is a simple example of Output:

Hello {{name}}
Hello {{user.name}}
Hello {{ 'tobi' }}

Advanced Output: Filters

Output markup takes filters. Filters are simple methods. The first parameter is always the output of the left side of the filter. The return value of the filter will be the new left value when the next filter is run. When there are no more filters, the template will receive the resulting string. 

Hello {{ 'tobi' | upcase }}
Hello tobi has {{ 'tobi' | size }} letters!
Hello {{ '*tobi*' | textilize | upcase }}
Hello {{ 'now' | date: "%Y %h" }}

Standard Filters

  • date - reformat a date
  • capitalize - capitalize words in the input sentence
  • downcase - convert an input string to lowercase
  • upcase - convert an input string to uppercase
  • first - get the first element of the passed in array
  • last - get the last element of the passed in array
  • join - join elements of the array with certain character between them
  • sort - sort elements of the array
  • map - map/collect an array on a given property
  • size - return the size of an array or string
  • escape - escape a string
  • escape_once - returns an escaped version of html without affecting existing escaped entities
  • strip_html - strip html from string
  • strip_newlines - strip all newlines (\n) from string
  • newline_to_br - replace each newline (\n) with html break
  • replace - replace each occurrence e.g. 
    • {{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'
  • replace_first - replace the first occurrence e.g. 
    • {{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'
  • remove - remove each occurrence e.g. 
    • {{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'
  • remove_first - remove the first occurrence e.g. 
    • {{ 'barbar' | remove_first:'bar' }} #=> 'bar'
  • truncate - truncate a string down to x characters
  • truncatewords - truncate a string down to x words
  • prepend - prepend a string e.g. 
    • {{ 'bar' | prepend:'foo' }} #=> 'foobar'
  • append - append a string e.g. 
    • {{ 'foo' | append:'bar' }} #=> 'foobar'
  • minus - subtraction e.g. 
    • {{ 4 | minus:2 }} #=> 2
  • plus - addition e.g. 
    • {{ '1' | plus:'1' }} #=> '11',
    • {{ 1 | plus:1 }} #=> 2
  • times - multiplication e.g 
    • {{ 5 | times:4 }} #=> 20
  • divided_by - division e.g. 
    • {{ 10 | divided_by:2 }} #=> 5
  • split - split a string on a matching pattern e.g. 
    • {{ "a~b" | split:"~" }} #=> ['a','b']
  • modulo - remainder, e.g. 
    • {{ 3 | modulo:2 }} #=> 1

Meta Fields

You can add arbitrary Meta Key/Meta Value pairs (more information is available here). Call them individually like this:
 

{{ order.meta_values | where: "key", "notecard_text" | map: "value" }}


Full code to generate the screenshot above:

<html><body>
    order_id:  {{ order.id }}<br />
    
    <h2>All Order MetaValues:</h2>
    {% for meta_value in order.meta_values %}
    {{ meta_value.key }}: {{ meta_value.value }}<br />
    {% endfor %}

    <h3>ShippingVendors: 
        {{ order.meta_values | where: "key", "shipping_vendor" | map: "value" }}<br/>
    </h3>

    <table border="1">
        <tr><th>ITEM SKU</th><th>QTY</th><th>OrderItem MetaValues</th><th>Item MetaValues</th></tr>
        {% for order_item in order.order_items %}
        <tr>
            <td>{{ order_item.sku }}</td>
            <td>{{ order_item.quantity }}</td>
            <td>
                <table>
                    {% tablerow meta_value in order_item.meta_values %}
                    {{ meta_value.key }}: {{ meta_value.value }}
                    {% endtablerow %}
                </table>
            </td>
            <td>
                {% for meta_value in order_item.item.meta_values %}
                <p>{{ meta_value.key }}: {{ meta_value.value }}</p>
                {% endfor %}
            </td>
        </tr>
        {% endfor %}
    </table>
    </body></html>

Tags

Tags are used for the logic in your template. New tags are very easy to code.

Here is a list of supported tags:

  • assign - assigns some value to a variable

  • capture - block tag that captures text into a variable

  • case - block tag, its the standard case...when block

  • comment - block tag, comments out the text in the block

  • cycle - cycle is usually used within a loop to alternate between values, like colors or DOM classes.

  • for - for loop

  • if - standard if/else block

  • include - includes another template; useful for partials

  • raw - temporarily disable tag processing to avoid syntax conflicts.

  • unless - mirror of "if" statement

Comments

Comment is the simplest tag. It prevents the content from being written to the document.

We made 1 million dollars {% comment %} in losses {% endcomment %} this year

Raw

Raw temporarily disables tag processing. This is useful for generating content (for example Mustache, Handlebars) which uses conflicting syntax.

{% raw %}
  In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
{% endraw %}
 

If / Else

If/Else should be well known from any other programming language. Liquid allows you to write simple expressions in the if or unless (and optionally, elsif and else) clause:

{% if user %}
  Hello {{ user.name }}
{% endif %}

# Same as above
{% if user != null %}
  Hello {{ user.name }}
{% endif %}

{% if user.name == 'tobi' %}
  Hello tobi
{% elsif user.name == 'bob' %}
  Hello bob
{% endif %}

{% if user.name == 'tobi' or user.name == 'bob' %}
  Hello tobi or bob
{% endif %}

{% if user.name == 'bob' and user.age > 45 %}
  Hello old bob
{% endif %}

{% if user.name != 'tobi' %}
  Hello non-tobi
{% endif %}

# Same as above
{% unless user.name == 'tobi' %}
  Hello non-tobi
{% endunless %}

# Check for the size of an array
{% if user.payments == empty %}
   you never paid !
{% endif %}

{% if user.payments.size > 0  %}
   you paid !
{% endif %}

{% if user.age > 18 %}
   Login here
{% else %}
   Sorry, you are too young
{% endif %}

# array = 1,2,3
{% if array contains 2 %}
   array includes 2
{% endif %}

# string = 'hello world'
{% if string contains 'hello' %}
   string includes 'hello'
{% endif %}

Case Statement

If you need more conditions, you can use the case statement:

{% case condition %}
{% when 1 %}
hit 1
{% when 2 or 3 %}
hit 2 or 3
{% else %}
... else ...
{% endcase %}

Example:

{% case template %}

{% when 'label' %}
     // {{ label.title }}
{% when 'product' %}
     // {{ product.vendor | link_to_vendor }} / {{ product.title }}
{% else %}
     // {{page_title}}
{% endcase %}

Cycle

Often, you have to alternate between different colors or similar tasks. Liquid has built-in support for such operations, using the cycle tag.

{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}


This will result in:

one
two
three
one


If no name is supplied for the cycle group, then it is assumed that multiple calls with the same parameters are one group.

If you want to have total control over cycle groups, you can specify the name of the group. This can even be a variable.

{% cycle 'group 1': 'one', 'two', 'three' %}
{% cycle 'group 1': 'one', 'two', 'three' %}
{% cycle 'group 2': 'one', 'two', 'three' %}
{% cycle 'group 2': 'one', 'two', 'three' %}

The above will result in:

one
two
one
two

For loops

Liquid allows for loops over collections:

{% for item in array %}
  {{ item }}
{% endfor %}


When iterating a hash, item[0] contains the key and item[1] contains the value:

{% for item in hash %}
  {{ item[0] }}: {{ item[1] }}
{% endfor %}


During every for loop, the following helper variables are available for extra styling needs:

forloop.length      # => length of the entire for loop
forloop.index       # => index of the current iteration
forloop.index0      # => index of the current iteration (zero based)
forloop.rindex      # => how many items are still left?
forloop.rindex0     # => how many items are still left? (zero based)
forloop.first       # => is this the first iteration?
forloop.last        # => is this the last iteration?


There are several attributes you can use to influence which items you receive in your loop.

A limit:int lets you restrict how many items you get. Whereas, offset:int lets you start the collection with the nth item.

# array = [1,2,3,4,5,6]
{% for item in array limit:2 offset:2 %}
  {{ item }}
{% endfor %}
# results in 3,4


Reversing the loop:

{% for item in collection reversed %} {{item}} {% endfor %}


Instead of looping over an existing collection, you can define a range of numbers to loop through. The range can be defined by both literal and variable numbers:

# if item.quantity is 4...
{% for i in (1..item.quantity) %}
  {{ i }}
{% endfor %}
# results in 1,2,3,4

Variable Assignment

You can store data in your own variables, to be used in output or other tags as desired. The simplest way to create a variable is with the "assign" tag, which has a pretty straightforward syntax:

{% assign name = 'freestyle' %}

{% for t in collections.tags %}{% if t == name %}
  <p>Freestyle!</p>
{% endif %}{% endfor %}


Another way of doing this would be to assign true/false values to the variable:

{% assign freestyle = false %}

{% for t in collections.tags %}{% if t == 'freestyle' %}
  {% assign freestyle = true %}
{% endif %}{% endfor %}

{% if freestyle %}
  <p>Freestyle!</p>
{% endif %}


If you want to combine a number of strings into a single string and save it to a variable, you can do this with the "capture" tag. This tag is a block which "captures" whatever is rendered inside it, then assigns the captured value to the given variable instead of rendering it to the screen.

  {% capture attribute_name %}{{ item.title | handleize }}-{{ i }}-color{% endcapture %}

  <label for="{{ attribute_name }}">Color:</label>
  <select name="attributes[{{ attribute_name }}]" id="{{ attribute_name }}">
    <option value="red">Red</option>
    <option value="green">Green</option>
    <option value="blue">Blue</option>
  </select>

 

Related Questions:

How do I customize Packing Slips?

How do I create a custom template?

How do I preview a custom template?