Suma Woo Order Tracking

Location: web/app/plugins/suma-woo-order-tracking/ Version: 1.1.4 Author: Rhino Group Text Domain: suma-woo-order-tracking

---

Overview

The suma-woo-order-tracking plugin provides customers with an interactive order tracking page featuring a visual progress bar. It supports both logged-in customers and guests (by order number + email), and maps WooCommerce order statuses to human-readable tracking steps configured by the store admin.

---

File Structure

suma-woo-order-tracking/
├── init.php                     ← Main plugin bootstrap
├── bundle.php                   ← Optional bundled dependencies
├── readme.txt                   ← Plugin documentation
├── changelog.md                 ← Version history
├── package.json / webpack.mix.js ← Build configuration
├── inc/
│   ├── class-plugin.php         ← Main plugin orchestrator
│   ├── class-admin.php          ← WooCommerce settings registration
│   ├── class-frontend.php       ← Shortcode, My Account integration
│   └── class-wc-settings.php    ← Settings page implementation
├── lib/
│   └── plugin-update-checker/   ← Auto-update checker library
├── src/
│   ├── js/                      ← Source JavaScript
│   └── scss/                    ← Source SCSS
├── dist/
│   ├── css/admin.css
│   ├── css/frontend.css
│   └── js/admin.js
└── templates/
    ├── guest-form.php            ← Guest order lookup form
    ├── tracking-page.php         ← Main tracking display with progress bar
    └── tracking-disabled.php     ← Shown when tracking feature is disabled

---

PHP Classes

\Suma\OrderTracking\Plugin

The main plugin orchestrator.

Key responsibilities:

• Plugin activation: cleans up deprecated settings, flushes rewrite rules
• Plugin deactivation: cleanup
• Loads all other classes via run() method

namespace Suma\OrderTracking;

class Plugin {
    public function activate() : void { ... }
    public function deactivate() : void { ... }
    public function run() : void { ... }
    public function get_key() : string { ... }  // Option key prefix
    public function get_name() : string { ... } // Plugin display name
}

---

\Suma\OrderTracking\Admin

Manages the WordPress admin interface for order tracking configuration.

Key responsibilities:

• Registers the WooCommerce settings tab (WooCommerce → Settings → Order Tracking)
• Enqueues admin JavaScript and CSS (color picker, steps manager)
• Sanitizes and saves tracking step configuration

---

\Suma\OrderTracking\Frontend

Handles all front-end rendering and integration.

Key responsibilities:

• Enqueues dist/css/frontend.css on pages containing the tracking shortcode
• Registers the [suma_order_tracking] shortcode
• Adds a "Track Order" link to the My Account → Orders table

My Account integration:

// Adds tracking link to each order row in My Account → Orders
add_filter( 'woocommerce_my_account_my_orders_actions', [ $this, 'add_tracking_link_to_orders_table' ], 10, 2 );

---

\Suma\OrderTracking\WC_Settings

Extends WC_Settings_Page to create the WooCommerce settings tab.

Settings ID: order_tracking

Settings Fields:

Setting Key	Type	Description
show_tracking_link_order_table	Checkbox	Show tracking link in My Account → Orders table
enable_guest_access	Checkbox	Allow guests to look up orders via order number + email
tracking_path	Text	URL path to the tracking page (e.g., /track-order)
accent_color	Color picker	Primary progress bar color
complete_color	Color picker	Completed step color
guest_form_additional_content	WYSIWYG editor	Additional content shown on the guest lookup form

Tracking Steps Configuration:

Tracking steps are configured via a JSON-powered JavaScript UI in the settings page. Each step maps one or more WooCommerce order statuses to a display label:

[
  { "label": "Order Placed", "statuses": ["pending", "on-hold"] },
  { "label": "Payment Confirmed", "statuses": ["processing"] },
  { "label": "Shipped", "statuses": ["partial-shipped"] },
  { "label": "Delivered", "statuses": ["completed"] }
]

Steps are stored in the suma_order_tracking_steps option as a JSON array.

---

Shortcode: [suma_order_tracking]

Place this shortcode on the designated order tracking page (e.g., /track-order).

Behavior:

Scenario	Output
Guest, no order ID	Shows the guest order lookup form (guest-form.php)
Guest, submitted order + email	Validates and shows tracking for that order
Logged-in customer, no order ID	Shows their most recent orders with tracking links
Any user, ?order_id=123 in URL	Shows tracking page for order #123
Tracking feature disabled	Shows tracking-disabled.php message

Example page setup:

1. Create a WordPress page at /track-order
2. Add [suma_order_tracking] to the page content (or use an Elementor shortcode block)
3. Set the Tracking Path in WooCommerce → Settings → Order Tracking to /track-order

---

Templates

tracking-page.php

Renders the full tracking page including:

• Order summary header (order number, date, status)
• Visual progress bar showing current step
• Order items table
• Shipping information (populated via suma_order_tracking_shipping_info filter)

guest-form.php

Renders the guest lookup form with:

• Order number input
• Email address input
• Any additional content from guest_form_additional_content setting
• CSRF protection (WP nonce)

tracking-disabled.php

A simple message displayed when the tracking feature is disabled in WooCommerce settings.

---

WordPress Hooks

Actions

Hook	Description
admin_init	Registers admin settings
admin_enqueue_scripts	Loads admin CSS/JS (color picker, steps manager)
init	Registers plugin update checker

Filters

Hook	Description
woocommerce_get_settings_pages	Adds Order Tracking tab to WooCommerce settings
woocommerce_my_account_my_orders_actions	Adds tracking link to My Account → Orders table
woocommerce_settings_save_order_tracking	Runs save logic for settings

---

Extension Filters

suma_order_tracking_shipping_info

Inject shipping carrier and tracking information into the tracking page.

add_filter( 'suma_order_tracking_shipping_info', function( array $info, int $order_id ) : array {
    // Fetch tracking from ShipStation or your shipping plugin
    return [
        'carrier'      => 'FedEx',
        'tracking'     => '1234567890',
        'tracking_url' => 'https://www.fedex.com/apps/fedextrack/?tracknumbers=1234567890',
    ];
}, 10, 2 );

suma_order_tracking_table_columns

Customize the columns displayed in the order items table on the tracking page.

add_filter( 'suma_order_tracking_table_columns', function( array $columns, \WC_Order $order ) : array {
    $columns['weight'] = __( 'Weight', 'suma-woo-order-tracking' );
    return $columns;
}, 10, 2 );

do_action( 'suma_order_tracking_table_column_{column_id}', $item, $order )

Render custom column content:

add_action( 'suma_order_tracking_table_column_weight', function( $item, \WC_Order $order ) : void {
    echo esc_html( $item->get_meta( '_weight' ) . ' oz' );
}, 10, 2 );

---

Database Options

Option Key	Type	Description
suma_order_tracking_options	Array	General plugin settings
suma_order_tracking_steps	JSON string	Tracking step definitions
suma_order_pending_payment_email_sent	Order meta	Flag: pending payment email sent
suma_order_vault_email_sent	Order meta	Flag: vault storage email sent

---

Admin Interface Location

WooCommerce → Settings → Order Tracking (tab added by WC_Settings class)