Shopify Pluginless

This document describes a way on how to integrate the Printess Editor for personalized produts into your shopify shop without installing any kind of plugin. This method only relies on Shopify standard ways of product configuration and on small modifications of the shops frontend theme. The unmodified “Dawn” standard theme is used inside this documentation. Steps required might be slightly different on modified theme versions or on other themes.

1. Creation of required product meta fields

Before making any changes on our themes, we need a way to distinguish „normal“ shopify products from printess products. We also need a way to map a printess template to a specific shopify product. Shopify provides Metafields as a way to add custom configurations to its products. We will create one metafield called templateName that will be used to map a specific product to a published printess product.

Go into the administration interface of your shop and open the meta field configuration:

Location of the app and sales channel settings

Scroll down and find the „Metafields“ option. Select Products.

Location of the product specific meta field settings

Click on „Add definition“ to create a new form field definition.

Location of the Add definition button

You have to create one field for the printess template name. The name property is the display name that is shown within the product configuration. Use Printess Template Name as Value. “Namespace and key” is the value that is IMPORTANT for the integration. This is the key that will be used to access the value from within the frontend. Use “printess” as namespace and “templateName” as key. The final value that needs to be written to “Namespace and key” is “printess.templateName”. Its is important to use exactly this value. “Description” is the description that will be displayed inside the product configuration.

Values to enter:

Name: Printess Template Name Namespace and key: printess.templateName Description: The printess template name that should be used for this product

Select “Expose this metafield to Storefront API requests” and click on “Select content type”.

Location of the select content type setting

Use “Single line text” as type and click on “Save”.

Configured data type and save button location

Now, create a second meta data definition for the drop shipping configuration. This field contains the “Printess drop shipping product definition id”. The available ids (Product definitions) can be found inside your printess account portal under “Dropshippers”. Use “Dropshipping product definition id” for name and “printess.productDefinitionId” under “Namespace and key”. As description, add “(Integer value) -1: No dropshipping; 0: Use template settings; >0: Dropshipping product definition id”. Make sure that the value in “Namespace and key” is correct. Shopify prefills this value with wrong values. Casing is important!

The field value type has to be set to Integer.

Screenshot of the product definition id meta field configuration for drop shipping

By creating additional definitions for “printess.dpi” (integer) or “printess.outputformat” (single line text, supported values pdf, png, jpg) you can add additional options for controlling the output dpi and the file format of the produced files after an order.

2. Product configuration

Inside the shop configuration go to “Products” and open an existing one (or create a new one).

Location of product configuration

Inside the product configuration of the created ( / selected product), scroll down to the bottom where the meta fields section is located. Enter a name of an exsiting, published printess template.

Screenshot of meta field configuration for printess products. Use “-1” for “dropshipping product definition id” (Disable dropshipping) and click on “Save

3. Theme configuration

Go to the Administration interface of your shop and open the the theme editor (Online Store → Themes → Customize)

Location of the theme editing button

Open the code editor.

Location of the edit theme code menu entry

Download the 3 files printesseditor.css, printesseditor.js and printessshopspecific.js from the printess pluginless gist and upload all 3 to the shoppify theme assets:

Screenshot of the asset upload button

Inside the “Add new asset” dialog, click on “Add file

Screenshot of the upload asset dialog

You will need to provide the Printess “Shop- Token” to the editor. Instead of hard coding this token into the sourcecode, it will be added as a theme setting. The shop token can then be changed in certain situations later on. To create a new Theme setting, open the file settings_schema.json (config folder).

Location of the settings_schema.json

Scroll to the bottom of the file. The last line’s content should be a closing JSON array tag “]”. Add a new line on top and paste in the content of the file settings_schema.json

Screenshot of the modified settings_schema.json

Save the changes. It is mandatory to create a default value. For that, inside the theme code editor, open the file settings_data.json and paste the content of the settings_data.json into the „current“ json node:

Screenshot of the settings_data file

If you go back to the theme wysiwyg editor, and open the settings you should see the new printess setting at the bottom of the settings list:

Screenshot of the UI for the added shop token configuration

For printess products, the “Add to basket” button has to be replaced with a customize button. Go back to code editing and open the “Sections folder”. Open the file “main-product.liquid”. A switch needs to be added which displays the “Add to basket” button on products that have no printess.templateName property set and add a “Customize” button for products with a configured template name.

To make this work, some variables needs to be declared, that contain the templateName, some dropshipping Info, output info and the flag that says if the current product is a printess product.

At the top of the “main-product.liquid” file, you will find a “section” definition. The first few childs of the section node “<section”, are imports of external files. Copy the “Printess main-product.liquid variable block” block from the gist main-product-variable_block.liquid right below the external file imports:

Screenshot of the pasted variable block

Now you have to search for the “Add to basket button”. It is wrapped in a “buy_buttons” block that is used by the theme wysiwyg editor. Look out for:

{%- when ‘buy_buttons’ -%}

That whole buy buttons block ends with the definition of the “rating block”:

{%- when ‘rating’ -%}

You have to hide all content of the “buy_buttons” block into an if else switch that is hiding all contents for non printess products and showing the customize button instead for printess products.

Copy the contents of the Printess main-product.liquid show original add to cart button block right under the theme’s “buy_buttons” block:

Location where to put the Printess main-product.liquid show original add to cart button block

Copy the contents of the Printess main-product.liquid show printess add to cart button block right above the {%- when ‘rating’ -%} code block.

Location where to put the Printess main-product.liquid show printess add to cart button block

Save the file changes.

The next step is to add a customize button to your shopping cart. Open the file “main-cart-items.liquid”.

Inside the shopping basket view, the theme iterates through all shopping cart items and displays some additional information / controls like the thumbnail, product details, quantity selector etc. For printess products you will have to exchange the thumbnail and add the edit button to the product details section. Search for the loop that iterates through all products and paste the contents of the Printess main-cart-items.liquid variable block block right after the loop definition.

Location where to put the

This block reads the printess product specific settings from the cart line item and makes them available to the liquid theme code.

Now search for the code that is responsible for displaying the thumbnail and add a switch that hides the standard thumbnail and displays the printess thumbnail for printess products. The thumbnail can be found inside the “cart-item__media” block. Paste the code of the Printess main-cart-items.liquid thumbnail block 1 right below the “cart-item__media” block.

Location where to place the Printess main-cart-items.liquid thumbnail block 1

Right after the inserted Printess “Printess main-cart-items.liquid thumbnail block 1”, the theme is testing if the line item image exists.

Check for thumnails

You have to find the matching {% endif %} block and paste the contents of the Printess main-cart-items.liquid thumbnail block 2 right underneath.

Check for thumnails

Within the product details block, the theme displays all property values of the cart line item that has been added by any kind of shopify integration. For Printess prodcuts, this block should be hidden and replaced with an edit button that reopens the Printess Editor and allows making changes to designs that have been already added to the cart. Search for the foor loop that is iterating through all the cart line item properties and paste the contents of the Printess main-cart-items.liquid edit button block 1 atop of the for loop {%- for property in item.properties -%}

Location where to placer the cart button block

The contents of the Printess main-cart-items.liquid edit button block 2 needs to be copied directly below the closing tag of the property for loop {%- endfor -%}

Location where to placer the cart button 2 block

The last thing left to do, is making sure that the uploaded JavaScript and CSS files that have been uploaded to the assets section of the theme are loaded automatically on each page load.

Open the “theme.liquid” file inside the “Layout” folder.

Location of the theme.liquid file

Paste the contetnts of the Printess theme.liquid header block somewhere in the html header definition of the theme. We added it right at the top after the “meta data” that is specified by the original theme.

Screenshot of the pasted content of the Printess theme.liquid header block

Then scroll down to the bottom of the page. Search for the Body end tag “” and paste the contents of the Printess theme.liquid body block above the end tag.

Screenshot of the pasted content of the Printess theme.liquid body block

4. PDF Production (Webhook registration)

In order to notify the printess system about new orders so that it can start producing the PDF’s of your personalized products you need to register a webhook at the shopify webhook configuration. You will need to contact the printess support as first and ask for a order webhook key. After you have been provided with a key, you need to go to the “App and saleschannel settings” of your shop administration.

Location of the app and sales channels settings

There, open the notification settings.

Location of the notification channels

And scroll to the bottom where you will find the web hooks configuration.

Location of the web hook configuration

Click on “Create webhook” and select “Order creation” from the events and configure the format to be “JSON”:

Order creation web hook settings

Inside the url setting, use the following url: https://api.printess.com/shops/shopify/order/xxxxxxxxxxx You have to replace the “xxxxxxxxxxx” inside the url with the key that has been provided to you by the printess support. For Shopify Webhook API version select the current release version

Order creation web hook settings

Click on save. Now, shopify will display a “secret key” that is being used to sign shopify requests and that is being used to verify that the webhook call is really done by the shopify system.

location of the webhook secret key

Provide this key to the Printess support and wait until you got the ok that the key has been added to your account. This completes the printess integration. After ordering a printess product, you should see the order and the produced pdf inside the Printess account portal.

5. Fulfillment

In case your Printess account has fulfillments activated, we (Printess) need a shopify app token that is allowed to access and modify fulfillment information on your orders. You will need to create a private app inside your shop that has the following access scopes activated: ‘read_fulfillments’, ‘write_fulfillments’, ‘read_assigned_fulfillment_orders’, ‘write_assigned_fulfillment_orders’, ‘read_merchant_managed_fulfillment_orders’, ‘write_merchant_managed_fulfillment_orders

To create such a private app, head over to the apps “App and sales channel settings” inside the admin area of your shop.

Location of the App & Saleschannel settings

Click on Develop apps on the top right side.

Location of the develop apps button

Click on Create an app

Location of the create an app button

Provide a name for the app.

Screenshot of app settings dialog

Now click on “Configure Admin API scopes

Location of the Configure Admin API scopes

Select the following api scopes: ‘read_fulfillments’, ‘write_fulfillments’, ‘read_assigned_fulfillment_orders’, ‘write_assigned_fulfillment_orders’, ‘read_merchant_managed_fulfillment_orders’, ‘write_merchant_managed_fulfillment_orders

Location of the assigned fulfillment order scopes

Location of the fulfillment services api scopes

Merchant-managed fulfillment orders

Click on Save on the top right (bottom right) corner of the page.

Location of the save button

To receive an access token, the app needs to be installed on the current shop. Click on Install app on the top right corner.

Location of the install app button

Click on Install

Location of the install button

Shopify will now display the Admin API access token as well as the API key and secret key. In the Admin API access token section, click on reveal token once and copy it to your clipboard or write it down.

Screenshot of the token screen

The token should start with shpat_. Now provide the printess support with this token and the domain name of your shop.