Shopify Theme Integration Guide

version 3.0.0

NOTE: Duplicate theme first. DO NOT directly edit the live theme.

TIP: Start and end of blocks of HelixPay code added to the theme is commented like this {% comment %} HelixPay Start {% endcomment %} to easily identify added and modified code.

  1. Add global assets

    Upload assets helixpay-global.js and helixpay.css and include them in the theme.liquid file. Include css file before the head closing tag and script before the body closing tag.

    {% comment %} HelixPay added line below {% endcomment %}
    {{ 'helixpay.css' | asset_url | stylesheet_tag }}
    
    {% comment %} HelixPay added line below {% endcomment %}
    <script src="https://preview.helixpay.ph/js/helixpay.js"></script>
    <script src="{{ 'helixpay-global.js' | asset_url }}"></script>
    
  2. Add recurrence selector in the product page

    Create snippet helixpay_recurrence_selector.liquid and include it on the product page. Copy contents of helixpay_recurrence_selector.liquid.

    Include the snippet inside {% form 'product' below variant selector and above Add to Cart button. Apply necessary styling to match the theme (you can modify markup of helixpay_recurrence_selector.liquid and modify classes in helixpay.css).

    {% form 'product' %}
        {% comment %} Variant selector here {% endcomment %}
    
        {% comment %} HelixPay Start {% endcomment %}
        {%- render 'helixpay_recurrence_selector', product: product -%}
        {% comment %} HelixPay End {% endcomment %}
    
        {% comment %} Add to cart button here {% endcomment %}
    {% endform %}
    

    NOTE: if selector is shown in a dynamically added element like for example a modal or pop-up, call the function HelixPay.initMultipleInputsForRecurrence with 1st param of initial selected recurrence code (nullable) and the modal element to initialize the selector JS.

    // HelixPay Start
    if (HelixPay && HelixPay.initMultipleInputsForRecurrence) {
      HelixPay.initMultipleInputsForRecurrence(null, modalElement);
    }
    // HelixPay End
    
  3. Handle subscription price discount display in product page

    Look for code that displays product price. Wrap existing code in <span class="default-theme-price">. Duplicate the span and change attributes into <span class="helixpay-price" data-price="{{ current_variant.price }}">. In helixpay-price, adjust code to display the discounted style.

    On the helixpay-price element. Change display conditions to always display the discounted style. Change compare_at_price to <span class="recurrence-undiscounted-price" data-money-format="{{ price | money }}"></span> then change previous price to <span class="recurrence-discounted-price" data-money-format="{{ shop.money_format }}" style="display:none"></span>. You can also use shop.money_with_currency_format depending on theme style.

    {% comment %} HelixPay added line below {% endcomment %}
    <span class="default-theme-price">
        {% comment %} Existing theme code starts here {% endcomment %}
        ...
        {% comment %} Existing theme code ends here {% endcomment %}
        {% comment %} HelixPay added line below {% endcomment %}
    </span>
    {% comment %} HelixPay Start {% endcomment %}
    <span class="helixpay-price" data-price="{{ current_variant.price }}" style="display:none">
        ...
        <span
          class="recurrence-undiscounted-price"
          data-money-format="{{ shop.money_format }}"
        >
            {{ current_variant.price | money }}
        </span>
        <span
          class="recurrence-discounted-price"
          data-money-format="{{ shop.money_format }}"
        ></span>
        ...
    </span>
    {% comment %} HelixPay End {% endcomment %}
    

    NOTE: to handle product variant update on your theme script file, call the function HelixPay.onVariantUpdate() on each update instances with new product variant as parameter.

    // HelixPay Start
    if (HelixPay && HelixPay.onVariantUpdate) {
      HelixPay.onVariantUpdate(variant);
    }
    // HelixPay End
    
  4. Display selected recurrence in cart page

    Find cart item liquid file. Adjust display of cart item properties. Check if property Frequency is displayed.

    NOTE: some themes display the cart in a drawer or a pop up. Adjust code to handle dynamic JS when necessary. You can also skip this step if property Frequency is already displayed.

     <div>
        {%- if item.properties.Frequency != blank -%}
          {{ item.properties.Frequency }}
        {%- else -%}
          Single Order
        {%- endif -%}
     </div>
    
  5. Add price discount display in cart items

    Create snippet helixpay_pricing.liquid and include it on each of the cart line item display. Copy contents of helixpay_pricing.liquid.

    {% comment %} HelixPay Start {% endcomment %}
    {%- if item.properties._recurrenceDiscountValue != blank or if item.properties._recurrenceDiscountValue != '0'  -%}
      {% liquid
        if item.original_line_price != item.final_line_price
          assign used_price = item.final_price
          assign used_line_price = item.final_line_price
        else
          assign used_price = item.original_price
          assign used_line_price = item.original_line_price
        endif
    
        if item.properties._computationType and item.properties._computationType == '2'
          if item.properties.Recurrence == 'quarterly'
            assign used_price = used_price | times: 3
          else if item.properties.Recurrence == 'annually'
            assign used_price = used_price | times: 12
          endif
        endif
      
        if item.properties._recurrenceDiscountType == '1'
          assign discount_amount = item.properties._recurrenceDiscountValue | times: 100
        else if item.properties._recurrenceDiscountType == '2' and discount_percent > 0
          assign discount_percent = item.properties._recurrenceDiscountValue | divided_by: 100.0
          assign discount_amount = used_price | times: discount_percent
        else
          assign discount_amount = 0
        endif
      
        assign recurrence_discounted_price = used_price | minus: discount_amount
      
        assign recurrence_discounted_line_price = recurrence_discounted_price | times: item.quantity
        
        assign applied_price = recurrence_discounted_price
      %}  
     
     {% comment %} HelixPay: line below should not be duplicated across multiple screen views {% endcomment %}
     <input type="hidden" class="helixpay-cart-line-price" value="{{recurrence_discounted_line_price}}">
    {%- else -%}
     {% comment %} HelixPay: added line below. should not be duplicated across multiple screen views {% endcomment %}
     <input type="hidden" class="helixpay-cart-line-price" value="{{item.original_line_price}}">
    {%- endif -%}
    {% comment %} HelixPay End {% endcomment %}
    

    Then display each item price with additional conditions from helixpay_pricing.liquid. Apply necessary styling to match the theme.

    {%- if item.properties._recurrenceDiscountValue != blank and if item.properties._recurrenceDiscountValue != '0'  -%}
    

    NOTE: Update your theme's scripts for dynamic display of cart items prices. You can use its properties to recalculate on their prices. (e.g.)

    Discount Type:
    1: Fixed Value Discount
    2: Percentage Discount

    Discount Value: (10)
    1: PHP 10.00
    2: 10%

  6. Display price discount display in cart subtotal

    Find where cart.total_price is displayed. Add the class orig-subtotal and data attributes data-orig-subtotal="{{ cart.total_price }}" data-display="inline" to the direct element it is displayed. Add another element beside it for helixpay-subtotal (Follow guide below). Add class helixpay-subtotal-wrapper to their parent element.

    Before:

     {{ 'cart.general.subtotal' | t }}
    <span class="money">{{ cart.total_price | money }}</span>
    

    After:

    {% comment %} HelixPay added class helixpay-subtotal-wrapper {% endcomment %}
    <div class="helixpay-subtotal-wrapper">
      {{ 'cart.general.subtotal' | t }} {% comment %} HelixPay Start {% endcomment
      %}
      <span
        class="money orig-subtotal"
        data-orig-subtotal="{{ cart.original_total_price }}"
        data-display="inline"
      >
        {{ cart.total_price | money }}
      </span>
      <span
        class="money helixpay-subtotal"
        data-money-format="{{ shop.money_format }}"
        style="display: none"
      ></span>
      {% comment %} HelixPay End {% endcomment %}
    </div>
    

    NOTE: Make sure the code below is added only once on each cart item with the respective cart line price.

    <input type="hidden" class="helixpay-cart-line-price" value="{{recurrence_discounted_line_price}}">
    

    or

    <input type="hidden" class="helixpay-cart-line-price" value="{{item.original_line_price}}">
    

    Then call the HelixPay.initHelixpaySubtotal() function on the first load of the cart page wrapped in DOMContentLoaded listener. Also call the HelixPay.initHelixpaySubtotal() function in every dynamic load of subtotal.

    // HelixPay Start
    document.addEventListener("DOMContentLoaded", function () {
      if (HelixPay && HelixPay.initHelixpaySubtotal) {
        HelixPay.initHelixpaySubtotal();
      }
    });
    // HelixPay End
    

    When handling a dynamic cart page or cart drawer where the subtotal is changed by javascript, call the HelixPay.initHelixpaySubtotal() function in every dynamic load of subtotal. You might also need to update the data attribute data-orig-subtotal value.

    // Inside function that dynamically loads subtotal
    // HelixPay Start
    
    var origSubtotal = document.querySelector('orig-subtotal');
    
    if (origSubtotal) {
      origSubtotal.dataset.origSubtotal = NEWSUBTOTAL;
    }
    
    if (HelixPay && HelixPay.initHelixpaySubtotal) {
        HelixPay.initHelixpaySubtotal();
    }
    // HelixPay End
    
  7. Integrate smart checkout button

    Smart because it redirects accordingly. Comment existing checkout button then add new checkout button. Make sure the data-cart-form-id value is the cart form id used to checkout products. You may need to add the id if the form doesn't have one. Apply appropriate styling to match the theme.

    {% comment %} HelixPay Start {% endcomment %}
    <button
      type="button"
      class="helixpay-checkout"
      data-shop-domain="{{ shop.permanent_domain }}"
      data-cart-form-id="cart"
    >
      Checkout
    </button>
    {% comment %} HelixPay End {% endcomment %}
    
  8. Integrate dynamic checkout button (Buy it Now button)

    Look for form | payment_button in liquid files. Wrap it in a div with class shopifyDynamicCheckoutArea then add the div beside it with class helixpayDynamicCheckoutArea. make sure the value of data-product-form-id is the Add to Cart form id. Apply styling to the Subscribe Now button to match the theme.

    {% comment %} HelixPay Start {% endcomment %}
    <div class="shopifyDynamicCheckoutArea" style="display: none">
      {{ form | payment_button }}
    </div>
    <div class="helixpayDynamicCheckoutArea" style="display: none">
      <button
        type="button"
        class="helixpayDynamicCheckoutButton"
        data-shop-domain="{{ shop.domain }}"
        data-product-form-id="{{ product_form_id }}"
      >
        Subscribe Now
      </button>
    </div>
    {% comment %} HelixPay End {% endcomment %}
    
  9. Setup Subscription Tooltip

    You need to request first for helixpay merchant id and update helixpay-global.js config variable.

    ...
    window.HelixPay.setCustomConfig({
      merchantID: null,
      baseApi: 'https://api.helixpay.ph',
    });
    ...
    

    For tooltip styles, default set to theme color scheme settings.colors_accent_2 for background. If need to change update on helixpay_recurrence_selector.liquid file through inline css.

    <div class="hsw-tooltip" 
      style="background-color:{{ settings.colors_accent_2 }};color:        
      #fff">
        <div class="hsw-header">
          <span></span>
          <button type="button" class="close-hsw" aria-label="Close">
            <span aria-hidden="true">&times;</span>
          </button>
        </div>
        <p></p>
        <a href="https://helixpay.ph/" target="_blank">Powered by
          <img 
            src="https://cdn.helixpay.ph/images/assets/helixpay_logo_white_horizontal.png?" 
            alt="Helixpay">
        </a>
    </div>
    

Whatโ€™s Next