Skip to content

Configuration

All of Dankon’s settings live on one screen, WooCommerce > Dankon Tips, and are stored in a single tipping_settings option (an array). The page sits under the WooCommerce submenu and is gated to the manage_woocommerce capability; saving goes through options.php with the same capability. There are six settings, grouped into General and Presets.

The master switch, on by default. When off, the control never renders and no CSS or JavaScript is enqueued on the storefront, the checkout is untouched. Stored as enabled (boolean).

The heading shown above the tip buttons, e.g. Add a tip or Support our shelter. Stored as label. Leave it blank and Dankon uses the translated default “Add a tip” (shown as the field placeholder), so the checkout follows the site language. This same text is used as the fee label on the order, so it is what the customer sees on the totals line and in emails.

Optional supporting text under the label, e.g. a short note that tipping is always optional. Stored as description. Leave it blank to use the translated default (“Support our team, every tip is appreciated. Choose an amount or skip.”).

A checkbox under the description, on by default. Stored as show_description (boolean). Untick it to show the label on its own. Clearing the description box does not hide it, because an empty box means “use the default wording”.

How each preset value is interpreted. Stored as type, one of:

  • Percentage of cart (percent, the default), each value is a percentage of the pre-tip items subtotal. A 5 preset adds 5% of the subtotal, so a larger order means a larger tip.
  • Fixed amount (fixed), each value is a flat amount in your store currency, the same whatever the cart total.

Comma-separated numbers, stored as the presets list. Decimals are allowed to two places. For percentages use numbers like 5, 7.5, 10; for fixed amounts use currency values (2, 5, 10). On save the values are run through wc_format_decimal, rounded to two decimals, and filtered to positive numbers only, zero, negative and non-numeric entries are dropped. A maximum of eight presets is kept; the rest are ignored. Leave the field empty and the control is hidden until you add at least one.

The settings page renders a non-interactive preview of the resulting pills (percentages as 5%, fixed values formatted with wc_price) so you can see the effect before saving.

The control only appears when it is enabled and has at least one valid preset. If either is false, the storefront renders nothing, no assets load, and no fee is added, there is no broken or empty widget. This is why an enabled install with the presets field cleared simply hides the control.

  • The customer’s choice (a preset index, or “none”) is stored in the WooCommerce session over a nonce-protected AJAX call (tipping_set).
  • On every woocommerce_cart_calculate_fees, Dankon resolves the choice to an amount and adds it with WC_Cart::add_fee(). The fee is added non-taxable, tips and donations are not taxed, and this is not configurable.
  • A percentage tip is computed from WC_Cart::get_subtotal() (the pre-tip, tax-exclusive items subtotal) at calculation time, so it tracks the live cart.
  • An empty / “No tip” selection resolves to 0 and no fee line is added, there is never a £0 tip row.
  • At checkout, the resolved amount is written to the order as _tipping_amount meta, for auditing alongside the fee. The chosen preset index is saved as _tipping_preset and, when an add-on supplies recipients, the recipient as _tipping_recipient. This runs on woocommerce_checkout_create_order and, for the block checkout, on woocommerce_store_api_checkout_update_order_from_request.

A few behaviours are deliberately not settings:

  • Tips are never taxed, the fee is always added as non-taxable.
  • The default selection is always “No tip”, there is no setting to preselect a preset, which keeps tipping fully opt-in.
  • The control renders only on the classic checkout, at woocommerce_review_order_before_payment. There is no placement setting and no cart-page rendering.
  • There are no shortcodes, the control appears automatically on the checkout when usable, or not at all.

The control is rendered from templates/tip-control.php inside the plugin. It is loaded directly from the plugin directory, there is no theme-override path, so copying it into your theme has no effect. Adjust the appearance with CSS (below) rather than by replacing the template.

The storefront styles are built on --tipping-* custom properties, accent, ink, border, pill background, radius and gap, so you can re-theme the control from your theme stylesheet:

.tipping {
--tipping-accent: #0a7c66; /* hover + active border, focus ring */
--tipping-ink: #075c4b; /* active text + the underline stroke */
--tipping-radius: 8px;
}

The default accent is a warm honey-amber, and the chosen preset draws a hand-drawn “tip line” underline inside the pill (no layout shift). Dark-mode colours and a prefers-reduced-motion block (which disables the transitions) are built in and need no configuration. The accent falls back to your theme’s --wp--preset--color--primary where one is exposed.

Dankon exposes these hooks.

tipping/fee_amount, filter the resolved tip amount before it becomes a cart fee. Arguments: $amount (float, store currency), $selection (the TipSelection service) and $base (float, the subtotal used for percentage tips). The result is rounded to the store’s price decimals. This is the hook Pro round-up tipping uses:

add_filter( 'tipping/fee_amount', function ( float $amount, $selection ): float {
// Round the order up to the next whole unit and tip the difference.
$subtotal = $selection->cartSubtotal();
$roundUp = ceil( $subtotal ) - $subtotal;
return $amount + $roundUp;
}, 10, 2 );

tipping/admin_after_cards, fires inside the settings form, after the free setting cards and before the submit button. Add-ons echo their own .tipping-admin__card here; fields named under tipping_settings[...] save with the form. The settings page/option-group slug is available as \Dankon\Admin\Settings::pageSlug() (tipping-settings) so add-ons can register settings against the same group.

tipping/control_before_options, fires inside the storefront control, after the label and description and before the preset buttons. It receives one $context array with options, presets, current (the stored choice: mode, preset, recipient), recipients, isPercent, label and description. Pro uses it to render recipient or cause selectors.

tipping/recipients, filter the list of tip recipients. The free plugin returns an empty list. Each row needs a non-empty id (sanitised as a key, duplicates dropped) and label; a recipient sent with the AJAX call that is not on this list is ignored.

add_filter( 'tipping/recipients', function ( array $recipients ): array {
$recipients[] = [ 'id' => 'kitchen', 'label' => 'Kitchen team' ];
return $recipients;
} );

tipping/booted, action fired once the plugin has registered all its services, with the Plugin instance. Add-ons hook here to extend the shared container.

Settings live in the single tipping_settings option; a tipping_db_version option tracks the schema. Order data uses _tipping_amount, _tipping_preset and _tipping_recipient meta. Dankon creates no custom database tables. Deleting the plugin runs the uninstall routine, which removes both options (on every site of a multisite network) but keeps the tip order meta, that is part of completed orders’ financial record. Everything stays in your own database; Dankon contacts no external service.