Legacy Theme Installation

Manually add Keystone Product Options to themes that don't support Shopify 2.0 app blocks.

Overview

If your store uses a legacy (1.0) theme or a custom theme that doesn't support app blocks, you can still use Keystone Product Options by manually adding a Liquid snippet to your theme files.

Advanced Setup

This guide requires editing theme code. If you're not comfortable editing Liquid files, consider upgrading to a Shopify 2.0 theme or contact our support team for assistance.

When You Need This

Use manual installation if:

• Your theme doesn't show app blocks in the theme customizer
• You're using a vintage/legacy Shopify theme
• You have a custom-built theme without 2.0 support
• The standard app block installation doesn't work

Installation Steps

Step 1: Create the Snippet File

1. From your Shopify admin, go to Online Store > Themes
2. Click the ⋯ (three dots) on your active theme
3. Select Edit code
4. In the left sidebar, find the Snippets folder
5. Click Add a new snippet
6. Name it keystone-product-options (without the .liquid extension – Shopify adds it automatically)
7. Click Create snippet

Step 2: Add the Snippet Code

Paste the following code into the new snippet file:

{% doc %}
  @description
  Keystone Product Options - Manual Installation Snippet (Product Pages Only)

  Installation:
  - For product pages: Add to your product template (e.g., in main-product.liquid or sections/product-template.liquid)
  - Place where you want options to appear (typically near or before the add-to-cart button)

  @example
  {% render 'keystone-product-options', product: product %}

  @param {object} product - Product object context
{% enddoc %}

{% comment %} Load custom styles {% endcomment %}
{%- assign custom_styles = shop.metafields.shopify_custom_options.css_styles.value -%}
{%- if custom_styles != blank -%}
  <style id="shopify-custom-options-styles">{{ custom_styles }}</style>
{%- endif -%}

{% comment %} Preload OptionsForm for faster loading {% endcomment %}
<link rel="modulepreload" href="https://api.product-options.key-stone.app/api/public/scripts/key-product-options-form.js" crossorigin="anonymous">

{% comment %} Load storefront script {% endcomment %}
<script src="https://api.product-options.key-stone.app/api/public/scripts/key-product-options-storefront.js" type="module" crossorigin="anonymous"></script>

{% comment %} Render options container {% endcomment %}
{% if product %}
  <div id="key_options_block"
       data-product-id="{{ product.id }}"
       data-product-title="{{ product.title | escape }}"
       data-product-price="{{ product.price | divided_by: 100.0 }}"
       data-product-tags="{% if product.tags.size > 0 %}{{ product.tags | join: ',' }}{% endif %}"
       data-customer-logged-in="{% if customer %}true{% else %}false{% endif %}"
       data-customer-tags="{% if customer.tags.size > 0 %}{{ customer.tags | join: ',' }}{% endif %}"
       data-shop-domain="{{ shop.permanent_domain }}"></div>
{% endif %}

8. Click Save

Step 3: Add the Snippet to Your Product Template

Now you need to render the snippet on your product pages:

1. In the theme code editor, find your product template file. Common locations include:

   • sections/product-template.liquid
   • templates/product.liquid
   • sections/main-product.liquid
   • snippets/product-form.liquid

2. Locate where you want the options to appear (typically above or near the Add to Cart button)

3. Add this line where you want the options form to display:

{% render 'keystone-product-options', product: product %}

4. Click Save

Placement Recommendation

For the best user experience, place the render tag:

• Above the quantity selector
• Above or near the Add to Cart button
• After the product variant selectors (if any)

This ensures customers see and select options before adding products to their cart.

Finding the Right Location

Common Theme Structures

Vintage Themes (Brooklyn, Debut, Supply, etc.) Look in sections/product-template.liquid for a section that includes the product form.

Custom Themes Search for add-to-cart or AddToCart in your theme files to find the product form location.

Example Placement

Here's an example of where to place the snippet in a typical product template:

<div class="product-form">
  <!-- Product variant selectors above -->
  {% for option in product.options %}
    ...
  {% endfor %}

  <!-- Add Keystone Product Options here -->
  {% render 'keystone-product-options', product: product %}

  <!-- Quantity and Add to Cart below -->
  <div class="quantity-selector">
    ...
  </div>
  <button type="submit" class="add-to-cart">
    Add to Cart
  </button>
</div>

Verifying the Installation

After adding the snippet:

1. Save all modified files
2. Open your online store in a new browser tab
3. Navigate to a product that has an option set assigned
4. Confirm the options display correctly on the product page

No Options Showing?

If options don't appear, verify that:

• The snippet file was saved correctly
• The render tag is in the correct template file
• The product variable is available in the template (try to test)
• The product has an option set assigned (learn more)
• Clear your browser cache and try again

Important Notes

Snippet Must Be Inside Product Context

The snippet requires the product object to function. Ensure it's placed within a template or section where product is defined.

Testing Product Context

If you're unsure whether product is available, temporarily add \{\{ product.title \}\} to your template. If it displays the product name, the snippet will work there.

Outside the Product Form

Unlike some apps, the Keystone options snippet does not need to be inside the <form> element. It can be placed anywhere on the product page where the product object is accessible.

One Installation Per Page

Only include the render tag once per product page. Multiple inclusions may cause duplicate options to appear.

Upgrading to App Blocks

If you later upgrade to a Shopify 2.0 theme:

1. Remove the render tag from your old template
2. Delete the keystone-product-options.liquid snippet (optional)
3. Follow the standard app block installation guide

Recommendation

Shopify 2.0 themes provide a better experience with easier customization and automatic updates. Consider upgrading when possible.

Getting Help

If you encounter issues with manual installation:

• Email support: support@key-stone.app
• Include your theme name and any error messages
• Share screenshots of where you placed the code

Our team can help identify the correct template file for your specific theme.

Next Steps

Once installation is complete:

1. Create option sets for your products
2. Assign products to option sets
3. Customize the appearance to match your brand