Shopify integration (Debut theme)

This guide covers adding customizable products to a Shopify store by integrating jQuery File Uploader to allow product customizations. We’ll use image processing operations to render resized image previews of your customized Shopify products.

We are using the Debut “vintage” theme in this guide. If you want to use the new Dawn theme, check the latest version of Shopify guide.

Shopify is an eCommerce platform that allows you to build online stores. However, you can add static item images only for your items. Uploadcare can help you create custom print sweatshirts, mugs with a logo, etc.

Specifically, we’ll be building a product page for a customizable poster print:

A user uploads an image of a future poster and will see a product preview updated in real-time. We have added a condition that if the user hasn’t selected an image, he will not be able to add the poster to the cart.

Let’s get started.

Before we begin

Make a Shopify account

If you don’t have one yet, create a Shopify account. It’s free for 14 days. We’ll go with the Debut theme (this is a “vintage” theme, so the templates for it are different for other themes), but you can pick anyone you like. 🦄

Create an Uploadcare account

Same here: if you aren’t with us yet, sign up. Once you have an account, navigate to your Dashboard to create a new Project or discover API keys for an existing one. To go through the steps of this guide, you will need the Public API Key, which tells Uploadcare which project your file uploads should go to.

All files added by users will be stored in Uploadcare storage. You can view them in the Dashboard on the File tab.

Step 1. Setting up the product

Navigate to the Shopify admin panel to create your product. Go to the Products section and hit the Add product button. Fill out all the necessary fields such as product name, description, price, etc. Now, let’s use Shopify’s built-in uploader to upload a product image.

Click Add media from URL and upload a poster template image from a URL or you can upload a picture directly.

Note that the product image must have a transparent area, which will be “filled” with the loaded image.

Fill in the inventory to add the item to the cart later. Also, make sure that Product Status is set to Active to appear in the store. Click Save to apply the changes.

Adding tags

Add a customizable tag to the Tags field. If the product doesn’t have a customizable tag, the widget will not add to it. Click Save to apply the changes.

Disable the image zoom effect

You’ll also need to disable the image zoom effect for the uploaded product pictures to ensure our customized products will work correctly. Go to the Online store → Theme → Сustomize. Instead of Home at the top of the page, select a Product. Hit Product pages in the sidebar and uncheck Enable image zoom. This way, Shopify won’t interfere with our upcoming image resize feature.

Disable cart notification

Go to the Online store → Theme → Сustomize. Instead of Home at the top of the page, select a Product, and hit Product pages in the sidebar. Hit at the bottom of the sidebar Theme settings and uncheck Show notification when item is added to cart.

We’ve just added a product to your shop! 🚀 Now, let’s make it customizable.

Step 2. Adding the uploading widget

Now, we’ll need some prints to customize. Your users will upload them, so we need to add the uploading widget by including the Uploadcare library.

Shopify allows modifying themes, so let’s add some code. It’s pretty simple: go to the Online store, hit Themes, Customize, and select Edit code in the menu on the top of the page. Create a new file in the Snippets section. Name it uploadcare-settings.liquid, and add the uploader <script> element followed by another element containing your public API key:

1
<script charset="utf-8" src="https://ucarecdn.com/libs/widget/3.x/uploadcare.full.min.js"></script>
2
<script>
3
  UPLOADCARE_PUBLIC_KEY = "YOUR_PUBLIC_KEY";
4
</script>

Add another snippet named uploadcare-fields.liquid. We’ll be adding an <input> element that’ll become the uploader button. Put the following lines in the snippet:

1
<p class="cart-attribute__field uploader-dawn">
2
  <input
3
    id="uploader"
4
    type="hidden"
5
    data-images-only="true"
6
    data-crop="5:7"
7
    role="uploadcare-uploader"
8
    name="properties[Upload]"
9
  />
10
</p>

As you see, our <input> comes with some attributes. Here’s what they do:

• data-images-only tells the uploading widget to accept images only. See more about the images-only option.
• data-crop defines the aspect ratio of the uploading widget crop option. Here we enable image cropping in the uploader with data-crop="5:7". In this case, 5:7 represents the ratio of the transparent area in the product image template. It may be different for your product.
• name="properties[Upload]" link the Uploader with a custom property named Upload. As a result, a CDN URL of the uploaded file will be saved on Shopify’s end and attached to the order. We’ll access it from within the Cart and other pages.

Add the following lines to the theme.liquid file placed in the Layout section right before the closing </head> tag:

1
{% if template == 'product' %}
2
    {% include 'uploadcare-settings' %}
3
{% endif %}

Discover the product-template.liquid file under the Sections category, find the <form> element, and put the following somewhere within it:

1
{% if product.tags contains 'customizable' %}
2
  {% include 'uploadcare-fields' %}
3
{% endif %}

We’re using the if statement to render the uploader only on products that have been tagged as customizable.

In this example, we decided to put the snippet right before the variants selector dropdown like in the screenshot below:

There you go! You’ve just added the uploading widget to your product page. Users can now add their prints; our next step will show them a poster preview.

Step 3. Live product preview

Add settings that will allow us to preview our product to be generated once an image has been uploaded. We can accomplish that using some JavaScript and jQuery File Uploader API reference.

Create a new file in the Snippets section. Name it uploadcare-customizable-product.liquid, and add the <script>:

1
<script>
2
// Get widget reference
3
var widget = uploadcare.Widget("[role=uploadcare-uploader]");
4
// Get product image element
5
var productImage = document.querySelector(".product-featured-media");
6
// Get "buy now" button element
7
var buyNowBtn = document.querySelector(".shopify-payment-button__button");
8
// Get "add to cart" button element
9
var addToCartBtn = document.querySelector(".product-form__cart-submit");
10
11
// Disable "add to cart" and "buy now" buttons
12
buyNowBtn.disabled = true;
13
addToCartBtn.disabled = true;
14
15
// This fires once a file is uploaded
16
widget.onUploadComplete(function (fileInfo) {
17
  // We take CDN URL of uploaded image and set it as CSS background
18
	// of the product image adjusting the position and size
19
 productImage.style.background = "url(" + uploadedImage + "-/preview/" + ")";
20
  productImage.style.backgroundSize = "53% 50%";
21
  productImage.style.backgroundPosition = "48% 37%";
22
  productImage.style.backgroundRepeat = "no-repeat";
23
24
	// Enable "add to cart" and "buy now" once image uploaded
25
  buyNowBtn.disabled = false;
26
  addToCartBtn.disabled = false;
27
});
28
</script>

Note that the class names of the elements in your theme may be different. Use developer tools to find the actual selectors in your theme. Also, the values of the backgroundSize and backgroundPosition parameters need to be adjusted to your product image and the actual position and size of the transparent area.

Add this snippet to product-template.liquid. It’s better to place it at the bottom before the schema section:

1
{% if product.tags contains 'customizable' %}
2
  {% include 'uploadcare-customizable-product' %}
3
{% endif %}

Step 4. Preview in the cart

We stored CDN URLs of uploaded images in a dedicated property and can render previews of customized products on the Cart page. In cart-template.liquid find the cart image wrapper. In the Debut theme it looks like this:

1
<div class="cart__image-wrapper">
2
	<img class="cart__image{% if item.image == null %} hide{% endif %}" src="{{ item | img_url: 'x190' }}" alt="{{ item.image.alt | escape }}" data-cart-item-image>
3
</div>

Replace it with the following lines:

1
<div class="cart__image-wrapper">
2
	{%- if item.properties.Upload != blank -%}
3
		<img class="custom-product-preview cart__image{% if item.image == null %} hide{% endif %}" src="{{ item.image | image_url }}" alt="{{ item.image.alt | escape }}" data-image-upload="{{ item.properties.Upload }}" data-cart-item-image>
4
	{%- else -%}
5
		<img class="cart__image{% if item.image == null %} hide{% endif %}" src="{{ item.image | image_url }}" alt="{{ item.image.alt | escape }}" data-cart-item-image>
6
	{%- endif -%}
7
</div>

As a result, if there’s a URL in the Upload property, Shopify will add it as a data attribute (data-image-upload) to the corresponding preview image. Also, it will add the custom-product-preview class to this image. To make use of this attribute, we need to add some JavaScript.

Create a new file in the Snippets section. Name it uploadcare-cart-preview.liquid, and add the <script>:

1
<script>
2
  var previews = document.querySelectorAll(".custom-product-preview");
3
  previews.forEach(function(preview) {
4
    var background = preview.getAttribute("data-image-upload");
5
    preview.style.background = "url(" + background + "-/preview/" + ")";
6
    preview.style.backgroundSize = "53% 50%";
7
    preview.style.backgroundPosition = "48% 37%";
8
    preview.style.backgroundRepeat = "no-repeat";
9
  });
10
</script>

The script will take all images of the custom-product-preview class and set the CDN URL from the data-image-upload attribute as a background — the same as we did on the product page.

You can also apply the same changes to Shopify email templates, for instance, to the order confirmation email (Store settings → Notifications → Order confirmation).

Results

If everything is correct, your product page should now look like this:

You should now see the uploaded image and custom product fields:

Conclusion

Yay! You have just created a customizable product. The flexibility of Uploadcare is now enhancing your Shopify store.