Background
In this guide we will implement the Cylindo 360 HD Viewer into a webshop running the Magento platform.
Environment preparation
1. Install Magento platform
For this tutorial Cylindo’s customers should have the Adobe Commerce (Magento) platform installed in their servers.
If it is not already installed, it must be installed following the installation guide provided by Adobe on its official site.
For this example, we’ve installed Magento version 2.4.
2. Login into the admin panel of the Magento platform
3. Create a Configurable product
On the Admin sidebar, go to the Products option located under the Catalog menu.
Click the arrow button from the Add Product button of the upper-right corner and choose Configurable Product.
Fill the form with the product information, for this example we’re going to use the Emma Armchair product.
When all the information is filled, click on the Save button displayed in the button displayed in the upper-right corner.
For more configuration options our suggestion is to read the official documentation.
4. When the product is created, we’re ready to add configurations. For this example, we’re going to add options to change the Upholstery and the Legs of the Emma Armchair product.
By default, Magento creates simple products with unique SKUs for each of the 9 possible combinations, this is to cover every possible combination of variations.
It is also worth mentioning that by default, the product name and SKU values for each variation is assigned based on the attribute value and either the parent product name or SKU.
To create the configurations, we first need to select the created product and click the Edit option displayed in the last column of the products table.
To create the configurations, we first need to select the created product and click the Edit option displayed in the last column of the products table.
In the modal window displayed select the option Create New Attribute
Each attribute represents a Cylindo feature, and the options of each attribute are the options of the Cylindo products.
So here we’ve to fill the attribute option with the Cylindo information. For the Default label and Attribute code we’re going to use the feature Name and Code respectively and for each option we’ll use the Option code to fill the Admin field and the Option name to set the Default Store View field. The below two images show the configuration for the Upholstery.
And these 2 images show the configuration for the Legs.
When both Attributes (Features) are ready the next step is to save the and select them from the attributes list to continue with the process to create the possible combinations.
Not all times the features and options will be able to create a combination for each case, so the next form allows us to define which attributes can be used together in the configuration panel. For this example, all the options should be selected, but it could change according to the product configuration.
The next form requests an image for each configuration, Cylindo customers could set a fallback image to ensure something is displayed in case the 360 viewer fails while loading, but for this example we’re skipping this and we’re going directly to the next menu.
The last form shows an overview of the simple products that Magento is creating for each combination. In this last form when the Generate Products button is clicked the combinations are created and they’re displayed in the Configurations section of the Configurable Product.
This image shows the resultant list, please notice that some information related to the product quantity is still missing.
In case more guidance is needed to fill the items that were not configured in this tutorial such as prices for each simple product, quantity, etc., the complete information can be found here.
Once the configurable product is saved the resultant simple products are listed in the products list as displayed in the next image.
HD 360 Viewer implementation.
Introduction
Once we’ve the structure of our configurable product ready in Magento, the next step is to make sure that the information that we’ve stored in the Magento2 platform and the Cylindo CMS is synchronized.
It means that the same codes for the SKU, Attributes and Options of Magento need to exist in the Cylindo CMS.
To validate this, we first need to know and understand how the product structure is in both platforms, Magento and Cylindo.
In Cylindo, a SKU is named Product, and it is identified by its Product Code. The product attributes are named features and the options of the attributes are also named options in the Cylindo platform.
It is also worth mentioning that in Magento 2 a Configurableproduct is a complex product created by Simple products, each variation is a Simple product that has its own SKU, description, price, etc.
In Cylindo, the variations of a configurable product are handled in a different way. In Cylindo only one Product is created, and the variations are requested through the Features and Options not by a specific SKU or Product code. So, in case a specific combination needs to be displayed through the Cylindo products, such as Content API, HD 360 Viewer, the Option for each the Feature needs to be passed through the APIs to get the desired variation.
For example, if a configurable product named ARMCHAIR is created in Magento 2 and it has one option named UPHOLSTERY with two possible values, named YELLOW and BLUE. Magento creates 3 products defined by the SKUs ARMCHAIR, ARMCHAIR-YELLOW and ARMCHAIR-BLUE.
In the Cylindo the same product will be identified by the product code, ARMCHAIR, and it would contain only one feature named UPHOLSTERY and the options of this feature would be YELLOW and BLUE.
In case the ARMCHAIR-YELLOW variation needs to be displayed, the feature and option UPHOLSTERY:YELLOW need to be passed through the Viewer API to display this variation of the product.
Implementation process
To implement the HD 360 Viewer within Magento2, we need to modify the default Catalog module of Magento2 to add the new functionality required by Cylindo.
To achieve this, we’ll need to install the Cylindo’s core and then create a Block and a Template file to create the Cylindo logic that will be embedded in the PDP view through the XML file of the Catalog module. Please notice that due to the version of Magento that you’ve installed and the structure of your online store part of the process could be different, but essentially this is the same process of all the implementations.
Step 1. Cylindo’s core installation within the Layout
Open the file app/code/Magento/Catalog/view/frontend/layout and within the <head> tag create the Cylindo tags to download the CSS core.
<script src="https://viewer.cylindo.com/v4/viewer.min.js" src_type="url"/>
<css src="https://viewer.cylindo.com/v4/viewer.min.css" src_type="url"/>
Step 2. Create the Block Class
Create the file Cylindo.php within app/code/Magento/Catalog/Block/Ui/ it will store the Class with the Functions needed to display the viewer.
This Class is in charge of retrieving the information needed to create and manage the viewer instance in the Product Detail Page, the information needed to create the viewer instance, are the Account ID, Product Code, and the Features and Options that will be mapped and linked to the configuration panel of the customer website.
The block file contains 4 functions.
- getConfigurableProduct, This function retrieves the information of the configurable product.
- getAttributes, This function retrieves the information of the attributes of the configurable object.
- getAdminOptions, This function retrieves the option codes of the admin store. It is important to mention that this function retrieves the option labels (codes) of the admin store instead of the labels of the store, in case you’ve
- getCylindoData, This function retrieves a JSON object with the information retrieved by the above functions.
The complete PHP class can be downloaded from this link.
Step 3. Create the Template
Create the file cylindo.phtml within if the folder doesn’t exist, it should be created app/code/Magento/Catalog/view/frontend/templates/product/view/
The template file is a phtml file where the information generated by the Block Class is received, this file is in charge to build the 360 viewer instance and also to detect the changes of the configuration panel to update the features of the viewer instance.
To learn more about the implementation of the 360 viewer instance you can read more about it here.
The complete phtml file can be downloaded here.
Step 4. Render the phtml file in the PDP
Open and modify again the file catalog_product_view.xml from the folder app/code/Magento/Catalog/view/frontend/layout to add the block in the PDP
The below piece of code shows how to achieve this, for this case we’re indicating that within the content container we’re adding a block using the Cylindo’s block and template.
<referenceContainer name=“content”>
<block
class=“Magento\Catalog\Block\Ui\Cylindo”
name=“cylindo”
as=“cylindo”
template=“Magento_Catalog::product/view/cylindo.phtml”/>
</referenceContainer>
The complete XML file can be downloaded here:
https://drive.google.com/file/d/1W20AaVcRGFbFTkpwMG2uIo6TF1iEF4EN/view?usp=sharing
Once these files are added in your online store and the cache of the Magento2 store is cleared the HD 360 Viewer should be displayed in the PDP of the customer’s website.
The below screenshot shows the resultant view.
