Gatemi Free Shipping Bar Developer Reference

The free edition applies no filters or actions of its own. Everything under Filters is the full edition's; its settings screen lists the same filters under For developers.

Filters — Full edition

gmfsb_settings

The settings array, merged over the defaults, the first time it is read in a request. Keys: enabled, locations, message, message_qualified, accent_color, success_color.

gmfsb_locations

The automatic placements, a list drawn from shop, cart, minicart and checkout.

// No bar on the checkout for logged-in customers.
add_filter( 'gmfsb_locations', function ( $locations ) {
	if ( is_user_logged_in() ) {
		$locations = array_diff( $locations, array( 'checkout' ) );
	}
	return array_values( $locations );
} );

gmfsb_free_shipping_method_ids

Which shipping method ids count as a free-shipping rule. Default array( 'free_shipping' ). A method added here must answer get_option() for requires, min_amount and ignore_discounts the way WooCommerce's own Free shipping method does.

gmfsb_cart_total

Argument Type
$total float The cart total measured against the minimum, rounded to the store's decimals

gmfsb_progress_state

Argument Type
$state ProgressState or null null means no bar. Otherwise an object with threshold, total, remaining, percent and qualified

Return null — or anything that is not a GatemiFreeShippingBarCoreProgressState — to hide the bar.

gmfsb_bar_html

Argument Type
$html string The bar markup, wrapped in <div class="gmfsb-fragment">
$state ProgressState or null The state it was built from

Keep the .gmfsb-fragment wrapper: it is the element the cart fragments replace.

Others

Filter What it changes
gmfsb_modules The module list, before the plugin boots
gmfsb_license_api_url The licence API base, default https://gatemi.com/wp-json/gatemi-license/v1
gmfsb_update_cache_ttl How long an update answer is cached, in seconds (default 12 hours)
gmfsb_update_retry_ttl How long to wait after a failed update check (default 15 minutes)
gmfsb_sync_cache_ttl How long a shared licence roster is cached

Actions — Full edition

gmfsb_booted fires once all modules are wired, with the service container as its argument.

Block and shortcode — Full edition

  • Block: Free Shipping Bar, gatemi-free-shipping-bar/bar. Dynamic, rendered on the server through the same renderer as every placement, no attributes, at most one per page.
  • Shortcode: [gatemi_free_shipping_bar].

A singular post or page containing either is skipped by the automatic placements.

Hooks the bar renders on

Placement Classic hook Block page
shop woocommerce_before_shop_loop —
cart woocommerce_before_cart above woocommerce/cart
minicart (full) woocommerce_widget_shopping_cart_before_buttons —
checkout (full) woocommerce_before_checkout_form above woocommerce/checkout

The full edition prints on the classic hooks at priority 7, and adds the bar to woocommerce_add_to_cart_fragments and woocommerce_update_order_review_fragments under the key div.gmfsb-fragment. On the Cart and Checkout blocks, which fire no fragment events, its script subscribes to the wc/store/cart data store and, when the cart totals change, requests WooCommerce's own get_refreshed_fragments endpoint (passed to the script as gmfsbData.fragmentsUrl) and swaps the div.gmfsb-fragment it returns. Keep the wrapper if you filter the markup.

On first run, while gmfsb_settings does not exist, the full edition copies enabled and the shop/cart entries of locations from gmfb_settings into it, once, and leaves gmfb_settings untouched.

Options

Option Edition Contents
gmfb_settings free enabled (yes/no), locations (subset of shop, cart)
gmfsb_settings full the six settings listed under gmfsb_settings
gmfsb_license full licence state

Neither edition writes post meta, order meta or custom tables. The full edition schedules gmfsb_license_check only once a licence key is entered.

Markup and CSS classes

Free edition:

<div class="gmfb-bar" role="status">
  <p class="gmfb-message">Add <span class="gmfb-amount">…</span> more to unlock free shipping</p>
  <div class="gmfb-track" aria-hidden="true"><div class="gmfb-fill" style="width:60%"></div></div>
</div>

.gmfb-bar--qualified is added once free shipping is unlocked. Stylesheet handle: gmfb-bar.

Full edition: the same shape with the gmfsb- prefix — .gmfsb-fragment › .gmfsb-bar (with .gmfsb-bar--qualified) › .gmfsb-message, .gmfsb-amount, .gmfsb-track, .gmfsb-fill. The fill also carries data-gmfsb-percent and a --gmfsb-percent custom property; .gmfsb-bar carries --gmfsb-accent and --gmfsb-success. With a coupon-only rule there is no track. Style and script handle: gmfsb.

/* A thicker track. */
.gmfb-track,
.gmfsb-track { height: 10px; border-radius: 5px; }
Shopping Cart
Scroll to Top