@bva/recommendations
v0.0.10
Published
JS recommendations widget using Shopify native recommendations API
Downloads
36
Readme
Recommendations
JS wrapper around Shopify's Recommendation API that provides an easy to use interface to get HTML on the page.
Installation
If you're using Node you can install this package in the following ways:
Yarn
yarn add @bva/recommendationsNPM
npm install @bva/recommendationsIf you're not using Yarn or NPM, see below in Usage for more info on adding the minified file directly to your projects.
Usage
Recommendations is a simple widget using Shopify's native recommendations API that can be included on any Shopify website. Check out how easy it is to implement using ES6 modules:
import Recommendations from '@bva/recommendations';
const config = {
productId: 10590155084,
limit: 5,
};
const recs = new Recommendations(config);
recs.initialize();If you're not using NPM and ES6 import/export syntax, you can also grab the minified dist/recommendations.min.js and include it in your HTML before your custom JS. Its equally simple:
<body>
<div data-recommendations-insertion></div>
<script src="recommendations.min.js"></script>
<script>
var config = {
productId: 10590155084,
limit: 6
};
var recs = new Shopify.Recommendations(config);
recs.initialize();
</script>Perfect for your new slate projects
Configuration Object
A configuration is required when initializing your Recommendations instance and uses the following properties:
- productId - The ID of the product recommendations will be based off of
- hiddenTag - (default:
"recommendations::hide") Tag that hides specific products - insertion - (default:
"[data-recommendations-insertion]") HTML element that the reviews will be inserted into - limit - (default:
4)The amount of products that will be displayed (max 10) - template - (see below for default) A function that returns a string of HTML for a single product
Product Id
The Product ID is what will be used in the request to Shopify to figure out which products to display. It must be passed to your instance upon instantiation via 1 of the following methods.
HTML (Recommended Method)
Add the data attribute data-recommendations-main-product-id to your insertion element and add the product id as a value to that. This is the recommended method because you'll usually have access to the Product ID via liquid. It is much easier for a future developer to read this and understand what's happening.
<div data-recommendations-insertion data-recommendations-main-product-id="1234567890"></div>In Liquid
<div data-recommendations-insertion data-recommendations-main-product-id="{{ product.id }}"></div>JS
Pass the productId value along with your configuration object.
const config = {
productId: 1234567890,
limit: 5,
};
const recs = Shopify.Recommendations(config);
recs.initialize();In Liquid
<script>
Shopify.customVariables = {
productId: {{ product.id }}
};
</script>const config = {
productId: window.Shopify.customVariables.productId,
limit: 5,
};
...Template
A template is the HTML that is displayed for each product in the recommendations widget. The template config option is a function that takes 1 argument product, which is the product object returned from Shopify. The return vaue should be a string of HTML. The product argument has access to all imformation that would usually be accessible when pulling product data from Shopify.
The default template looks like:
function(product) {
return(`
<div class="recommendation__product" data-recommendations-product-id="${product.id}">
<a href="${product.url}" class="recommendation__wrapper">
<div class="recommendation__product-image-wrapper">
<img class="recommendation__product-image" src="${product.featured_image}" alt="${product_title} image" />
</div>
<div class="recommendation__product-details">
<h3 class="recommendation__product-title">${product_title}</h3>
<span class="recommendation__product-price">${product_price}</span>
</div>
</a>
</div>
`);
}Methods
initialize
Initializes a Recommendations instance and adds it to the page.
const recs = Shopify.Recommendations({ variantId: 1234567890 });
recs.initialize();reinitialize
Needs documentation
uninitialize
Needs documentation
updateOptions
Needs documentation
Events
recommendations.initialized: Fires when a recommendation instance is initialized. The callback you will find the product data inevent.detail.dataand the current instance inevent.detail.context.
Changelog
To see any recent changes view the CHANGELOG.