Developer Reference
The technical details for developers building on or around ShapedCart: shortcodes, custom buttons, events, the Store API, and what it stores.
This page is for developers and agencies. It covers the parts of ShapedCart you can build on, and how it fits into WooCommerce. For styling, see Custom CSS.
Shortcodes
ShapedCart has one shortcode, which outputs the menu cart icon:
| Shortcode | Output |
|---|---|
[shaped_cart_menu] | The menu cart link: icon, count badge and total, as set on the Menu Cart card |
[reno_menu_cart] | The same output. This is the name from before the rename, and it stays registered permanently. |
The shortcode takes no attributes. It outputs nothing when:
- Enable ShapedCart is off, on the Settings tab
- the Menu Cart card is switched off
- the current page is excluded by the Menu Cart's Hide on setting
The output is a link to the WooCommerce cart page, so it still works without JavaScript:
<a href="https://example.com/cart/" class="shaped-cart-menu-trigger" data-shaped-cart-open="1" aria-label="Open cart">
<span class="shaped-cart-menu-trigger__icon-wrap">
<svg class="shaped-cart-menu-trigger__icon" aria-hidden="true">…</svg>
<span class="shaped-cart-menu-trigger__count" data-shaped-cart-count>3</span>
</span>
<span class="shaped-cart-menu-trigger__total" data-shaped-cart-total>…</span>
</a>To render it from PHP, for example in a theme template, use echo do_shortcode( '[shaped_cart_menu]' );.
Custom open button
Add the data-shaped-cart-open attribute to any element, and clicking it opens the ShapedCart side cart. Use it to build your own cart button, for example in a custom header, a page builder layout, or next to a "Continue to cart" message.
<!-- A link: opens the side cart, and falls back to the cart page without JavaScript -->
<a href="/cart/" data-shaped-cart-open>View your cart</a>
<!-- A button -->
<button type="button" data-shaped-cart-open>Open cart</button>How it behaves:
- Any element works. One listener on the page handles every element with the attribute, including elements added after the page loads, for example by AJAX or a page builder.
- Links don't navigate. On a link, ShapedCart opens the side cart instead of following the link. If ShapedCart's script isn't running, the link works normally, so pointing it at your cart page gives you a sensible fallback.
- The attribute's value doesn't matter.
data-shaped-cart-openanddata-shaped-cart-open="1"behave the same. - Keyboard support comes from the element. Use a
<button>or an<a href>, and keyboard users can open the cart with Enter, and Space on a button. If you have to use another element, give itrole="button"andtabindex="0", and ShapedCart handles Enter and Space for it. A plain<div>or<span>without those can be clicked but not reached by keyboard. - It only works where the side cart is on the page. That's every storefront page while Enable ShapedCart is on.
data-shaped-cart-close works the same way in reverse: clicking an element with it closes the side cart. The cart's own close button and overlay use it.
No JavaScript API
There's no open() function to call. The data attribute is the supported way to open the cart. The shapedCartFrontend object on the page is ShapedCart's internal configuration, not an API, and it can change between versions.
Events ShapedCart listens to
ShapedCart refreshes the side cart, and opens it if Auto-open on add is on, when either of these WooCommerce events fires on document.body:
| Event | Fired by |
|---|---|
added_to_cart (jQuery event) | WooCommerce's classic AJAX add-to-cart buttons, and quick view plugins built on them |
wc-blocks_added_to_cart (DOM CustomEvent) | WooCommerce's product blocks, such as the buttons in a Product Collection block |
It also detects adds from the single product page's normal form submit on the server, through WooCommerce's woocommerce_add_to_cart action. See Auto-Open on Add to Cart.
If your own code adds products to the cart, for example a custom quick view or bundle builder, fire one of the events afterwards. ShapedCart then fetches the new cart from the Store API and opens:
// With jQuery, which WooCommerce loads on most storefronts:
jQuery( document.body ).trigger( 'added_to_cart' );
// Or without jQuery:
document.body.dispatchEvent( new CustomEvent( 'wc-blocks_added_to_cart' ) );ShapedCart doesn't need the event's arguments. It reads the cart fresh either way.
Store API
ShapedCart's storefront script talks to WooCommerce's Store API, the REST API that WooCommerce's own Cart and Checkout blocks use, at /wp-json/wc/store/v1/. It uses these routes:
| Route | Used for |
|---|---|
GET cart | Refreshing the cart after an add |
POST cart/update-item | Changing a quantity |
POST cart/remove-item | Removing an item |
POST cart/apply-coupon | Applying a coupon |
POST cart/remove-coupon | Removing a coupon |
Every request sends WooCommerce's Nonce header, plus an X-Shaped-Cart: 1 header. ShapedCart uses that header to recognize its own requests, so that add-on plugins which only add item details on the cart page also add them for the side cart. Other Store API clients, like the Cart block, aren't affected.
Because the cart changes through the Store API, anything that hooks into WooCommerce's cart, such as pricing rules, fees, coupons or add-ons, applies to the side cart the same way it applies to the Cart block.
WooCommerce and WordPress hooks it uses
ShapedCart doesn't add PHP actions or filters of its own. On the storefront, it uses these standard WordPress and WooCommerce hooks:
| Hook | How ShapedCart uses it |
|---|---|
wp_footer | Prints the side cart and the floating cart markup |
wp_enqueue_scripts | Loads its stylesheet and script on storefront pages |
wp_nav_menu_items | Adds the menu cart to the menu picked in Add to Menu |
woocommerce_add_to_cart | Notes that a product was added in this request, for auto-open after a normal form submit |
woocommerce_get_item_data | Applies this filter to collect custom item details from add-on plugins, for Show custom details |
woocommerce_variation_option_name | Applies this filter to get display names for custom (non-taxonomy) variation attributes, the same way WooCommerce does, so swatch plugins that change those names are respected |
Because it uses woocommerce_get_item_data, your own code can add a detail line to the side cart by filtering it, exactly as you would for the WooCommerce cart page.
Assets
| Handle | Type | File |
|---|---|---|
shaped-cart-frontend | Stylesheet | assets/frontend/drawer.css, plus an inline :root block with the custom properties |
shaped-cart-frontend | Script | assets/frontend/drawer.js, in the footer, with no dependencies |
Both load on every storefront page while Enable ShapedCart is on, because the floating cart and menu cart can open the side cart from any page. The script is small and has no dependencies, not even jQuery.
Dequeuing breaks the cart
Removing these with wp_dequeue_script() leaves the cart markup on the page with nothing to run it. To turn ShapedCart off, use Enable ShapedCart instead.
If a speed plugin delays or combines JavaScript, exclude drawer.js. See Compatibility → Caching.
Admin REST API
The ShapedCart settings screen uses its own REST routes under /wp-json/shaped-cart/v1/. Each one requires the manage_woocommerce capability:
| Route | Used for |
|---|---|
GET settings | Loading the settings screen |
POST settings | Saving settings |
POST settings/reset | Reset All Settings |
GET menus | The Add to Menu list |
These routes are there for the settings screen, not as a public API, and they may change between versions.
Stored options
ShapedCart stores everything in a few rows of the WordPress options table. It creates no custom tables, post types or files.
| Option | What it holds |
|---|---|
shaped_cart_settings | Every setting, as one array. Not autoloaded. |
shaped_cart_db_version | The version whose data updates last ran on this site. Autoloaded. |
shaped_cart_first_activated_version | The version first activated on this site. Never changes after that. |
shaped_cart_first_activated_date | When it was first activated. Never changes after that. |
reno_cart_settings, reno_cart_first_activated_version, reno_cart_first_activated_date, reno_cart_current_version | Only on sites that ran RenoCart 0.1.0. The pre-rename copies, kept as a backup. ShapedCart doesn't use them once it has copied them to the new names. |
To read a setting in your own code, use get_option( 'shaped_cart_settings' ) and fall back to a default if a key is missing. A setting added in a newer version isn't in the stored array until the settings are saved again. Avoid writing to the option directly. Values saved through the settings screen are checked and cleaned first, and a direct write skips that.
With WP-CLI:
wp option get shaped_cart_settings --format=jsonTo check whether ShapedCart is active from your own plugin or theme, test for its version constant:
if ( defined( 'SHAPED_CART_VERSION' ) ) {
// ShapedCart is active.
}Uninstalling & Data explains which of these options are removed when the plugin is deleted.
Templates
ShapedCart has no template files to override. Its markup is generated in PHP. Use Custom CSS to change the look, the woocommerce_get_item_data filter to add item details, and the custom open button to add your own triggers.
Related
- Custom CSS: custom properties, class names and breakpoints
- Auto-Open on Add to Cart: how adds are detected
- Compatibility: themes, page builders and caching