Shopify integration (Debut theme)

Before we begin

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. The key can be found either in the API keys.

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.

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.

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:

<script charset="utf-8" src="https://ucarecdn.com/libs/widget/3.x/uploadcare.full.min.js"></script>
<script>
  UPLOADCARE_PUBLIC_KEY = "YOUR_PUBLIC_KEY";
</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:

<p class="cart-attribute__field uploader-dawn">
  <input
    id="uploader"
    type="hidden"
    data-images-only="true"
    data-crop="5:7"
    role="uploadcare-uploader"
    name="properties[Upload]"
  />
</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:

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

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

{% if product.tags contains 'customizable' %}
  {% include 'uploadcare-fields' %}
{% 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 the jQuery widget API.

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

<script>
// Get widget reference
var widget = uploadcare.Widget("[role=uploadcare-uploader]");
// Get product image element
var productImage = document.querySelector(".product-featured-media");
// Get "buy now" button element
var buyNowBtn = document.querySelector(".shopify-payment-button__button");
// Get "add to cart" button element
var addToCartBtn = document.querySelector(".product-form__cart-submit");

// Disable "add to cart" and "buy now" buttons
buyNowBtn.disabled = true;
addToCartBtn.disabled = true;

// This fires once a file is uploaded
widget.onUploadComplete(function (fileInfo) {
  // We take CDN URL of uploaded image and set it as CSS background
	// of the product image adjusting the position and size
 productImage.style.background = "url(" + uploadedImage + "-/preview/" + ")";
  productImage.style.backgroundSize = "53% 50%";
  productImage.style.backgroundPosition = "48% 37%";
  productImage.style.backgroundRepeat = "no-repeat";

	// Enable "add to cart" and "buy now" once image uploaded
  buyNowBtn.disabled = false;
  addToCartBtn.disabled = false;
});
</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:

{% if product.tags contains 'customizable' %}
  {% include 'uploadcare-customizable-product' %}
{% 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:

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

Replace it with the following lines:

<div class="cart__image-wrapper">
	{%- if item.properties.Upload != blank -%}
		<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>
	{%- else -%}
		<img class="cart__image{% if item.image == null %} hide{% endif %}" src="{{ item.image | image_url }}" alt="{{ item.image.alt | escape }}" data-cart-item-image>
	{%- endif -%}
</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>:

<script>
  var previews = document.querySelectorAll(".custom-product-preview");
  previews.forEach(function(preview) {
    var background = preview.getAttribute("data-image-upload");
    preview.style.background = "url(" + background + "-/preview/" + ")";
    preview.style.backgroundSize = "53% 50%";
    preview.style.backgroundPosition = "48% 37%";
    preview.style.backgroundRepeat = "no-repeat";
  });
</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.