Migrating from Legacy to Web Components

This guide provides a comprehensive walkthrough for migrating from the legacy Mimeeq implementation (using data-mimeeq attributes) to the modern Web Components approach (using <mmq-embed> elements). The migration process is designed to be straightforward, allowing you to take advantage of improved performance, enhanced features, and better compatibility without significant code refactoring.

Why Migrate?

Legacy Method - End of Life Approaching

The legacy integration method using data-mimeeq attributes is deprecated and scheduled for removal in future releases. To ensure continued functionality and access to new features, migration to the Web Components approach is strongly recommended.

Migrating to the Web Components approach offers several significant advantages:

Feature	Legacy Approach	Web Components Approach
Performance	Baseline	30-40% faster rendering
Browser Compatibility	Limited	Enhanced cross-browser support
Shadow DOM Encapsulation	No	Yes - prevents CSS conflicts
Feature Support	Limited to core features	Full feature set with ongoing updates
Maintenance	Critical fixes only	Active development and improvements
Modal Support	Basic	Enhanced with improved sizing controls
Memory Management	Manual cleanup required	Automatic cleanup
Custom UI Support	Limited	Comprehensive customization options
Developer Experience	Verbose	Simplified, declarative API

Migration Quick Reference

The ideal migration path involves moving your configuration to embed templates in the admin panel, resulting in much cleaner code:

Legacy Code

<div
  data-mimeeq
  data-mimeeq-short-code="ABC123"
  data-withhistory
  data-locale="en"
  data-mimeeq-ui-hide-price
  data-mimeeq-ui-hide-tabs
  data-mimeeq-button-color="#0066cc"></div>
<script
  src="https://jrdgrq09nk.execute-api.eu-central-1.amazonaws.com/api/cpq/get-embed-short-code-data?shortCode=ABC123&html=1"
  rel="script"
  type="application/javascript"
  async></script>

Web Component Equivalent

<mmq-embed short-code="ABC123" template="your_template_id"></mmq-embed>
<script
  src="https://cdn.mimeeq.com/read_models/embed/app-embed.js"
  rel="script"
  type="application/javascript"
  async></script>

This approach moves all configuration settings into the embed template, which can be managed through the Mimeeq admin panel by non-technical users. This creates a clean separation between code and configuration, making future updates easier to manage without requiring developer involvement.

Step-by-Step Migration Process

Follow this simplified process to ensure a smooth transition from legacy to Web Components:

1. Create an Embed Template in the Admin Panel

First, create a template that includes all your configuration settings:

Log in to your Mimeeq admin panel
Navigate to Settings → Embed Templates
Click "Create New Template"
Configure all settings that were previously defined as HTML attributes
Save the template and note the template ID

This approach offers several significant advantages:

Settings can be updated by non-technical users
Changes can be made without developer involvement
Updates take effect immediately without code deployments
Templates provide a real-time preview of changes
Multiple templates can be created for different contexts

2. Update Script Reference

Next, replace the legacy script reference with the new Web Components script:

Legacy:

<script
  src="https://jrdgrq09nk.execute-api.eu-central-1.amazonaws.com/api/cpq/get-embed-short-code-data?shortCode=YOUR_SHORTCODE&html=1"
  rel="script"
  type="application/javascript"
  async></script>

Web Component:

<script
  src="https://cdn.mimeeq.com/read_models/embed/app-embed.js"
  rel="script"
  type="application/javascript"
  async></script>

3. Replace Container Element With Minimal Web Component

Replace your complex legacy container with a simple web component that references your template:

Legacy (with many attributes):

<div
  data-mimeeq
  data-mimeeq-short-code="YOUR_SHORTCODE"
  data-withhistory
  data-locale="en"
  data-mimeeq-ui-hide-price
  data-mimeeq-ui-hide-tabs
  data-mimeeq-button-color="#0066cc"
  data-mimeeq-background-color="#f5f5f5"
  ...many
  more
  attributes...></div>

Web Component (clean and simple):

<mmq-embed short-code="YOUR_SHORTCODE" template="your_template_id"></mmq-embed>

In most cases, that's all you need! The template contains all your configuration settings, creating a much cleaner integration and making future updates simpler.

4. Update Event Listeners

If your application uses Mimeeq events, the events themselves remain the same, but some implementation details may change:

Legacy:

// Manually mount/unmount the configurator
document.dispatchEvent(new Event('mimeeq-show-configurator'));
document.dispatchEvent(new Event('mimeeq-unmount'));

// Listen for events
document.addEventListener('mimeeq-app-loaded', (event) => {
  console.log('Mimeeq app loaded');
});

Web Component:

// Use the component's show/hide methods
document.querySelector('mmq-embed').show();
document.querySelector('mmq-embed').hide();

// Events work the same way
document.addEventListener('mimeeq-app-loaded', (event) => {
  console.log('Mimeeq app loaded');
});

5. Update Custom JavaScript

If you have custom JavaScript that interacts with the Mimeeq application, most code will continue to work with minimal changes:

Legacy and Web Component (Same API):

// This code works with both implementation methods
window.mimeeqApp.observers.product.configurationCode.subscribe(({ newValue }) => {
  console.log('Configuration code changed:', newValue);
});

window.mimeeqApp.utils.setPrice({
  price: 1299.99,
  unitPrice: 1299.99,
  currency: 'EUR',
});

Common Migration Scenarios

Basic Product Configurator

Legacy:

<div data-mimeeq data-mimeeq-short-code="ABC123"></div>
<script
  src="https://jrdgrq09nk.execute-api.eu-central-1.amazonaws.com/api/cpq/get-embed-short-code-data?shortCode=ABC123&html=1"
  rel="script"
  type="application/javascript"
  async></script>

Web Component with Template:

<mmq-embed short-code="ABC123" template="basic_template"></mmq-embed>
<script
  src="https://cdn.mimeeq.com/read_models/embed/app-embed.js"
  rel="script"
  type="application/javascript"
  async></script>

Legacy:

<button id="openConfiguratorBtn">Configure Product</button>
<div data-mimeeq data-mimeeq-short-code="ABC123" data-mimeeq-modal></div>
<script
  src="https://jrdgrq09nk.execute-api.eu-central-1.amazonaws.com/api/cpq/get-embed-short-code-data?shortCode=ABC123&html=1"
  rel="script"
  type="application/javascript"
  async></script>
<script>
  document.getElementById('openConfiguratorBtn').addEventListener('click', () => {
    document.dispatchEvent(new Event('mimeeq-show-configurator'));
  });
</script>

Web Component with Template:

<button id="openConfiguratorBtn">Configure Product</button>
<mmq-embed id="productConfigurator" short-code="ABC123" template="modal_template"></mmq-embed>
<script
  src="https://cdn.mimeeq.com/read_models/embed/app-embed.js"
  rel="script"
  type="application/javascript"
  async></script>
<script>
  document.getElementById('openConfiguratorBtn').addEventListener('click', () => {
    document.getElementById('productConfigurator').show();
  });
</script>

Note: The "modal_template" would have the "Render in Modal" option enabled in the admin panel.

Configurator with Custom UI Elements and Event Listeners

Even for implementations with custom UI elements and event listeners, the migration approach remains straightforward:

Legacy:

<div
  data-mimeeq
  data-mimeeq-short-code="ABC123"
  data-mimeeq-ui-hide-price
  data-mimeeq-ui-hide-tabs></div>
<div id="custom-price">Custom price display</div>
<script
  src="https://jrdgrq09nk.execute-api.eu-central-1.amazonaws.com/api/cpq/get-embed-short-code-data?shortCode=ABC123&html=1"
  rel="script"
  type="application/javascript"
  async></script>
<script>
  document.addEventListener('mimeeq-app-loaded', () => {
    window.mimeeqApp.observers.product.price.subscribe(({ newValue }) => {
      document.getElementById('custom-price').textContent =
        `Price: ${newValue.price} ${newValue.currency}`;
    });
  });
</script>

Web Component with Template:

<mmq-embed short-code="ABC123" template="custom_ui_template"></mmq-embed>
<div id="custom-price">Custom price display</div>
<script
  src="https://cdn.mimeeq.com/read_models/embed/app-embed.js"
  rel="script"
  type="application/javascript"
  async></script>
<script>
  document.addEventListener('mimeeq-app-loaded', () => {
    window.mimeeqApp.observers.product.price.subscribe(({ newValue }) => {
      document.getElementById('custom-price').textContent =
        `Price: ${newValue.price} ${newValue.currency}`;
    });
  });
</script>

Note: The "custom_ui_template" would have options like "Hide Price" and "Hide Tabs" enabled in the admin panel.

Modular Configurator

Legacy:

<button id="openModularBtn">Design Your Space</button>
<div data-mimeeq data-mimeeq-short-code="MOD123" data-mimeeq-modular-modal></div>
<script
  src="https://jrdgrq09nk.execute-api.eu-central-1.amazonaws.com/api/cpq/get-embed-short-code-data?shortCode=MOD123&html=1"
  rel="script"
  type="application/javascript"
  async></script>
<script>
  document.getElementById('openModularBtn').addEventListener('click', () => {
    document.dispatchEvent(new Event('mimeeq-show-modular'));
  });
</script>

Web Component with Template:

<button id="openModularBtn">Design Your Space</button>
<mmq-embed id="modularConfigurator" short-code="MOD123" template="modular_template"></mmq-embed>
<script
  src="https://cdn.mimeeq.com/read_models/embed/app-embed.js"
  rel="script"
  type="application/javascript"
  async></script>
<script>
  document.getElementById('openModularBtn').addEventListener('click', () => {
    document.getElementById('modularConfigurator').show();
  });
</script>

Note: The "modular_template" would have the "Render Modular in Modal" option enabled in the admin panel.

Testing Your Migration

After migrating, we recommend testing the following aspects of your implementation:

Basic Rendering - Verify that the configurator displays correctly
Interactivity - Confirm that all user interactions work as expected
Custom Styles - Check that any custom styling is applied correctly
Event Handling - Test that all event listeners continue to function
Modal Behavior - For modal implementations, verify open/close functionality
Responsive Design - Test across different screen sizes and devices
Performance - Monitor for any unexpected performance differences

Troubleshooting Common Issues

Configurator Not Showing

Issue: The configurator doesn't appear after migration.

Solution:

Verify that the short-code attribute is correctly set
Check for JavaScript errors in the browser console
Ensure the script is loaded before interacting with the component
If using render-at-mount, make sure it's properly set

Events Not Firing

Issue: Custom event handlers aren't triggered.

Solution:

Confirm that event listeners are attached after the mimeeq-app-loaded event
Verify event names and listener implementation
Check that selectors correctly target the new components

Style Conflicts

Issue: Custom styling no longer applies or causes conflicts.

Solution:

Shadow DOM encapsulation in Web Components may require different styling approaches
Use CSS custom properties (variables) for theming
For detailed styling, use the ::part() selector approach

Issue: Modal behavior differs from the legacy implementation.

Solution:

Ensure the correct modal attribute is used (with-modal, with-modal-modular, or with-modal-list)
Use the component's show() and hide() methods instead of dispatching events
Check modal sizing attributes if the dimensions don't match expectations

Getting Additional Help

If you encounter issues during migration that aren't covered in this guide:

Check the comprehensive mmq-embed documentation
Review the events documentation for event handling changes
Explore the embed options for equivalent settings
Contact Mimeeq support for personalized assistance

Conclusion

Migrating from the legacy implementation to Web Components offers significant benefits beyond just technical improvements:

Separation of Code and Configuration: By moving settings to embed templates in the admin panel, you create a clean separation between code and configuration.
Non-Developer Updates: Templates can be managed by non-technical staff, reducing reliance on developers for basic configuration changes.
Real-Time Updates: Changes to templates take effect immediately without code deployments or release cycles.
Visual Editor: The admin panel provides an intuitive visual interface with real-time preview for creating and editing templates.
Performance and Compatibility: Web Components provide better performance, enhanced cross-browser compatibility, and access to the latest features.

The simplicity of the migration process—creating a template in the admin panel and replacing complex HTML with a minimal web component reference—makes this an accessible upgrade for all Mimeeq customers. Since the template contains all your configuration settings, the actual code change is minimal in most cases.

Remember that the legacy approach will be deprecated in future releases, so planning your migration now will prevent potential compatibility issues down the line.

Why Migrate?​

Migration Quick Reference​

Legacy Code​

Web Component Equivalent​

Step-by-Step Migration Process​

1. Create an Embed Template in the Admin Panel​

2. Update Script Reference​

3. Replace Container Element With Minimal Web Component​

4. Update Event Listeners​

5. Update Custom JavaScript​

Common Migration Scenarios​

Basic Product Configurator​

Modal Configurator​

Configurator with Custom UI Elements and Event Listeners​

Modular Configurator​

Testing Your Migration​

Troubleshooting Common Issues​

Configurator Not Showing​

Events Not Firing​

Style Conflicts​

Modal Issues​

Getting Additional Help​

Conclusion​

Why Migrate?

Migration Quick Reference

Legacy Code

Web Component Equivalent

Step-by-Step Migration Process

1. Create an Embed Template in the Admin Panel

2. Update Script Reference

3. Replace Container Element With Minimal Web Component

4. Update Event Listeners

5. Update Custom JavaScript

Common Migration Scenarios

Basic Product Configurator

Modal Configurator

Configurator with Custom UI Elements and Event Listeners

Modular Configurator

Testing Your Migration

Troubleshooting Common Issues

Configurator Not Showing

Events Not Firing

Style Conflicts

Modal Issues

Getting Additional Help

Conclusion