How to resolve issues with the 1P Subscription App Block in non-default Shopify themes?

[Jacqui]

This document is meant for merchants and theme partners who are encountering issues with the 1P Subscription App Block. It specifically applies to those who are not using a default version of an OS 2.0 theme created by Shopify. This includes custom themes, third-party themes, and modified versions of Shopify's themes.

This document will explain how the various components of our app block integrate with the theme, what elements are required for our app block to work, and how you can update your theme to work with our app block. You will learn:

1. Identifying Shopify sections
2. Find the variant input 
3. Find the product form
4. Hide the app block in the quick buy modal 

Requirements

1. You've installed an Online Store 2.0 theme, such as Dawn, that uses JSON templates and supports app blocks.

If you don’t know your theme architecture version (whether or not your theme is an Online Store 2.0 theme), you can follow these steps to find out. 

Don’t forget to make a copy of your theme before making any modifications. This will ensure that you can always revert back to a previous version if needed.

Identifying Shopify sections

To ensure that the 1P Subscriptions app block functions properly, the theme needs to have two specific implementations. These implementations allow the app block to effectively search and retrieve the necessary elements and data from the product page’s structure.

1. Sections, as per the theme requirements.
2. Sections that are independent of one another as described in Shopify sections best practices. For example, the main product section is independent of other sections like the featured product, and only contains data and elements that are related to the main product. 

Determine use of sections

To determine if your theme is using sections, verify that your main product or featured product is wrapped with one of these tags using the developer tools. The tag should start with shopify-section-.

<section id="shopify-section-${sectionId}" ...>

Determine use of independent sections

To determine if your theme is using independent sections, you can test in the Online Store Theme Editor that the product elements on the product page can be removed, added and reordered one independently of the other(s).

For example, a featured product can be removed without removing the main product, and vice versa. 

What to do if your theme doesn’t support sections

If you do not find this shopify section in your theme, then the main product or featured product is not using sections. You will need to implement them as sections that support app blocks to be compatible with the 1P Subscriptions app block.

Here is the documentation to help you achieve that. This requires technical knowledge.

What to do if your theme doesn’t support independent sections

If your sections are not independent of one another, you will need to split them into individual sections, each with app block support.

Here is the documentation to help you achieve that. This requires technical knowledge. 

Finding the product form

In order for the 1P Subscriptions App Block to successfully find the product forms required for the functionality of the app block, the theme must use the action="/cart/add" on the section’s main product form.

The app block will use the forms for 2 things:

1. Appending the selling_plan input to the forms, this input is required to get the correct subscriptions data in the cart and in checkout
2. Find and listen to the variant input. This is required for the app block to determine which selling plans are available for the selected variant. 

Determine use of the action="/cart/add" attribute

To determine if your theme is using the action="/cart/add" attribute, use the developer tools to find the product form. You can hover over form elements in the product section, like the add to cart buttons, or variant options.
Best practice is for forms to use forms tags, so searching for the form keyword in the elements can work too. 

What to do if your theme doesn’t use the action="/cart/add" attribute

There are two ways to solve this issue

1. Use the Liquid form tag, with the ‘product’ attribute, this form tag automatically uses the action="/cart/add" attribute. If your theme is already using this tag, it may be explicitly defining the action attribute, simply remove this definition. 
2. Find the product forms you want to use the app block on, in your theme and manually add the  action="/cart/add" attribute.
   this.shopifySection.querySelectorAll('[action="/cart/add"]');

You’ll also want to make sure that any code in your theme that expects the form to use the previous action is modified to expect the new action attribute. 

Finding the variant input

We search for an input or a select element with the attribute name=”id”.

These are the most common elements used for variant selection. Additionally, them being named id is expected, since this is the field the form expects for the variant id.

This means, in order for your theme to be compatible with the app block, the variant id will need to be stored in one of these element types. 

Determine if your theme uses a hidden input or select for the variant value

To determine if your theme uses a select or input, use the developer tools Elements tab to search for the attribute name="id". Alternatively, you can find the add to cart forms, and check that this input or select element exists as one of its children. 

What to do if your theme doesn’t use a supported variant element 

You can follow this documentation to implement variant selection. The key section is creating a master variant selector using the input or select tag, with the attribute name=”id”.

Listening to the variant change

In order to display the correct selling plans associated with the selected variant, the app block listens for the variant change.

First, the app block will need to find the form, then it will listen to this form for an onchange event to be emitted when the variant changes. It’s important that the value of the variant input is updated to the currently selected variant id before the event is emitted, since this is the value the app block will use to determine which selling plans are displayed.  

Determine if the form is emitting an event when the variant changes

To determine if the form is emitting an event when the variant changes, you can: 

1. Add this code snippet to the main-product.liquid file in your theme code. (This is what the file is called in most themes, but can be named slightly differently depending on the theme.)
2. Save and click “Preview store”
3. Navigate to a product that has variants
4. Open the developer tools console tab
5. Change the variant

If you see the text, “The form is emitting an event.”, then this means the app block can listen to the variant change.
There are some exceptions where the app block may be able to listen to the variant change, but it still can’t identify the correct variant id.

For example, your theme may trigger a form change before the variant id is updated. In this case, the app block would be using the previously selected variant id to display the selling plans, causing unpredictable behaviors.

<script>

  document.addEventListener('DOMContentLoaded', () => {

    document.querySelectorAll('form').forEach((addToCartForm) => {

      addToCartForm.addEventListener('change', () => {

        console.log("The form is emitting an event.")

      })

    })

  })

</script>

What to do if your theme doesn’t emit an event when the variant changes

You will need to understand how your theme works and emit an event when the variant is updated in the correct javascript file. If the form does emit an event, but you are seeing selling plans that belong to the previously selected variant, you need to make sure the form event is emitted when the variant id is updated. The solution for this incompatibility is different for every theme.

Hiding the Subscriptions Widget in the quick buy Modal

You may have noticed that the subscriptions widget appears in the quick buy modal of your theme. We currently do not support this feature, however, due to the way the quick buy modal is implemented in your theme, it may be visible.

This can be fixed by adding custom CSS to the theme. 

Determine if the 1P Subscriptions widget is visible in the quick buy modal

To determine if the 1P Subscriptions widget is visible in the quick buy modal, you will need to follow these steps.
 

1. Add the subscriptions app block to a product, on the product page in the online store editor. Here’s a tutorial on how to do that. 
2. Enable quick buy or quick buy feature for your theme, or for a specific section. It depends on how your theme implements this feature. 
3. For a product with variants and that is linked to a selling plan, click the “Choose options” button or quick buy button. 
4. Check to see if the subscriptions widget is visible.

What to do if the 1P Subscriptions widget is visible in the quick buy modal

If the 1P subscriptions widget is visible in the quick buy modal, you can hide it by adding some custom CSS to your theme. Note that if you choose not to hide the widget, the 1P subscriptions app does not support the quick buy feature, therefore it will be visible, but non-functional.

To add custom CSS to your theme, follow these steps. 

1. Find the modal id or class – you can do this by hovering over an open quick buy modal with the dev tools.
   
2. Add one of these custom CSS snippets to your theme (tutorial)

If you’re using the modal classname, use this snippet

.<modal-classname> .shopify_subscriptions_app_block {

display: none;
}



If you’re using the modal id, use this snippet



#<modal-id> .shopify_subscriptions_app_block {

display: none;

}

[shopaid]

Thanks for Sharing this article.