Skio Universal Plan Picker V2: Lit.JS Component Skio Universal Plan Picker V2: Lit.JS Component

Skio Universal Plan Picker V2: Lit.JS Component

christian christian

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 %}
 
Each parameter being passed to the component, such as `product`, `selectedVariant`, and `formId`, are used by the Skio component to both generate the UI display, as well as make changes to the "Add to cart" form on the page in order to apply the proper `selling_plan` value when the API call is made to add a product to the customer's cart.

 

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>
Once you've found this div, you can change the copy:
<div class="skio-group-title">
Buy once
</div>
This change will now show in the Skio element for all products.

Using Lit.JS, more sophisticated changes can be made, such as conditionally showing / hiding specific elements and copy based on criteria such as the product's handle, ID, selected variant, etc. For more information on the Lit.JS framework, see the Lit.JS documentation: https://lit.dev/docs/
 
 

Making changes to the functionality / Javascript

Changes can be made to the functionality / Javascript of the Skio Universal Plan Picker element by adding or changing the functions present in the assets/skio-plan-picker-component.js file.
 
For example, if you wanted to add a new function to add '(recommended)' at the end of the `defaultFrequency` selling plan option in the subscription frequency dropdown, this can be achieved by adding the following function to the assets/skio-plan-picker-component.js file:
 
checkDefaultFrequency(selling_plan_name) {
if (selling_plan_name.toLowerCase().includes(this.defaultFrequency.toLowerCase())) {
return selling_plan_name + ' (recommended)';
} else {
return selling_plan_name;
}
}
 
You would then be able to utilize this function by adding the necessary Lit.JS logic in the `render()` function call where the `option` elements are rendered, such as below:
 
<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>
 
For more information on the Lit.JS framework, see the Lit.JS documentation: https://lit.dev/docs/
 
 

Making changes to the CSS styling

All CSS styling for the Skio Universal Plan Picker element can be found in the assets/skio-plan-picker-component.js file, at the top of the file. Important to note is that the CSS is inside of the following variable:
 
const skioStyles
 
This is important because Lit.JS requires for CSS styling to be inside of this variable in order to apply the styling inside of the `#shadow-dom` that is created by the web component itself. Any attempts to add styling outside of this file may not work as expected.
 
For example, to change the border-radius on all elements with the class name of `skio-group-container--available`, the following change can be made within the component file:
 
Currently the file has:
.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;
}
change to:
.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;
}
 
Additional styling can also be added as needed, however please note that all new styling needs to be within the `skioStyles` variable, otherwise an error will occur.
 

Hide the "How do subscriptions work?" element

The details-modal (which appears if you hover the "How do subscriptions work?" text) can be hidden by commenting out the following lines:

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

Alternatively, Lit.js logic can be used to conditionally hide the element, example:
${ this.product.handle == 'dont-show-details' ? html`` : html`
<details class="skio-details">
...
</details>
` }
 

Add comment

Please sign in to leave a comment.