Printess pluginless Shopify integration

This document describes a way how to integrate the Printess Editor for personalized prodcuts 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:

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

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

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".

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

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.

2) Product configuration

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

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.

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)

Open the code editor.

Download the printess-assets.zip and upload the 3 contained files to shopify (printesseditor.css, printesseditor.js, printessshopspecific.js)

Inside the "Add new asset" dialog, click on "Add file"

Do this for all 3 files inside the uploads folder (printesseditor.css, printesseditor.js, printessshopspecific.js)

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 (snippets folder).

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 (snippets folder).

Save the changes.
It is required to create a default value. For that, open the file settings_data.json (snippets folder) and paste the content into the „current“ json node:

Replace the token value with your own shop token. Save the changes on the 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:

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 whichdisplays the „Add to basket“ button on products that have no printess templateName 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 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 Variable Block“ from the file „CodeBlocks.txt“ (snippets folder) right below the external file imports:

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 Customize Button 1 Block“ that can be found inside the file „CodeBlocks.txt“ (snippets folder) right under the themes „buy_buttons“ block.

Paste the contents of the „Printess Customize Button 2 Block“ that can be found inside the file „CodeBlocks.txt“ (snippets folder) right above the

{%- when 'rating' -%}

statement:

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 Modify Button Block 1“ hat can be found inside the attached „CodeBlocks.txt“ right after the loop definition.

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. The thumbnail can be found inside the „cart-item__media“ block. Paste the code that can be found in „Printess Thumbnail Block 1“ inside the file „CodeBlocks.txt“ (snippets folder) right below the „cart-item__media“ block.

Right after the inserted Printess „Thumbnail Block 1“, the theme is testing if the line item image exists.

You have to find the matching {% endif %} block and paste the contents of the „Printess Thumbnail Block 2“ inside the file „CodeBlocks.txt“ (snippets folder) right underneath.

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 makign 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 Edit Button Block 1" which can be found at the file „CodeBlocks.txt“ (snippets folder) atop of the for loop {%- for property in item.properties -%}

The contents of the "Printess Edit Button Block 2" which can be found inside the file „CodeBlocks.txt“ (snippets folder) needs to be copied directly below the closing tag of the property for loop "{%- endfor -%}".

The last thing left to do, is loading the javascript helpers that have been uploaded to the assets section and initializing them.

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

Paste the „Printess Download Files Block“ inside the file „CodeBlocks.txt“ (snippets folder) 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.

Then scroll down to the bottom of the page. Search for the Body end tag "</body>" and paste the contents of the "Printess Initialization Block" inside the file „CodeBlocks.txt“ (snippets folder) above the end tag.

4) Webhook registration

The last thing left to do is registering the order webhook so that the printess system is notified about new orders and can start producing the PDF’s of your personalized products. For this you will need to contact the printess support 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.

There, open the notification settings.

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

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

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

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.

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 isnide the Printess account portal.

5) Hiding printess specific product settings from the buyer side

Newer versions of this pluginless integration prefix their product properties (templateName, thumbnailUrl, productDefinitionId etc) with an underscore. This is the standard way for shopify themes to hide these from being displayed on the buyer side. Pluginless soure codes that have been downloaded before mid January 2022 did not prefix their properties and therefore will display additional product properties inside the shopping basket and the order overview. The backend of the order webhook that is used for the pluginless version supports both versions, with and without underscore.

For older pluginless versions, open the file assets->printessshopspecific.js and find lines 25-27 and lines 44-46 that are responsible for writing these properties to the shopify basket items:

And prefix the keys (printessSaveToken, printessThumbnail and printessProductDefinitionId) with an underscore.

For most themes that honor shopify standard behaviours this is all needed to hide these properties from the buyer side for each product that is added to the basket from now on. In rare occassions, where themes do not honor these, you will have to find the code positions that are responsible for rendering these properties and manually prevent all properties that start with _printess from being rendered. On the Shopify standard theme Dawn, they can be found in the source editor in the following files: cart-notification-product.liquid, main-cart-items.liquid, main-order.liquid and cart-drawer.liquid.
In all files, the sourcecode for rendering the product properties looks similar. At first, a variable is assigned that contains the first character of the property name. In a second step, it is tested if this first character is an underscore. If not, it is not rendered.

Above screenshot is taken from the file main-cart-items.liquid. All the listed liquid files listed above have the same sourcecode regarding these properties. In order to hide all properties that start with an underscore, just copy the sourcecode from the orignal theme shown above and use that.
{%- for property in item.properties -%} {%- assign property_first_char = property.first | slice: 0 -%} {%- if property.last != blank and property_first_char != '_' -%} <div class="product-option"> <dt>{{ property.first }}: </dt> <dd> {%- if property.last contains '/uploads/' -%} <a href="{{ property.last }}" class="link" target="_blank"> {{ property.last | split: '/' | last }} </a> {%- else -%} {{ property.last }} {%- endif -%} </dd> </div> {%- endif -%} {%- endfor -%}

For hiding printess properties only, this code can be modified to hide all properties that start with printess, replace the line
{%- assign property_first_char = property.first | slice: 0 -%}
With this line:
{%- assign startsWithPrintess = property.first | slice: 0,8 -%}

or for _printess with this line:
{%- assign startsWithPrintess = property.first | slice: 0,9 -%}

Then rewrite the check for underscore with the one for printess / _printess:

{%- if startsWithPrintess != 'printess' -%}
or _printess:
{%- if startsWithPrintess != '_printess' -%}

6) 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.

Click on Develop apps on the top right side.

Click on Create an app

Provide a name for the app.

Now click on "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'

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

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

Click on Install

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.

The token should start with shpat_. Now provide us with this token.

7) Output settings

It is possible to specify the format of the output file (pdf, png jpeg) as well as the output resolution in dpi (Dots per inch). To specify these output settings on product level, go to your shops administration and open your shop settings.

Open the metafield settings for products and create 2 new meta definitions for output format and output dpi.

Open the metafield settings for products and create 2 new meta definitions for output format and output dpi.

The settings for output format are:

	Name	Value
Name	Output Format
Namespace and key	printess.outputFormat
Description	The file output format (pdf, png, jpg)
Type	Single line text

The settings for output resolution are:

	Name	Value
Name	Output Resolution in DPI
Namespace and key	printess.dpi
Description	The file output resolution in dots per inch
Type	Single line text

Go back to the store administration and open the theme code editing as shown in "3) Theme configuration" and open the file main-product.liquid.
Copy the code block <!------------- Printess Variable Block2 -------------> that can be found in the attached file „CodeBlocks.txt“ and place it directly under the code block <!------------- Printess Variable Block -------------> that has been placed in step "3) Theme configuration".

Still inside the main-product.liquid file, search for <!------------- Printess Customize Button 2 Block -------------> and replace it with the latest (most up to date) <!------------- Printess Customize Button 2 Block -------------> that can be found inside the attached file „CodeBlocks.txt“

Now replace the file "printessshopspecific.js" that can be found inside the assets folder with the newest one available inside the printess-assets.zip package. Direct file link: printessshopspecific.js)

In case you need to have global settings instead of product specific ones, you need to add some entries to the settingsdata.json that can be found inside the "Config" folder. Search vor the entry printess_shoptoken. Put a new line after that line and add the following entrys:
"printess_outputdpi": "300", "printess_outputformat": "pdf",

To output png or jpg images instead of pdf's replace "pdf" with "png" or "jpg"