How to: Display Items
Square Online SDK
The Square Online SDK has item helpers to simplify the logic around item variations, options, and modifiers. This includes additional logic not covered here such as how to select the variation from the option set choices, disable sold out variation choices and/or select a default variation.
Displaying item options
This guide solely focuses on the basic use cases of displaying items. Be sure to check out the Square Online SDK in order to see the additional scenarios you will want to take into account.
An item will always have at least one and sometimes many variations. In order to buy an item or add it to cart the buyer will need to select a specific variation. This is trivial in the case where an item has a single variation. Choosing from many variations requires selecting from an item’s options.
If the item was created with an option set from the Square Online dashboard, sellers can select the type of renderer format they want to use for an option set which you can choose to follow which can be radio, dropdown, or color.
Depending on how an item was setup in the catalog there are two ways that an item’s data will be formatted.
Items with flat variations
A flat variation is when a buyer needs to make a single choice to pick which variation they want. Items with flat variations will not contain an item_options property, but will contain a name property.
If your flat variation was created with an option set, an item_option_name, and renderer property are included on each. In addition, if the option set renderer is color, there will be a color property (in hex format) on each flat variation.
For an item that only has a single variation, the name will be Regular if a variation was not configured. You’ll likely choose to exclude showing any UI in this default scenario.
Here is a basic example taking the above logic into account:
{% if item.item_options is empty and ((item.variations)|length > 1 or item.variations.0.name != "Regular") %}
<div class="options">
{% if item.variations.0.renderer == "dropdown" %}
<select name="variation">
<option value="" selected>Select one{% if item.variations.0.item_option_name is defined %} ({{item.variations.0.item_option_name}}){% endif %}</option>
{% for variation in item.variations %}
<option value="{{ variation.id }}">
{{ variation.name }} - {{ variation|variation_display_price }}
</option>
{% endfor %}
</select>
{% endif %}
{% if (item.variations.0.renderer is not defined) or (item.variations.0.renderer == "radio") or (item.variations.0.renderer == "color") %}
<fieldset>
<legend>Select one{% if item.variations.0.item_option_name is defined %} ({{item.variations.0.item_option_name}}){% endif %}</legend>
{% for variation in item.variations %}
<label>
<input type="radio" name="variation" value="{{ variation.id }}">
<span>
{% if variation.renderer == "color" %}
<div style="height: 15px; width: 15px; display: inline-block; background-color: {{ variation.color }}"></div>
{% endif %}
{{ variation.name }} - {{ variation|variation_display_price }}
</span>
</label>
{% endfor %}
</fieldset>
{% endif %}
</div>
{% endif %}
If you are more familiar with the site’s item catalog and know what the variations represent then you can display the variation choice in another way. For example as tiles:
<div class="item-variations">
{% for variation in item.variations %}
<div
class="variation-tile"
onclick="selectVariation('{{ variation.id }}')"
style="cursor:pointer;"
>
<span class="variation-name">{{ variation.name }}</span>
<span class="variation-price">{{ variation|variation_display_price }}</span>
</div>
{% endfor %}
</select>
Items with multiple options
Sometimes an item’s variations are composed of multiple options. In this case a buyer needs to make multiple choices in order to identify a single variation to buy/add to cart. You can tell you are in this situation if the item_options property exists on an item.
Each item option will contain the renderer property to let you know which format to follow should you choose. It will also have a choices array which contains all the choices for that particular item option. If the renderer is color, there will also be a colors array which matches up a color (in hex format) 1:1 with the choices array.
Also note, unlike the flat variations, the variations will not include name, item_option_name, or renderer.
Here is an example of an item option:
// item.item_options[0]
{
"choices": [
"Red",
"Yellow",
"Blue",
"Green"
],
"colors": [
"#ff0000",
"#ffff00",
"#0000ff",
"#008000"
],
"id": "7YKSUS556XMD22P5HYIVB3P7",
"name": "Color",
"ordinal": 0,
"renderer": "color"
}
Here is a basic example taking the above logic into account:
{% if item.item_options is not empty %}
{% for option in item.item_options %}
{% if option.renderer == "dropdown" %}
<select name="variation">
<option value="" selected>{{ option.name }}</option>
{% for choice in option.choices %}
<option value="{{choice }}" data-option-id="{{ option.id }}">
{{ choice }}
</option>
{% endfor %}
</select>
{% endif %}
{% if (option.renderer == "radio") or (option.renderer == "color") %}
<fieldset>
<legend>{{ option.name }}</legend>
{% for choice in option.choices %}
<label>
<input
type="radio"
name="choice-{{ option.id }}"
value="{{ choice }}"
data-option-id="{{ option.id }}"
>
<span>
{% if option.renderer == "color" %}
<div style="height: 15px; width: 15px; display: inline-block; background-color: {{ option.colors[loop.index0] }}"></div>
{% endif %}
{{ choice }}
</span>
</label>
{% endfor %}
</fieldset>
{% endif %}
{% endfor %}
{% endif %}
Alternatively, you may choose to just display the raw variations array on the item resource. On each object in the variations array there will be an item_option_values array that contains the option choices that represent that particular varation.
// item.variations[0].item_option_values
{
"7YKSUS556XMD22P5HYIVB3P7": {
"name": "Color",
"choice": "Red",
"color": "#ff0000"
},
"FPWZK5NMPZSUJ6V2SKYMYKS7": {
"name": "Size",
"choice": "Small"
},
"V4ZLC5E7ZIRJQHBKQVSXITGU": {
"name": "Variant",
"choice": "Home"
}
}
Modifiers
Modifiers allow buyers to customize an item with modifications or custom text. Examples of modifiers are toppings on a pizza or a message to be engraved on jewelery. Modifiers can be free or have an additional charge.
Modifiers are usually displayed with checkbox (CHOICE or GIFT_WRAP types) or text (TEXT or GIFT_MESSAGE types) inputs.
An item contains a modifier_lists array, which in turn can contain a modifiers array if it’s a checkbox type.
For checkbox types, the modifiers can also have hidden, sold_out, and/or selected_by_default properties.
{% for modifier_list in item.modifier_lists %}
<h3>{{ modifier_list.name }}</h3>
{% if modifier_list.type == "CHOICE" or modifier_list.type == "GIFT_WRAP" %}
{% for modifier in modifier_list.modifiers %}
{% if modifier.hidden != true %}
<label>
<input
type="checkbox"
{% if modifier.sold_out %}
disabled
{% endif %}
{% if modifier.selected_by_default %}
checked
{% endif %}
name="modifiers-{{ modifier_list.id }}"
value="{{ modifier.id }}"
/>
{{ modifier.name }}
</label>
{% endif %}
{% endfor %}
{% endif %}
{% if modifier_list.type == "TEXT" or modifier_list.type == "GIFT_MESSAGE" %}
<input
type="text"
name="modifiers-{{ modifier_list.id }}"
/>
{% endif %}
{% endfor %}
Images
Item images are served from the Square Online CDN and can be resized to fit your use case. To display an item’s images do this:
{% if item.images is not empty %}
{% for image in item.images %}
<img src="{{ image.absolute_url }}" />
{% endfor %}
{% endif %}
If you want to display an image resized to a specific width you can use the image_width filter:
<img src="{{ item.images[0]|image_width(200) }}" />
We recommend using srcset and sizes filters to allow the browser to pick the best image size to display:
{% set image_sizes = [559, 862, 580, 580, 600] %}
<img
{{ item.images[0].absolute_url|srcset }}
{{ image_sizes|sizes }}
src="{{ item.images[0].absolute_url }}"
/>
This outputs the following HTML:
<img
srcset="https://cdn-domain/path-to-image.jpeg?width=80 80w, https://cdn-domain/path-to-image.jpeg?width=160 160w, https://cdn-domain/path-to-image.jpeg?width=320 320w, https://cdn-domain/path-to-image.jpeg?width=640 640w, https://cdn-domain/path-to-image.jpeg?width=1280 1280w"
sizes="(max-width: 599px) 559px,(max-width: 839px) 862px,(max-width: 1199px) 580px,(max-width: 1599px) 580px,600px"
src="https://cdn-domain/path-to-image.jpeg"
/>
See also: