Upcart V2.0 migratiegids

Overzicht

Upcart V2.0-modules introduceren een volledig architectonisch herontwerp van het cartsysteem. De update richt zich op verbeterde prestaties, uitgebreidere aanpassingsmogelijkheden en betere onderhoudbaarheid. Deze gids helpt je te begrijpen wat er verandert bij de migratie van V1.0- naar V2.0-modules, welke compatibiliteitsproblemen je kunt tegenkomen en hoe je je bestaande aanpassingen veilig bijwerkt.

Breaking changes - wijzigingen in CSS-klassenamen

V1-klassen (verouderd)

🚨 De volgende V1.0-klassenamen worden niet meer ondersteund in V2.0:

.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...

De waarschuwingsklassen voor uitverkochte producten upcart-quantity-warning en upcart-quantity-warning-text zijn ook ongewijzigd. Ze komen uit de cart-initializer en niet uit een module met versiebeheer, dus ze worden identiek uitgegeven, ongeacht of je modules op V1 of V2 draaien.

.styles_CartPreview__card__ staat niet in deze lijst — dit is de gedeelde cart-shell-wrapper die rond elke module wordt weergegeven, ongeacht de versie, dus regels die hierop gericht zijn blijven werken op V2. De rewards-klassen zijn .styles_Rewards__ (eenvoudige balk) en .styles_TieredRewards__ (balk met niveaus); er bestaat geen .styles_RewardsModule__.

/*******************  
*** Cart Header ***  
*******************/  
'upcart-header',  
'upcart-header-text',  
'upcart-header-logo',  
'upcart-header-close-button',  
'upcart-header-close-button-icon',  
  
/******************  
*** Line Items ***  
******************/  
'upcart-products-section',  
'upcart-product-item',  
/** > Title */  
'upcart-product-title',  
'upcart-product-title-link',  
/** > Prices */  
'upcart-item-prices-row',  
'upcart-item-price',  
'upcart-item-compare-price',  
'upcart-product-savings',  
/** > Options/Variants */  
'upcart-item-option',  
'upcart-item-option-category',  
'upcart-item-option-value',  
/** > Bundle Item Components */  
'upcart-bundle-item-image-wrapper',  
'upcart-bundle-item-product-title',  
'upcart-bundle-item-variant-title',  
'upcart-bundle-detail-toggle',  
/** > Properties */  
'upcart-item-properties',  
'upcart-item-property',  
'upcart-item-property-subscription',  
/** > Quantity Selector */  
'upcart-product-quantity-input',  
'upcart-product-quantity-minus',  
'upcart-product-quantity-plus',  
/** > Image */  
'upcart-product-image-wrapper',  
  
/*********************  
*** Announcements ***  
*********************/  
'upcart-announcement',  
  
/***************  
*** Rewards ***  
***************/  
'upcart-rewards',  
'upcart-rewards-message',  
'upcart-rewards-bar-background',  
'upcart-rewards-bar-foreground',  
'upcart-rewards-tier',  
'upcart-rewards-tier-circle',  
'upcart-rewards-tier-icon',  
'upcart-rewards-tier-description',  
  
/***************  
*** Upsells & Recommendations ***  
***************/  
'upcart-upsells-module',  
'upcart-upsells-title',  
'upcart-upsells-button',  
'upcart-upsell-item-title',  
'upcart-upsell-item-card',  
'upcart-upsell-item-image-wrapper',  
'upcart-upsell-item-image',  
'upcart-upsell-item-price',  
'upcart-upsell-item-price-row',  
'upcart-upsell-item-compare-price',  
'upcart-upsell-item-variant-selector',  
'upcart-upsells', // deprecated  
'upcart-recommendation-module',  
'upcart-recommendations-title',  
'upcart-recommendations-shop-now-button',  
  
/***************  
*** Add-ons ***  
***************/  
'upcart-addons',  
'upcart-addons-title',  
'upcart-addons-product-description',  
'upcart-addons-price',  
'upcart-addons-compare-price',  
'upcart-addons-toggle',  
'upcart-addons-image-wrapper',  
  
/**********************  
*** Discount Codes ***  
**********************/  
'upcart-discount-code-row',  
'upcart-discount-code-module',  
'upcart-discount-code-button',  
'upcart-discount-code-input',  
'upcart-discount-code-badge',  
'upcart-discount-code-icon',  
'upcart-discount-code-text',  
'upcart-discount-code-input-wrapper',  
  
/*****************************  
*** Subscription Upgrades ***  
*****************************/  
'upcart-subscription-upgrade-section',  
'upcart-subscription-upgrade-button',  
'upcart-subscription-upgrade-dropdown',  
  
/***************************  
*** Express Pay Buttons ***  
***************************/  
'upcart-express-pay-buttons-container',  
'upcart-express-pay-buttons-row',  
'upcart-express-pay-button',  
'upcart-express-pay-button-shop-pay',  
'upcart-express-pay-button-google-pay',  
'upcart-express-pay-button-paypal',  
'upcart-express-pay-button-apple-pay',  
'upcart-express-pay-button-amazon-pay',  
'upcart-express-pay-button-meta-pay',  
  
/********************  
*** Trust Badges ***  
********************/  
'upcart-trust-badge',  
'upcart-trust-badge-image',  
  
/********************  
*** Integrations ***  
********************/  
'upcart-integration-zapiet-pickup',  
  
/*****************  
*** Skeletons ***  
*****************/  
'upcart-skeleton',  
'upcart-product-item-skeleton',  
'upcart-product-image-skeleton',  
'upcart-product-title-skeleton',  
'upcart-item-option-skeleton',  
'upcart-product-quantity-skeleton',  
'upcart-product-price-container-skeleton',  
'upcart-announcement-skeleton',  
'upcart-rewards-skeleton',  
'upcart-rewards-message-skeleton',  
'upcart-rewards-bar-skeleton',  
'upcart-upsells-module-skeleton',  
'upcart-upsells-title-skeleton',  
'upcart-upsell-item-image-skeleton',  
'upcart-upsell-item-title-skeleton',  
'upcart-upsell-item-price-skeleton',  
'upcart-upsells-button-skeleton',  
'upcart-trust-badge-skeleton',  
'upcart-trust-badge-image-skeleton',  
'upcart-checkout-button-container-skeleton',  
'upcart-checkout-button-skeleton',  
'upcart-addons-skeleton',  
'upcart-addons-image-wrapper-skeleton',  
'upcart-addons-skeleton-text-container',  
'upcart-discount-code-module-skeleton',  
'upcart-discount-code-input-skeleton',  
'upcart-discount-code-button-skeleton',  
'upcart-express-pay-buttons-container-skeleton',  
'upcart-express-pay-button-skeleton'

V2.0-klassen (nieuw systeem)

V2.0 introduceert een gestructureerd naamgevingssysteem met interne en publieke klasseprefixen.

Interne klassenamen

Deze zijn gereserveerd voor intern gebruik en kunnen zonder kennisgeving wijzigen. Als je deze klassen overschrijft, is toekomstige compatibiliteit niet gegarandeerd.

/* Internal classes - for Upcart's internal styling */   
.upcart-internal-header  
.upcart-internal-header__close-button  
.upcart-internal-cart-items  
.upcart-internal-rewards  
...

Publieke klassenamen

🚨 Lijst met beschikbare publieke klassenamen

/*******************  
***** Skeleton *****  
*******************/  
'upcart-public-skeleton'  
  
/*******************  
****** Header ******  
*******************/  
'upcart-public-header'  
'upcart-public-header__close-button'  
'upcart-public-header__close-button-icon'  
  
/*******************  
*** Announcement ***  
*******************/  
'upcart-public-announcement'  
  
/*******************  
** Recommendation **  
****** Upsell ******  
*******************/  
'upcart-public-component-upsell-tile'  
'upcart-public-component-upsell-tile__image-container'  
'upcart-public-component-upsell-tile__image'  
'upcart-public-component-upsell-tile__info'  
'upcart-public-component-upsell-tile__title-link'  
'upcart-public-component-upsell-tile__title'  
'upcart-public-component-upsell-tile__rating-row'  
'upcart-public-component-upsell-tile__stars'  
'upcart-public-component-upsell-tile__star--partial'  
'upcart-public-component-upsell-tile__reviews'  
'upcart-public-component-upsell-tile__price-row'  
'upcart-public-component-upsell-tile__price-compare-at'  
'upcart-public-component-upsell-tile__price'  
'upcart-public-component-upsell-tile__variant-row'  
'upcart-public-component__button'  
'upcart-public-component-loader'  
'upcart-public-upsell__skeleton'  
'upcart-public-upsell__skeleton-title'  
'upcart-public-upsell__skeleton-image'  
'upcart-public-upsell__skeleton-product-title'  
'upcart-public-upsell__skeleton-product-price'  
  
/*******************  
****** Notes *******  
*******************/  
'upcart-public-notes'  
'upcart-public-component-collapse__dropdown-container'  
'upcart-public-component-collapse__expand-icon'  
'upcart-public-notes__text-container'  
'upcart-public-notes__textarea'  
  
/*******************  
** Discount Code ***  
*******************/  
'upcart-public-discount-code'  
'upcart-public-discount-code__form'  
'upcart-public-discount-code__input-wrapper'  
'upcart-public-discount-code__input'  
'upcart-public-discount-code__suffix'  
'upcart-public-discount-code__error'  
'upcart-public-discount-code__button'  
'upcart-public-component__button'  
'upcart-public-skeleton'  
'upcart-public-discount-code__skeleton'  
'upcart-public-discount-code__skeleton-input'  
'upcart-public-discount-code__skeleton-button'  
  
/*******************  
** Trust Badges ****  
*******************/  
'upcart-public-trust-badges'  
'upcart-public-trust-badges__image'  
  
/*******************  
** Tiered Rewards **  
*******************/  
'upcart-public-rewards'  
'upcart-public-rewards__message'  
'upcart-public-rewards__bar'  
'upcart-public-component-segmented-progress-bar'  
'upcart-public-component-segmented-progress-bar__segments-container'  
'upcart-public-component-segmented-progress-bar__segment'  
'upcart-public-component-segmented-progress-bar__segment-fill'  
'upcart-public-component-segmented-progress-bar__milestone'  
'upcart-public-component-segmented-progress-bar__milestone--bottom'  
'upcart-public-component-segmented-progress-bar__milestone--top'  
'upcart-public-component-segmented-progress-bar__milestone--middle'  
'upcart-public-component-segmented-progress-bar__milestone-icon'  
'upcart-public-component-segmented-progress-bar__milestone-label'  
'upcart-public-component-segmented-progress-bar__milestone-label--align-right'  
'upcart-public-component-segmented-progress-bar__milestone-label--align-center'  
'upcart-public-rewards__skeleton',  
'upcart-public-rewards__skeleton-message',  
'upcart-public-rewards__skeleton-bar',  
  
/*******************  
**** Cart Items ****  
*******************/  
'upcart-public-component-product-tile'  
'upcart-public-component-product-tile__content'  
'upcart-public-component-product-tile__image-wrapper'  
'upcart-public-component-product-tile__image'  
'upcart-public-component-product-tile__info'  
'upcart-public-component-product-tile__header'  
'upcart-public-component-product-tile__product-title'  
'upcart-public-component-product-tile__title-link'  
'upcart-public-component-product-tile__remove-button'  
'upcart-public-component-loader'  
'upcart-public-component-product-tile__variant'  
'upcart-public-component-product-tile__properties'  
'upcart-public-component-product-tile__bundle'  
'upcart-public-component-product-tile__product-pricing'  
'upcart-public-component-product-tile__price-compare-at'  
'upcart-public-component-product-tile__price'  
'upcart-public-component-product-tile__savings'  
'upcart-public-component-product-tile__controls'  
'upcart-public-component-product-tile__quantity-selector'  
'upcart-public-component-product-tile__quantity-minus'  
'upcart-public-component-product-tile__quantity-plus'  
'upcart-public-component-product-tile__discount-codes'  
'upcart-public-component-tag'  
'upcart-public-component-tag__icon'  
'upcart-public-component-tag__text'  
'upcart-public-component-product-tile__subscription-upgrade'  
'upcart-public-component__button'  
'upcart-public-component-product-tile__select-wrapper'  
'upcart-public-component-product-tile__select'  
'upcart-public-product-properties__subscription'  
'upcart-public-product-properties__item'  
'upcart-public-product-properties__link'  
'upcart-public-cart-items__key-value-pair'  
'upcart-public-bundle-properties'  
'upcart-public-bundle-properties__variant-title'  
'upcart-public-component-collapse__dropdown-container'  
'upcart-public-bundle-properties__header'  
'upcart-public-component-collapse__expand-icon'  
'upcart-public-notes__text-container'  
'upcart-public-bundle-properties__item-components'  
'upcart-public-bundle-properties__item-component-row'  
'upcart-public-bundle-properties__image-wrapper'  
'upcart-public-bundle-properties__content'  
'upcart-public-bundle-properties__product-title'  
'upcart-public-upsell__skeleton'  
'upcart-public-upsell__skeleton-title'  
'upcart-public-upsell__skeleton-image'  
'upcart-public-upsell__skeleton-product-title'  
'upcart-public-upsell__skeleton-product-price'  
  
/*******************  
***** Add-ons ******  
*******************/  
'upcart-public-addons'  
'upcart-public-addons__image-wrapper'  
'upcart-public-addons__content-wrapper'  
'upcart-public-addons__content-title-wrapper'  
'upcart-public-addons__content-title'  
'upcart-public-addons__content-price'  
'upcart-public-addons__compare-at-price'  
'upcart-public-addons__price'  
'upcart-public-addons__content-description'  
'upcart-public-addons__toggle-wrapper'  
'upcart-public-addons__toggle'  
'upcart-public-addons__toggle-switch'  
'upcart-public-addons__toggle-slider'  
'upcart-public-skeleton'  
'upcart-public-addons__skeleton'  
'upcart-public-addons__skeleton-image'  
'upcart-public-addons__skeleton-text'  
  
/*******************  
*** Cart summary ***  
*******************/  
'upcart-public-cart-summary'  
'upcart-public-cart-summary__discount-codes'  
'upcart-public-cart-summary__discount-label'  
'upcart-public-cart-summary__slide-codes'  
'upcart-public-cart-summary__total-discount'

Deze maken deel uit van de publieke styling-API (upcart-public-) en kunnen veilig worden overschreven voor aangepaste designs.

.upcart-public-header  
.upcart-public-header__close-button  
.upcart-public-rewards  
...

✅ DO’s

Gebruik alleen upcart-public--klassenamen voor styling.

/* ✅ Correct usage */  
.upcart-public-header {     
  font-size: 18px;  
  font-weight: bold;   
}

❌ DON’T’s

Vermijd het overschrijven van interne klassenamen

/* ❌ Avoid this */  
.upcart-internal-header {     
  font-size: 18px;  
  font-weight: bold;   
}

Vermijd het targeten van specifieke nodes met diepe of aangepaste selectors.

/* ❌ Avoid this */  
.upcart-public-upsell div a {     
  font-size: 18px;  
  font-weight: bold;   
}

Data-attribuutsysteem

V2.0 introduceert een gestructureerd data-attribuutsysteem voor betere targeting en geavanceerde aanpassingen.

<!-- V2 data attributes for targeting -->   
<div data-upcart-chunk="header-title-content" />     
<div data-internal-properties="hasNonDefaultTitleAlignment=true" />       
<div data-placement="topOfFooter" />

Deze attributen maken het eenvoudiger om flexibele, datagestuurde templates te maken terwijl de code overzichtelijk blijft.

Wijzigingen in templatevariabelen

V2-modules gebruiken een nieuwe syntaxis voor templatevariabelen met dubbele accolades {{ }}.

Announcement-module

V1.0: `{TIMER}`
V2.0: `{{timer}}`

Tiered Rewards-module

V1.0: `{AMOUNT}` → V2: `{{amount}}`
V1.0: `{COUNT}` → V2: `{{count}}`

Migratieproces

1. Maak een back-up van de huidige configuratie

Maak voordat je wijzigingen aanbrengt een back-up van je bestaande aangepaste CSS- en HTML-bestanden.

2. Test in sandbox-modus

Stel je bijgewerkte cart in met sandbox-modus om nieuwe modules veilig te testen voordat je live gaat.

Geavanceerde aanpassingen met V2.0

Aangepaste templates

V2.0-modules ondersteunen volledig aangepaste templates voor merchants die volledige controle willen over lay-out en structuur. Om aangepaste templates in te schakelen:

Ga naar Settings > Cart settings, vouw Advanced Settings uit en vink Access custom templates aan. Het selectievakje staat in dat ingeklapte gedeelte, niet op het tabblad Cart settings zelf.
Schakel de functietoggle in.
Raadpleeg de ontwikkelaarsdocumentatie van Upcart voor syntaxis en voorbeelden.

Ingeschakeld selectievakje Access custom templates met de beschrijving ervan in de cartinstellingen van Upcart

Let op: het supportteam van Upcart kan niet helpen met het ontwikkelen, debuggen of oplossen van problemen met aangepaste templates.

Best practices

Test updates altijd eerst in sandbox-modus.
Migreer en werk aanpassingen stapsgewijs bij.
Gebruik publieke klassen voor styling in plaats van interne klassen.
Bewaar back-ups van alle eerdere versies voordat je live instellingen bijwerkt.

Toekomstige overwegingen

V2-modules blijven nieuwe functies, optimalisaties en updates ontvangen.
V1-modules bevinden zich nu in onderhoudsmodus met beperkte ondersteuning en zonder nieuwe functies.
Merchants worden aangemoedigd om zo snel mogelijk naar V2 te migreren voor volledige compatibiliteit.

Aan de slag

Winkelwagenmodules

Winkelwageninstellingen

Sticky winkelwagenknop

Multicart

Aanpassingen

Analytics

Integraties en compatibiliteit

Facturering en account

Probleemoplossing

Overzicht

Breaking changes - wijzigingen in CSS-klassenamen

V1-klassen (verouderd)

V2.0-klassen (nieuw systeem)

Interne klassenamen

Publieke klassenamen

✅ DO’s

❌ DON’T’s

Data-attribuutsysteem

Wijzigingen in templatevariabelen

Announcement-module

Tiered Rewards-module

Migratieproces

1. Maak een back-up van de huidige configuratie

2. Test in sandbox-modus

Geavanceerde aanpassingen met V2.0

Aangepaste templates

Best practices

Toekomstige overwegingen

​Overzicht

​Breaking changes - wijzigingen in CSS-klassenamen

​V1-klassen (verouderd)

​V2.0-klassen (nieuw systeem)

​Interne klassenamen

​Publieke klassenamen

​

​✅ DO’s

​❌ DON’T’s

​Data-attribuutsysteem

​Wijzigingen in templatevariabelen

​Announcement-module

​Tiered Rewards-module

​Migratieproces

​1. Maak een back-up van de huidige configuratie

​2. Test in sandbox-modus

​Geavanceerde aanpassingen met V2.0

​Aangepaste templates

​Best practices

​Toekomstige overwegingen

​

​

Overzicht

Breaking changes - wijzigingen in CSS-klassenamen

V1-klassen (verouderd)

V2.0-klassen (nieuw systeem)

Interne klassenamen

Publieke klassenamen

✅ DO’s

❌ DON’T’s

Data-attribuutsysteem

Wijzigingen in templatevariabelen

Announcement-module

Tiered Rewards-module

Migratieproces

1. Maak een back-up van de huidige configuratie

2. Test in sandbox-modus

Geavanceerde aanpassingen met V2.0

Aangepaste templates

Best practices

Toekomstige overwegingen