JezK

Edit File: Troubleshooting-FAQ.md

# Troubleshooting & FAQ Common issues and their solutions, derived from the plugin changelog and known compatibility requirements. --- ## Cart Not Appearing ### Cart Shows on Some Pages But Not Others **Expected behaviour:** The cart drawer and floating button are **intentionally hidden** on the WooCommerce checkout page to prevent UX conflicts. The cart is enabled when `enable_moderncart` is `'all'` AND: - The page is NOT `is_checkout()` - OR the page is `is_shop()`, `is_product()`, or `is_cart()` **If the cart is missing on other pages**, check: 1. Navigate to **WooCommerce → Modern Cart → General tab** 2. Verify `enable_moderncart` is not set to `'disabled'` 3. Check if any plugin is returning `false` via the `moderncart_override_is_global_enabled` filter ### Cart Not Visible — Maintenance Mode Active When the site is in maintenance mode (WooCommerce Coming Soon, Elementor maintenance, or WordPress core maintenance), the floating cart button is not rendered. This is intentional. Admins (`manage_options` capability) can still see the cart. **Fix:** Disable maintenance mode, or use an admin account to preview. ### Cart Missing During REST API Requests When WordPress renders nav menu widgets via the REST API (`/wp-json/wp/v2/widget-types/`), the cart output is suppressed to prevent it from appearing inside widget block renders. This is expected. The cart will appear normally on the frontend. --- ## Cart Appears Empty After Back Button Navigation **Symptom:** User adds products to the cart, navigates to checkout, then uses the browser back button — the cart drawer shows as empty. **Fix (v1.0.7):** This was fixed by properly refreshing the cart state when navigating back via browser history. Update to v1.0.7 or later. --- ## Tax Display Issues **Symptom:** Tax amounts not showing correctly in the cart total, or the cart total includes incorrect tax values. **Fix (v1.0.7):** A tax calculation issue was fixed in the cart total display to ensure accurate tax calculation and display for WooCommerce carts. Update to v1.0.7 or later. **If still encountering issues:** - Verify WooCommerce tax settings under **WooCommerce → Settings → Tax** - Check if a third-party plugin is modifying `woocommerce_before_calculate_totals` at a conflicting priority - Modern Cart hooks `woocommerce_before_calculate_totals` at priority 10 for custom price support --- ## Product Names Showing HTML Tags (TranslatePress) **Symptom:** Cart item product names display raw HTML tags when TranslatePress is active. **Fix (v1.0.6):** Fixed in v1.0.6. Update to resolve. --- ## AJAX Add-to-Cart Not Working **Symptom:** Clicking "Add to Cart" refreshes the page instead of opening the drawer. **Checklist:** 1. Verify `enable_ajax_add_to_cart` is `true` in **General settings** 2. Check browser console for JavaScript errors 3. Verify the nonce is present in `moderncart_ajax_object.ajax_nonce` 4. Check for JavaScript conflicts from other plugins (test with plugins deactivated one by one) **If intentionally disabled by a filter:** ```php // Check if this filter is returning true somewhere in your codebase apply_filters( 'moderncart_disable_ajax_add_to_cart', false ) ``` **Fix (v1.0.6):** An AJAX add-to-cart issue was fixed to ensure the form submits correctly. Update to v1.0.6 or later. --- ## Coupon Field Issues **Symptom:** Coupon field doesn't expand, or coupon state is lost after page interactions. **Fix (v1.0.2):** Coupon field reliability was improved through better state management. Update to v1.0.2 or later. **Manual check:** 1. Navigate to **WooCommerce → Modern Cart → Cart tab** 2. Verify `enable_coupon_field` is not set to `'disabled'` 3. Ensure the coupon section option is set to `'minimize'` or `'expand'` --- ## Shipping Calculation Errors **Symptom:** Shipping total shows incorrectly, or changes when cart items change. **Fix (v1.0.2):** Corrected shipping calculation errors for accurate totals when shipping settings change. Update to v1.0.2 or later. **Debugging:** 1. Check WooCommerce → Settings → Shipping for correct zone configuration 2. `Cart::get_free_shipping_amount()` reads from Zone ID `1` for unknown customers — ensure Zone 1 has the correct settings 3. Override the threshold: `add_filter('moderncart_free_shipping_min_amount', function() { return 50; });` --- ## Astra Cart Icon Still Triggering Astra's Cart **Symptom:** Clicking the Astra header cart icon opens Astra's mini-cart instead of Modern Cart. **Fix (v1.0.2):** Astra cart icon compatibility was fixed through better custom trigger selector handling. Update to v1.0.2 or later. **Manual check:** - Verify the `modern-cart-for-wc-available` class is added to the Astra cart menu element (inspect element in browser) - Check if a caching plugin is serving old HTML without the class --- ## Astra's Mobile Cart Flyout Still Appearing **Symptom:** Astra's mobile slide-out cart appears alongside Modern Cart's drawer. Modern Cart should automatically remove Astra's mobile cart flyout on `wp_loaded`. If it's still appearing: 1. Check if `Astra_Builder_Header::mobile_cart_flyout` is being re-added by another plugin or hook 2. Verify Modern Cart is loading after Astra (it should, as it loads on `plugins_loaded`) --- ## Firefox CSS Issues in Cart **Symptom:** Cart layout looks incorrect in Firefox (misaligned elements, wrong padding). **Fix (v1.0.2):** Firefox CSS issues in the popup cart were fixed. Update to v1.0.2 or later. --- ## Pro Plugin Compatibility Notice **Symptom:** An admin notice says "Modern Cart for WooCommerce: Update Required." **Cause:** Modern Cart Pro (`modern-cart-woo`) is installed but its version is older than 1.2.0. **Fix:** Update Modern Cart Pro to version 1.2.0 or higher. The Starter plugin will not initialise until Pro is updated. --- ## Cart Not Showing in WooCommerce "Coming Soon" Mode **Symptom:** Store is in "Coming Soon" mode with "Apply to store pages only" option active, and cart was not appearing correctly. **Fix (v1.0.4):** A compatibility issue was fixed. Update to v1.0.4 or later. **Note:** By design, Modern Cart hides the floating button for non-admin users when the site is in full Coming Soon mode. --- ## Settings Not Saving **Symptom:** Changes in the settings panel don't persist after saving. **Checklist:** 1. Ensure the currently logged-in user has `manage_options` capability 2. Check browser console for AJAX errors (403, 500) 3. Verify nonce is not expired (happens with very long admin sessions without page reload) 4. Check if a security plugin is blocking `admin-ajax.php` requests --- ## Cart Count Badge Wrong **Symptom:** Floating cart button shows wrong item count. The count is driven by `WC()->cart->get_cart_contents_count()`. Check: - If a plugin is modifying `woocommerce_cart_contents_count` - Override via filter: `add_filter('moderncart_filter_cart_count', function($count) { return $count; });` --- ## Custom CSS Variables Not Working **Symptom:** Changed colours in Appearance settings but frontend cart still shows old colours. **Checklist:** 1. Colour settings are output as CSS custom properties on `:root`. Check browser DevTools → Elements → `:root` for `--moderncart-*` variables 2. If using a caching plugin, clear the cache after changing settings 3. If Astra is active, colours may be sourced from Astra's CSS variables, not the settings — this is by design --- ## General Debugging ### Enable Debug Mode Add to `wp-config.php`: ```php define( 'MODERNCART_DEBUG', true ); ``` This causes script/style versions to include a timestamp, bypassing browser cache on every load. ### Check Plugin Status ```php // In a test PHP snippet: if ( defined( 'MODERNCART_VER' ) ) { echo 'Modern Cart loaded. Version: ' . MODERNCART_VER; echo 'WooCommerce active: ' . ( class_exists('woocommerce') ? 'yes' : 'no' ); echo 'Pro status: ' . \ModernCart\Inc\Helper::get_pro_status(); echo 'Global enabled: ' . ( \ModernCart\Inc\Cart::get_instance()->is_global_enabled() ? 'yes' : 'no' ); } ``` ### Verify AJAX Object In the browser console on a frontend page: ```javascript console.log(moderncart_ajax_object); // Should show: { ajax_url, ajax_nonce, animation_speed, ... } ``` If undefined, the scripts failed to enqueue — check `is_global_enabled()` result. --- ## FAQ ### Does Modern Cart work without WooCommerce? No. WooCommerce is required. Modern Cart only loads after confirming `class_exists('woocommerce')`. ### Does Modern Cart work on the checkout page? No, by design. The cart is suppressed on checkout pages to avoid UX conflicts. ### Can I use Modern Cart with any page builder? Yes. It works with Elementor, Spectra, Gutenberg, Beaver Builder, Bricks, Oxygen, and others. ### Does Modern Cart slow down my site? Scripts are only enqueued when the cart is enabled (`is_global_enabled()` check). The AJAX pattern replaces only the drawer innerHTML rather than full page reloads. Knowledge base data is cached for 12 hours. ### Do I need CartFlows? No, but the plugin integrates with CartFlows for express checkout and the edit cart button. ### How do I change the "Powered by Modern Cart" footer link? Go to **WooCommerce → Modern Cart → General** and toggle off "Enable Powered By". Or programmatically: ```php add_filter( 'moderncart_default_settings', function( $defaults ) { $defaults[ MODERNCART_MAIN_SETTINGS ]['enable_powered_by']['value'] = false; return $defaults; } ); ``` ### Where is support? - Documentation: `https://cartflows.com/docs-category/modern-cart-for-woocommerce/` - Support: `https://cartflows.com/support/` - Community: `https://www.facebook.com/groups/cartflows/` - GitHub Issues: `https://github.com/brainstormforce/modern-cart/issues`