Table of Contents

Adobe Commerce Integration (Formerly known as Magento)

Using VividWorks 3D product configurator on an Adobe Commerce store is as simple as installing our official Adobe Commerce Extension to your store, and configuring it. While installing our extension from the Adobe Commerce Marketplace is free, to actually use it you must be a VividWorks customer with access to our Manager system.

Prerequisites and other considerations

The VividWorks 3D E-Commerce Configurator, and thus also our Adobe Commerce extension, does not handle pricing. We use the product SKUs, or other sales codes, to fetch prices from the hosting E-Commerce system and also for the add-to-cart. This means that you will have to have all SKUs and their prices defined in your product catalog.

As mentioned above you need to be a VividWorks customer with access to our platform's back-end management site to configure your product rules, or have the product rules defined by ViviWorks. The SKU or sales code mapping is done as part of the product rules in our back-end. These SKUs are then used to fetch prices and add the correct parts to the shopping cart.

Once you get to inserting the configurator on your store pages please keep in mind that we only support having one configurator per page. In fact in case of multiple configurators only one of them will be shown.

Installation

The Vividworks 3D Product Configurator Magento extension is installed via the official Magento Marketplace and Composer. Follow the below short instructions to get our extensions running on your shop.

1. Prerequisites

Before you begin the installation process, make sure you have the following prerequisites:

  • Magento Version: Currently our extension is tested against Magento 2.4.6
  • Access to Server: Ensure you have access to the server where Magento is installed
  • Composer: We use Composer so you have to have a way of installing Composer based extensions
  • Magento Marketplace Account: Our extension is available through Magento Marketplace where you will need a user account
  • Backup: As always, before installing any extension, it's advisable to take a backup of your Magento store.

2. Getting access to our extension

Installing our extension is easy and straight forward with the Magento Marketplace.

  • Visit Magento Marketplace.
  • Search for "VividWorks 3D Product Configurator".
  • Purchase the extension. Note that our extension is free but the Magento Marketplace requires you to "purchase" it.

Once you have purchased our extension, which is free, you can proceed to next steps. Note that you can install also manually (not with Marketplace and composer) but it requires us to send you the extension package.

3. Install the extension

You can install the module either manually or through composer on command line. The manual installation is really only necessary if you have received our extension as a ZIP package.

Composer based installation

To install our extension, first you need to require it through the composer.json like so:

composer require vividworks/module-3d-product-configurator

Next, enable the extension by running the following commands in your Magento installation

bin/magento module:enable VividWorks_ThreeDProductConfigurator
bin/magento setup:upgrade

Clear the Magento cache by running:

bin/magento cache:clean

And that is all, our extension is now installed. Please continue reading to properly configure the extension and your products.

Manual installation

Our recommendation in this case is to create a temporary folder in your Magento installation, call it for example extensions.

mkdir extensions

Now extract our ZIP package under the extensions folder so that our extension is in its own subfolder, called for example vividworks. You should now have our package and its composer.json file in the folder called extensions/vividworks/.

Now you should add the extensions folder as a repository for the composer. Run the following command in the magento installation root:

composer config repositories.dev-extensions path extensions/\*

To install our extension please run the following commands

composer require vividworks/module-3d-product-configurator:@dev
bin/magento module:enable VividWorks_ThreeDProductConfigurator
bin/magento setup:upgrade
bin/magento cache:clean

And that is all, our extension is now installed. Please continue reading to properly configure the extension and your products.

Uninstalling VividWorks 3D Product Configurator

Running the following commands in your Magento installation should be enough to remove our extension. What will happen is you will:

  • Disable our extension
  • Make sure Magento database is updated
  • Remove the extension
  • Update caches

These commands should work regardless of whether you installed our extension via the ZIP package or the from the public composer repository.

bin/magento module:disable VividWorks_ThreeDProductConfigurator
bin/magento setup:upgrade
composer remove vividworks/module-3d-product-configurator
bin/magento cache:clean

The extension should now be uninstalled and removed

Configuring your products

Modular products can easily result in even hundreds of products in an E-Commerce platform's product catalog. This is because these platforms are rarely designed to house highly modular products that can have tens of various separately configurable parts or modules, the variations of which will all need their own SKUs and pricing.

With this in mind, we recommend you set up a hidden product category to house all the different modules and parts of your product. Or even multiple hidden categories if you have multiple products. Place the modules or product parts in these categories as their own catalog products unless you actually want to have them visible in the shop front.

Of course if the product itself is fairly simple, with just a few options and maybe no external separate parts to choose from, this may be overkill.

For the pricing to work in our configurator, and the add-to-cart function to be operable, you need to make sure that all of your product SKUs and prices are defined in your product catalog. The same SKUs will also need to be configured in the VividWorks backend, so unless you are doing this by yourself be in contact with your VividWorks contact person.

Configuring the extension

Configuring our extension is very simple. As opposed to some other similar offerings we rely completely on our own SaaS service and your Adobe Commerce product configuration. All our extension has to do is show our embedded planner interface and provide integration for add-to-cart function and fetching prices to be shown in the configurator.

In below sections you will encounter two important terms, Library ID and Product ID. These two ID strings are what effectively ties your webshop products to our backend product logic, and eventually shows the correct configurator for the end user. Having both defined correctly is required for the configurator to work. You can get the correct IDs either from VividWorks support (though most likely they have been provided to you by us), or from our backend Manager website.

Global settings

Once our extensions is installed, the first thing to check is the extension's global settings. In the Adobe Commerce admin backend navigate to Stores and then Configuration. In the Configuration page you will find a section called VividWorks 3D Configurator. These are the global settings of our extension, affecting the usage and behavior of our extension through all of your stores and products.

The settings in this section are the following:

Setting Description
Enable 3D Configurator Make sure this setting is set to Yes. The intention of this setting is to globally disable the configurator if need be, in which case you can set it to No.
Enable add to cart Enabling add-to-cart will show a button in our extensions' public configurator widget which when pressed will add the configured parts into the shopping cart.
Library ID If you only have one VividWorks Product Library, you can define its ID here so that it is globally set and you do not have to set it again later. Otherwise leave empty.
Product ID If you are only going to use one product for configuration via our extension, you can set this ID here globally. Otherwise leave empty.

A note for Enable 3D Configurator and Enable add to cart settings

Both of these are set to Yes by default, meaning both of them are enabled globally by default. Add to cart can be disabled by setting it to No without disabling the 3D Configurator.

A note of Library ID and Product ID settings

As mentioned previously, these two identifaction strings decide which product is visualized and configured in our configurator. The two IDs can be configured in three different places in the Adobe Commerce admin backend:

  1. The product level settings
  2. Widget level settings
  3. Global settings (exaplained in previous sections)

The priority of use for the two IDs is the same as above. Meaning, if I set the IDs in the product level settings no matter what settings the widget has the IDs are used as per the product settings.

If instead I have both product settings and widget settings left empty, the settings from the global configuration will be used.

In absence of Library ID and Product ID (not set in any of the three) the configurator will not be shown at all.

Please keep this in mind when planning on how to embed the configurator on your store.

Product specific settings

When editing a Product (Catalog -> Products -> Edit) there is a section called "VividWorks 3D Product Configurator". Under this section you have three settings:

  1. Active to enable or disable the configurator for this product
  2. Library ID as explained above
  3. Product ID also as explained above

If you are planning on showing the configurator on the product pages directly you can set the Library ID and Product ID settings in the Product settings page. These settings will be prioritized over all other settings as exaplained in previously.

Inserting the configurator into the webshop

There are a few different ways to insert our configurator on your shop, depending on where it needs to be shown. The configurator can be shown on any Page of the store, or inserted on special pages such as Product Pages via the Widgets.

A variation of the direct Page insertion is to create a Block first and then insert this block into a page. This approach allows to insert the same configurator to multiple pages with minimal work.

The following two sections will explain in details the two different approaches.

Widget

The Widget is an easy way to insert our configurator on any page, even multiple pages at once. For product pages, and some other "special" pages that are not available in the Pages section of the admin panel, this is also the only way to insert our configurator unless done directly in the template. Just make sure the following content containers exist and are allowed on the pages you want to insert the configurator to:

  • Main Content Top
  • Main Content Area
  • Main Content Bottom

To create a Widget navigate to Content -> Widgets. Now select "Add Widget". Select "3D Product Configurator" as the widget type and your theme in the "Design Theme" selection, and push "Continue".

Give the Widget a title that makes it easier to recognize in case you want to configure multiple Widgets.

For "Assign to Store Views" in most cases one should select "All Store Views".

The "Sort Order" should be left to 0. We do not support multiple configurators on one page.

Under "Widget Options" in the side menu you can find the Library ID and Product ID settings. If you will be using the Product level settings for assigning the two IDs you can leave these empty. If inserting the configurator to any other page on the store these two settings need to be assigned here.

Back in the "Storefront Properties" menu of the Widget there is a section called "Layout Updates". This is what you will use to actually insert the Widget on the pages. You can use the Layout Updates to insert the Widget for example to all product pages, a single specific product page, all product pages of a certain product, and so on.

For the sake of an example lets add the Widget on a specific product page:

  • Click the "Add Layout Update"
  • Select "All product types" for "Display on" dropdown
  • For "Products" select "Specific Products"
  • Use the product selector interface (that should've now appeared right below) to select the product(s) you want the widget to show on
  • Select the container you want the widget to show in

Now save the widget. For the layouts to update you may need to flush the Magento cache. You can do this by navigating to System -> Cache Management and hitting "Flush Magento Cache".

You should now see our configurator on the selected products' page in the store front.

Using the Page Builder and Blocks

The configurator can also be iserted on any content pages by using the Page Builder. The configurator can be added on a page by inserting a widget (note that this is slightly different from the Widget exaplained in the above section) on any which part of the page, or by first creating a content Block into which a widget is added.

Using the content Blocks is adviceable if you intend to add the same product configurator on multiple different pages. To add a configurator on a single page and other simple situations it may be more straight forward to just use the pages' Page Builder directly.

Insert via content Block

A content Block is basically a reusable block of content that can then be added on any page by using the Page Builder. This might be handy in cases where the same configurator needs to be added on multiple pages, or in general for easier maintenance. For example you might want to remove the configurator from a certain page but then later on add it back easily without remembering the Library ID and Product ID settings.

For more information about Blocks please refer to the official documentation

To create a Block navigate to Content -> Blocks and hit "Add New Block". Then:

  • Make sure the Block is enabled and give a recognizable Title. The title is used to later know which block to add in the Page Builder.
  • Give a Block a unique Identifier. This should be all lower case and no spaces. For convenience consider using the Title but transforming it from "My Sofa Configurator Block" to "my-sofa-configurator-block".
  • Select the store views this block is to be used in, or just "All store views".
  • Click "Edit with Page Builder"
  • In the Page Builder, drag an "HTML Code" element on the page from under the "Elements" section in the side bar
  • Select the new HTML Code element and go to its settings (the cog / gear icon)
  • In the settings page, choose Insert Widget
  • On the widget page, choose "3D Product Configurator" as the widget type
  • Now add the Library ID and Product ID that match the product you want to have configured.
  • Press the "Insert Widget" button at the top of the page.
  • Now save the settings of the HTML Code element by pushing "Save"
  • Close the Page Builder

You are now ready to add the Block to any content Page. Navigate to Content -> Pages and edit the target page by choosing "Select" and then "Edit" on the right hand side of the page table.

To add your content Block:

  • From under the "Content" section in the Page editor, choose "Edit with Page Builder"
  • From under the "Add Content" section of the side bar, drag a Block element on the page
  • Select the new Block element and go to its settings (the gear icon).
  • Now choose "Select Block"
  • Find the Block you created previously and push "Select" on the right hand side of its row
  • Now choose "Save" to save the block.
  • Close the Page Builder

The configurator should now be visible on the page you just edited.

We do not document the other modifications you can do for the Block and the Page but of course Adobe Commerce allows you to customize the looks and layout of the pages fairly freely.

Insert directly via widget

To add our 3D Product Configurator widget directly on pages works fairly similarly to what was just ecxplained above for the Block. In this case just go and edit the target Page and do the following:

  • From under the "Content" section in the Page editor, choose "Edit with Page Builder"
  • From under the "Elements" section of the side bar, drag an HTML Code element on the page
  • Select the new HTML Code element and go to its settings (the cog / gear icon)
  • In the settings page, choose Insert Widget
  • On the widget page, choose "3D Product Configurator" as the widget type
  • Now add the Library ID and Product ID that match the product you want to have configured.
  • Press the "Insert Widget" button at the top of the page.
  • Now save the settings of the HTML Code element by pushing "Save"
  • Close the Page Builder

That is all, the configurator should now be visible on the page in the store front.

Localization

Our 3D Product Configurator is localized in our web-based management interface. The language used and shown for the end user is selected based on the language chosen in the Shop. No further configuration is necessary for the extension itself, just make sure you have the localizations done in our management interface, based on the languages available in your shop.