Shopware Integration

This documentation will guide you through the process of creating and installing a custom Shopware plugin called “DopplePlugin” which integrates the Dopple SDK into the product page. This integration requires overriding the cms-element-image-gallery.html.twig template to load the Dopple functionality.

Be sure to consult the Shopware Plugins documentation for more information on creating custom plugins.

Prerequisites

1. Shopware setup with a store setup.
2. You have a valid owner and workspace name ready for use.
3. You know the configuration properties and values available on your 3D product (typically found in the editor from Dopple).
4. You have at least one product created in your Shopware store.

Creating the Plugin

Creating a custom Shopware plugin will allow you to easily integrate 3D Dopple products into your pages using the Dopple SDK, and add custom fields to your products for controlling product configuration and variants.

Plugin Setup

1. Generate the plugin skeleton

   First, generate the plugin skeleton by running the following command:

   bin/console plugin:create DopplePlugin

   This command creates a basic plugin structure in the custom/plugins/DopplePlugin directory.

2. Navigate to plugin directory

   Change to the newly created plugin directory:

   cd custom/plugins/DopplePlugin

3. Plugin configuration

   The basic configuration is generated in DopplePlugin.php. If additional functionality is required, you can modify this file, but for this integration, most changes will happen in the template and JavaScript files.

Creating the Template File

To integrate the Dopple SDK, you need to override the cms-element-image-gallery.html.twig file. This file is responsible for rendering the image gallery section in Shopware.

1. Create directory structure

   Under the DopplePlugin/src/Resources/views/storefront/element/ directory, create the following file structure if it doesn’t exist already:

   • DirectoryDopplePlugin

     • Directorysrc

       • DirectoryResources

         • Directoryviews

           • Directorystorefront

             • Directoryelement

               • cms-element-image-gallery.html.twig

2. Override the default template

   In the newly created template file, add the following code to extend and override the existing cms-element-image-gallery.html.twig template:

   cms-element-image-gallery.html.twig

   {% sw_extends '@Storefront/storefront/element/cms-element-image-gallery.html.twig' %}
   
   {% block element_image_gallery %}
   
   <div id="dopple-container">
     <div id="containerEle" style="height: 500px; position: relative;"></div>
   
     <script>
         document.addEventListener('DOMContentLoaded', async function () {
           const container = document.getElementById('containerEle');
           if (container) {
             console.log('Container ready for rendering');
           }
           const pageData = {{ page|json_encode|raw }};
           const selection = pageData.product.variation.reduce((acc, variant) => {
               if (variant.group && variant.option) {
                   acc[variant.group] = variant.option;
               }
               return acc;
           }, {});
   
           const productVariants = [
             {% for variant in page.product.children %}
               {
                 "mapping": {{ variant.customFields.dopple_mapping|json_encode }},
                 "variantId": "{{ variant.id }}",
               }
               {% if not loop.last %},{% endif %}
             {% endfor %}
           ];
   
           const mappedVariant = productVariants.reduce((acc, variant) => {
             acc[variant.variantId] = { ...variant };
             return acc;
           }, {});
   
           const doppleObj = {
             owner: '{{ page.product.customFields.doppleOwner|e }}',
             workspace: '{{ page.product.customFields.doppleWorkspace|e }}',
             productName: '{{ page.product.customFields.doppleProjectName|e }}',
             productVersion: '{{ page.product.customFields.doppleProductVersion|e }}',
             productVariants
           };
   
           console.log('Dopple Metaobject Fields:', {{page|json_encode|raw}});
   
           const { DoppleXR } = await import(
             "https://builds.dopple.io/packages/dopple-sdk@latest/dopple-sdk.js"
           );
           const sessionId = window.crypto.randomUUID();
           const dopple = new DoppleXR({
             container,
             selection: selection,
             owner: doppleObj.owner,
             workspace: doppleObj.workspace,
             projectName: doppleObj.productName,
             productVersion: doppleObj.productVersion,
             logNamespace: "sdk",
             sessionId,
           });
   
           await dopple.load();
           dopple.resize({ trackParentSize: true });
           dopple.run();
         });
     </script>
   
   </div>
   {% endblock %}

   This code ensures that the Dopple container is added after all images, and Dopple’s functionality is initialized only after the page has fully loaded.

Installing and Activating the Plugin

After adding the template file, follow these steps to install and activate the plugin.

1. Refresh plugins

   Refresh the Shopware plugins to make the new plugin available:

   bin/console plugin:refresh

2. Install the plugin

   Install the plugin with the following command:

   bin/console plugin:install DopplePlugin

3. Clear the cache

   Clear the Shopware cache to ensure all changes are applied:

   bin/console cache:clear

Creating the README.md

To document the plugin’s functionality, create a README.md file in the root of your plugin directory (DopplePlugin/README.md).

Below is a sample template you can use for the README.md file:

# DopplePlugin

This plugin integrates Dopple functionality into the Shopware product pages. It utilizes the Dopple SDK to display interactive 3D models based on product variants.

## Installation

### 1. Create the Plugin

To create the plugin, run the following command:

```bash
bin/console plugin:create DopplePlugin
```

### 2. Template Override

The plugin overrides the `cms-element-image-gallery.html.twig` template. Create the following file to implement the Dopple container:

```
DopplePlugin/src/Resources/views/storefront/element/cms-element-image-gallery.html.twig
```

### 3. Plugin Installation

Run the following commands to install and activate the plugin:

```bash
bin/console plugin:refresh
bin/console plugin:install DopplePlugin
bin/console cache:clear
```

## Usage

Once installed, the Dopple container will automatically be added to the product page. The Dopple SDK will be initialized when the page is loaded, displaying the 3D model based on the product variants.
Custom Fields

The plugin expects the following custom fields on the product:

- `dopple_mapping`
- `doppleOwner`
- `doppleWorkspace`
- `doppleProjectName`
- `doppleProductVersion`

Using the DopplePlugin

Once you have installed and activated the DopplePlugin, follow the steps below to configure and use the plugin.

Adding Custom Fields via the Admin UI

The DopplePlugin relies on specific custom fields for its configuration. You need to add these custom fields to the products in the Shopware Admin UI.

1. Log in to the Shopware admin panel

   Navigate to the admin panel of your Shopware instance.

2. Go to “Custom Fields”

   In the main menu, go to Settings > System > Custom Fields.

3. Create a custom field set

   • Click the Create New Set button.
   • Provide a name for the field set, such as Dopple Fields.
   • Assign the custom field set to Products under the Relation field.
   • Save the custom field set.

4. Add custom fields

   Add the following custom fields to the set. Ensure that the technical name matches exactly as specified below:

   • Dopple Owner
     • Type: Text
     • Technical Name: doppleOwner
     • Description: Specifies the owner for the Dopple configuration.
   • Dopple Workspace
     • Type: Text
     • Technical Name: doppleWorkspace
     • Description: Specifies the workspace ID used for Dopple.
   • Dopple Project Name
     • Type: Text
     • Technical Name: doppleProjectName
     • Description: Specifies the project name for Dopple.
   • Dopple Product Version
     • Type: Text
     • Technical Name: doppleProductVersion
     • Description: Specifies the product version for Dopple.

5. Save the custom fields

   • After adding the custom fields, click Save to apply the changes.

Assigning Custom Fields to Products:

• Go to the Products section in the admin panel.
• Open any product you want to configure with Dopple.
• In the product details, navigate to the Specifications tab.
• Find the Custom Fields section under Specifications.
• Fill in the values for the custom fields you created:
  • Dopple Owner
  • Dopple Workspace
  • Dopple Project Name
  • Dopple Product Version
• Ensure that the values are accurate and relevant to the product.
• Save the product.

How the Plugin Works

• The plugin adds a Dopple container below the product image gallery in the storefront.
• When a product page is loaded, the Dopple container initializes using the custom fields specified for that product.
• Users can interact with the 3D model in the Dopple container.

Additional Notes

• Additional information may be found on the Shopware Plugins documentation page.
• Ensure the Dopple SDK script is accessible via your network for the container to work.
• Any issues with custom fields or the Dopple container should be debugged using the browser’s developer console for potential errors.