JS Doc
Current version: 1.1.0
Our Find Similar widget finds visually similar products and presents the results in a pop up layout. There are 2 components in the widget:
- Product details of the query image
- Visually similar product results generated by us. The list of products can be presented in a carousel or scroll box format. The default display is carousel.
Setup
You can directly place our script into your page header to access this widget:
<script type="text/javascript" src="//cdn.visenze.com/visearch/dist/js/components/Recommendation-1.1.0.bundle.js"></script>
Quick start
This quick start guide demonstrates how to load and initialize our ViSenze You May Also Like widget. This guide uses basic options to initialize the widget. However, you can also customize advanced options if you want to do so.
Setup the Widget
2 simple steps to integrate our You May Also Like widget:
Place the element
You should place the "Find Similar" button somewhere in your HTML body and assign an ID to it.
In our example, we name the element ID as vs-findsimilar
which will be used in the initialization of the widget in javascript.
You can find this source code in src/findsimilar/index.html
:
<body>
<div class="container">
...
<div class="vs-product-details">
<div class="title" style="display: inline-block;">Product name</div>
<div id="vs-findsimilar" style="display: inline-block;"></div>
<div class="vs-price">$99.00</div>
</div>
...
</div>
</body>
Initialize the widget
To get real data working in the example, you need to initialize the following code snippet. The customizable parameter object contains three sub-objects:
vsSettings: parameters to customize the search options
displaySettings: parameters for presentation
findSimilarOpts: parameters of the product
You can find the following code snippet in src/js/findsimilar.js
:
var vsSettings = {
appKey: 'APP_KEY',
fl: ["im_url", "price", "title", "product_url", 'brand', 'discount_price'],
limit: 15,
detection: "all"
};
var displaySettings = {
showQueryProduct: false,
hasScrollBox: false,
modalSize: 80,
cardsToShow: 4,
cardsToScroll: 4
}
var findSimilarOpts = {
imName: "IM_NAME",
productDetails: {
productUrl: 'product_url',
heading: 'title',
label: 'brand',
price: "price",
discountPrice: "discount_price"
},
addToCartHoverIcon: true,
addToCartStaticIcon: false
}
var options = {
vsSettings: vsSettings,
displaySettings: displaySettings,
findSimilarOpts: findSimilarOpts
};
$(document).ready(function() {
FindSimilar(document.getElementById("vs-findsimilar"), options);
});
Please update the following parameters in the code snippet according to your own app configurations:
Parameters | Explanation |
---|---|
APP_KEY |
This is the credential to call our API. You should be able to find these in the Integration/Client-side Integration section on dashboard. Detailed explanation on key pairs can be found here. |
SCHEMA_NAME |
The corresponding schema field values to be linked. The value of the schema should be the one that is being configured in your schema setting. You can find the full list in the Your Images -> Schema section on dashboard. Detailed explanation on schema configuration can be found here. |
Run the example
The example project is managed by gulp.
If you don't have gulp, please follow the getting started guide to install it.
The following command will start a server and run the example at http://localhost:8080
:
// Remember to configure before starting or else there will be error
gulp start
If the parameters are configured correctly, you should be able to see the widget working like this:
Advanced options
Customize product card layout
You might want to customize the layout of the product card to fit the design of your site.
productDetails
is an object that maps the corresponding card details to search results.
The image below illustrates a visual representation of the product card and its details.
You can pass the field schema value to the placeholder in order for the correct value to be rendered.
Note that the widget will not render the product detail field unless it is set.
Example: Configure productDetails
as shown below in order to display the product title first and product brand below that:
productDetails: {
label: "title",
heading: "brand",
description: "",
price: "price",
discountPrice: "discount_price"
}
Customize product card style
Of special interest is the ability to customize the style of the widget so it matches the look and feel of your website. The widget is made of up multiple JavaScript elements which can be modified by adding CSS styling to your site.
You can find the sample css files to customize the look for the example in the directory src/styles
.
Here is sample css that customizes the product card layout as shown above:
/*Product details*/
.vs-product-details {
color: #333333;
font-size: 14px;
padding-top: 5px;
padding-bottom: 5px;
font-family: 'Roboto-Regular', sans-serif;
}
.vs-product-details .vs-ellipsis {
-webkit-line-clamp: 2;
-webkit-box-orient: vertical;
text-overflow: ellipsis;
overflow: hidden;
}
.vs-product-details .vs-elli-one {
-webkit-line-clamp: 1;
}
.vs-product-details .vs-product-label {
height: 22px;
font-family: 'Roboto-Bold', sans-serif;
}
.vs-product-details .vs-product-heading {
position: relative;
line-height: 1.4em;
height: 40px;
}
.vs-product-details .vs-product-description {
font-size: 12px;
height: 35px;
font-family: 'Roboto-Light', sans-serif;
color: #777777;
}
.vs-product-details .vs-product-price {
display: inline-block;
margin-top: 5px;
margin-bottom: 5px;
margin-right: 10px;
}
.vs-product-details .vs-strikethrough {
text-decoration: line-through;
color: #999999;
font-weight: 400;
}
.vs-product-details .vs-product-discount-price {
display: inline-block;
color: #d03535;
font-weight: 400;
}
.vs-product-details .vs-product-more_details {
color: white;
text-align: center;
background-color: black;
line-height: 30px;
}
.vs-product-details .vs-product-more_details:hover {
color: white;
text-decoration: none !important;
background-color: #676767;
}
.vs-product-details .vs-cart-static {
height: 20px;
width: 20px;
margin-left: 15%;
cursor: pointer;
opacity: 0.7;
float: right;
}
.vs-product-details .vs-cart-static:hover {
opacity: 1;
}
.vs-product-details .vs-cart-icon {
height: 100%;
width: 100%;
}
Reference
vsSettings
Key | Type | Description |
---|---|---|
appKey | string | (compulsory) app key |
fl | array | (compulsory) list of schema values returned from the API. The list needs to match the schema set in the API. |
fq | object | (optional) list of pre-defined filters to filter your search results. e.g. fq: ['country:singapore', 'brand:nike'] . Detailed explanation of the filters can be found here. |
limit | integer | (optional) the number of search results returned. Default set to 15. |
findSimilarOpts
Key | Type | Description |
---|---|---|
imName | string | (compulsory) the index id of the product to recommend on. This should be the same im_name used for datafeed indexing. |
productDetails | object | (compulsory) result in widget mapped to the product card display. See below for product card layout. Each of the card elements will be matched to the response result. Widget will not render the card element if the key is not given. |
productContainer | html element | (optional) area for additional customization on top of the default layout provided. Recommended to have simple additional buttons. |
onProductContainerClicked | function | (optional) method to be executed when the productContainer is clicked. |
fsTitle | string | (optional) title of the widget to be displayed. Default is set as "Find Similar". |
hasHoverCartIcon | boolean | (optional) show the "Add to cart" icon when image is hovered. Default set to true. See an example. |
hasStaticCartIcon | boolean | (optional) show the "Add to cart" icon permanently below the image. Default set to false. See an example. |
onAddToCartClicked | function | (optional) method to be executed when "Add to cart" icon is clicked. |
cartText | string | (optional) text to represent "Add to cart". Default set to "Add to cart". It will always show to the right of the icon. |
afterCartText | string | (optional) text to represent "Add to cart" after clicked. Default set to "Added". It will always show to the right of the icon. |
findSimilarText | string | (optional) add a text description on the right of the "Find Similar" icon. Default is empty. |
displaySettings
Key | Type | Description |
---|---|---|
hasQueryProduct | boolean | (optional) show the details of the query product. Default set to false. |
queryProductDetails | object / html components | (optional) the display of the query product. Has the option to use the product card layout or a customized html component. |
hasScrollBox | boolean | (optional) results to show in a scroll box layout if true, else results in carousel format. Default to false. |
modalSize | integer | (optional) size percentage of the popup modal. Default set to 60%. |
cardsToShow | integer | (optional) number of results in a single strip. Default set to 3. |
cardsToScroll | integer | (optional) number of results in a single scroll. Default set to 3. |
hasInfiniteScroll | boolean | (optional) enable infinite scroll. Default set to false. |
isDraggable | boolean | (optional) enable mouse drag within browser. Default set to false. |
hasDots | boolean | (optional) show the dots at the bottom as page indicator. Default set to true. |
nextArrowSrc | string | (optional) url to image source for the next arrow. |
prevArrowSrc | string | (optional) url to image source for the previous arrow page indicator. Default set to true. |
hasAutoplay | boolean | (optional) enable auto scrolling of results. Default set to false. |
autoplaySpeed | integer | (optional) delay time in terms of milliseconds between each scroll. Default set to 3000ms. |
currencySymbol | string | (optional) currency symbol before prices and discount_prices. Default set to '$'. |
errorMessage | string | (optional) message to be displayed when an error occurs. Default set to "System busy. Please try again later". |