Skio Universal Plan Picker V2: Lit.JS Component

Outline

• Overview
• How does it work?
• Usage when including the Skio component in the theme codebase
• Making changes to the component's layout / HTML contents
• Making changes to the functionality / Javascript
• Making changes to the CSS styling
• Hide the "How do subscriptions work?" element

Overview

This documentation is specifically for assisting existing merchants / stores who have the following file in their theme codebase:

• assets/skio-plan-picker-component.js

Important: if you do not have this theme file already in your Shopify Theme codebase, you may have the V1 of the Skio Universal Plan Picker element, which you can confirm by checking for this file in your Shopify Theme codebase: snippets/skio-plan-picker.liquid .

If you do have the V1 of the Skio Universal Plan Picker element, please refer to our Skio Universal Plan Picker V1 documentation: https://help.skio.com/hc/en-us/articles/21060337103771-Skio-Universal-Plan-Picker-V1-Liquid-JS-CSS-support

How does it work?

V2 of the Skio Universal Plan Picker utilizes the Lit.JS framework to generate a native web component that controls all data and UI display of Skio subscription selling plans related to any product on your store that is set up for subscriptions in Skio.

All layout, functionality, and styling for the Skio Universal Plan Picker element can be found in the assets/skio-plan-picker-component.js file in your Shopify Theme codebase.

Usage when including the Skio component in the theme codebase

The Skio component usage notes can be found at the top of the assets/skio-plan-picker-component.js file. The standard usage is as follows:

{% assign skioSellingPlanGroups = product.selling_plan_groups | where: 'app_id', 'SKIO' %}
{% if skioSellingPlanGroups.size > 0 %}
  <skio-plan-picker
    product='{{ product | json | escape }}'
    selectedVariant='{{ product.selected_or_first_available_variant | json | escape }}'
    formId='{{ product_form_id }}'
    currency='{{ cart.currency.iso_code }}'
    useVariantInputClickEvents='false'
    variantInputSelector=''
  >
  </skio-plan-picker>
  <input type="hidden" aria-hidden="true" name="selling_plan" value="">
  <script src="{{ 'skio-plan-picker-component.js' | asset_url }}" type="module"></script>
{% endif %}

There are additional parameters that can be passed to the Skio component, which can be found in the `properties` static variable inside the Skio component file. For example, you can pass the `startSubscription` parameter to the element as shown below, which will ensure that "Subscription" is the selected option on page-load rather than One-time:

{% assign skioSellingPlanGroups = product.selling_plan_groups | where: 'app_id', 'SKIO' %}
{% if skioSellingPlanGroups.size > 0 %}
  <skio-plan-picker
    product='{{ product | json | escape }}'
    selectedVariant='{{ product.selected_or_first_available_variant | json | escape }}'
    formId='{{ product_form_id }}'
    currency='{{ cart.currency.iso_code }}'
    useVariantInputClickEvents='false'
    variantInputSelector=''
    startSubscription
  >
  </skio-plan-picker>
  <input type="hidden" aria-hidden="true" name="selling_plan" value="">
  <script src="{{ 'skio-plan-picker-component.js' | asset_url }}" type="module"></script>
{% endif %}

Important parameters:

• product : passes all product-related data directly to the Skio element in order to render data
• selectedVariant : indicates which variant of the product is selected on page load
• formId : indicates the ID of the HTML `form` being used for sending the "Add to cart" API call to Shopify, for use in injecting the `selling_plan` input into the form
• currency : sets the currency to be used by the Skio element
• language : takes in a language identifier such as "en-US" to indicate the language to be used when formatting currency values
• useVariantInputClickEvents : when passed as 'true', this will cause the Skio element to look for an `input` element containing the currently selected variant's ID value in order to update the currently selected variant in the Skio component
• variantInputSelector : query selector for the `input` element containing the currently selected variant's ID value

Other useful parameters:

• startSubscription : sets 'Subscription' as the selected purchase option on initial render, rather than Onetime (unless the product can only be sold as a subscription, in which case 'Subscription' is always the default)
• subscriptionFirst : places the 'Subscription' option above 'One-time'
• productHandle : in place of passing the `product` parameter, passing `productHandle` will trigger an API call to the Shopify API to get the product's JSON data
• externalPriceSelector : query selector for an external price element, which the Skio component will then update the innerHTML of with the currently-selected price
• externalPriceSelectorWithCurrency : query selector for an external price element, which the Skio component will then update the innerHTML of with the currently-selected price with the currency at the front, ex. USD .
• defaultFrequency : allows you to pass the name of a specific selling plan (such as "Every 1 month"), which the frequency dropdown-menu will then default to selecting on initial render
• showAddToCartButton : will render an "Add to cart" button when passed, which when clicked will make a "/cart/add" API call to Shopify for the selected variant and purchase option; defaults to quantity 1

Important to note:

In order for the Skio component to recognize when the selected variant on the page is changed by user input, either of the following needs to occur:

1. The `useVariantInputClickEvents` parameter needs to be passed as 'true', and the  `variantInputSelector` parameter needs to pass in the query selector of the `input[name="id"]` element that contains the currently selected variant's ID. This `input` element must also emit a "changed" event when its value is changed.
   
   
2. The following event dispatch needs to be added within the theme code wherever the change from one variant to another is occurring within a Javascript function (usually a "updateHistoryState" function):
   
   

   document.dispatchEvent( new CustomEvent("variantChanged", { detail: { variantId: variant.id } }) );

   This event dispatch will tell the Skio component that the variant has been changed, as well as the ID value of the newly-selected variant.

Making changes to the component's layout / HTML contents

Changes can be made to the layout / HTML of the Skio Universal Plan Picker element in a number of ways using Lit.JS, however all rendered HTML elements / layout is controlled in the `render()` function.

For example, to change the copy in the Skio element from "One-time" for onetime purchases to "Buy Once", go into the `render()` function and find the following div:

<div class="skio-group-title">
  One-time
</div>

<div class="skio-group-title">
  Buy once
</div>

checkDefaultFrequency(selling_plan_name) {
  if (selling_plan_name.toLowerCase().includes(this.defaultFrequency.toLowerCase())) {
    return selling_plan_name + ' (recommended)';
  } else {
    return selling_plan_name;
  }
}

<option value="${ selling_plan.id }" ?selected=${group.selected_selling_plan == selling_plan }>
  ${group.name == 'Subscription' ? `Deliver ${this.checkDefaultFrequency(selling_plan.name.toLowerCase()) }` : `${this.checkDefaultFrequency(selling_plan.name) }`}
</option>

const skioStyles

.skio-group-container--available {
  display: block;
  position: relative;
  box-shadow: 005pxrgba(23, 24, 24, 0.05), 01px2pxrgba(0, 0, 0, 0.07);
  border-radius: 5px;
  border-width: 1px;
  border-color: transparent;
  border-style: solid;
  transition: border-color0.2sease;
}

.skio-group-container--available {
  display: block;
  position: relative;
  box-shadow: 005pxrgba(23, 24, 24, 0.05), 01px2pxrgba(0, 0, 0, 0.07);
  border-radius: 0px;
  border-width: 1px;
  border-color: transparent;
  border-style: solid;
  transition: border-color0.2sease;
}

<!-- <details class="skio-details">
  ...
</details> -->

${ this.product.handle == 'dont-show-details' ? html`` : html`
  <details class="skio-details">
    ...
  </details>
` }