Getting started
This guide will help you get started with the <cylindo-viewer> web component.
If you are using an e-commerce platform (WooCommerce, Shopify, Magento...), please refer to its integration guide instead.
Installation​
You can register the viewer on your page by adding the following script tag to your <head>
<link rel="preconnect" href="https://content.cylindo.com" crossorigin />
<script
type="module"
src="https://viewer-cdn.cylindo.com/v1/index.mjs"
async
></script>
Usage​
The viewer can now be used declaratively in any HTML page or integrated into any framework.
<cylindo-viewer customer-id="5034" code="63116214"></cylindo-viewer>
You can edit the code in the live editor above. Try changing the customer-id and code attributes to one of your own products.
You can find your Customer ID (Settings -> Account number) and products' Code on Cylindo CMS
Remote Configuration​
The remote-config attribute provides a way to manage your viewer's settings through the CMS, without having to modify any code directly.
This approach can be particularly useful if you want to adjust the appearance or functionality of the viewer without engaging in technical details.
For a comprehensive guide on this process, follow these instructions.
<cylindo-viewer customer-id="5098" code="WHISTLER SOFA BED" remote-config="k2hctc08" ></cylindo-viewer>
Thumbnail Bar​
The thumbnail bar is a customizable component that provides a visual navigation aid for your viewer configuration. It can easily be included and tailored to fit your specific needs, enhancing the user experience by offering quick access to different views.
Follow the detailed instructions to learn how to integrate the thumbnail bar into your viewer.
Best practices​
The minimum setup above is great for getting started, however there are still a few things we can do to improve the user experience of your website:
Preloading​
The viewer is loaded asynchronously to not impact your website's performance. This means that the viewer-code may not be loaded on first paint.
Specifying an <img slot="placeholder" ...> can help the viewer to render something even before it is registered.
<cylindo-viewer>
<img
slot="placeholder"
src="http://content.cylindo.com/api/v2/5034/products/63116214/default.webp"
/>
</cylindo-viewer>
A placeholder image is also great for SEO, as it is visible to search engines, even before javascript execution.
You do not need to specify customer-id and code on the viewer when using a placeholder image as the viewer can extrapolate this information from the image url.
Calculable dimensions​
It is recommended to specify both width and height or a width and aspect-ratio, to let the browser know the size of the viewer before resources are loaded.
This is because the viewer cannot know the size of the image until they are loaded, which can cause the page to jump around. See importance of Cumulative Layout Shift (CLS)
We recommend to ensure that the viewer has a minimum height of 345px on desktop browsers to prevent the controls overlapping.
If you wish to support browsers that don't support the aspect-ratio css properties, add this css variable to cylindo-viewer:
--legacy-browser-aspect-ratio: 4 / 3;
Combined with the placeholder image, a complete best-practice example looks like this:
HTML​
<cylindo-viewer>
<img
slot="placeholder"
src="http://content.cylindo.com/api/v2/5034/products/63116214/default.web"
/>
</cylindo-viewer>
With CSS​
cylindo-viewer {
display: block;
aspect-ratio: 4 / 3;
}
cylindo-viewer img[slot="placeholder"] {
object-fit: contain;
width: 100%;
height: 100%;
}