WooNooW/ADDON_BRIDGE_PATTERN.md

Addon Bridge Pattern - Rajaongkir Example

Philosophy

WooNooW Core = Zero Addon Dependencies

We don't integrate specific addons into WooNooW core. Instead, we provide:

1. Hook system for addons to extend functionality
2. Bridge snippets for compatibility with existing plugins
3. Addon development guide for building proper WooNooW addons

---

Problem: Rajaongkir Plugin

Rajaongkir is a WooCommerce plugin that:

• Removes standard address fields (city, state)
• Adds custom destination dropdown
• Stores data in WooCommerce session
• Works on WooCommerce checkout page

It doesn't work with WooNooW OrderForm because:

• OrderForm uses standard WooCommerce fields
• Rajaongkir expects session-based destination
• No destination = No shipping calculation

---

Solution: Bridge Snippet (Not Core Integration!)

Option A: Standalone Bridge Plugin

Create a tiny bridge plugin that makes Rajaongkir work with WooNooW:

<?php
/**
 * Plugin Name: WooNooW Rajaongkir Bridge
 * Description: Makes Rajaongkir plugin work with WooNooW OrderForm
 * Version: 1.0.0
 * Requires: WooNooW, Rajaongkir Official
 */

// Hook into WooNooW's shipping calculation
add_filter('woonoow_before_shipping_calculate', function($shipping_data) {
    // If Indonesia and has city, convert to Rajaongkir destination
    if ($shipping_data['country'] === 'ID' && !empty($shipping_data['city'])) {
        // Search Rajaongkir API for destination
        $api = Cekongkir_API::get_instance();
        $results = $api->search_destination_api($shipping_data['city']);
        
        if (!empty($results[0])) {
            // Set Rajaongkir session data
            WC()->session->set('selected_destination_id', $results[0]['id']);
            WC()->session->set('selected_destination_label', $results[0]['text']);
        }
    }
    
    return $shipping_data;
});

// Add Rajaongkir destination field to OrderForm via hook system
add_action('wp_enqueue_scripts', function() {
    if (!is_admin()) return;
    
    wp_enqueue_script(
        'woonoow-rajaongkir-bridge',
        plugin_dir_url(__FILE__) . 'dist/bridge.js',
        ['woonoow-admin'],
        '1.0.0',
        true
    );
});

Frontend (bridge.js):

import { addonLoader, addFilter } from '@woonoow/hooks';

addonLoader.register({
  id: 'rajaongkir-bridge',
  name: 'Rajaongkir Bridge',
  version: '1.0.0',
  init: () => {
    // Add destination search field after shipping address
    addFilter('woonoow_order_form_after_shipping', (content, formData, setFormData) => {
      // Only for Indonesia
      if (formData.shipping?.country !== 'ID') return content;
      
      return (
        <>
          {content}
          <div className="border rounded-lg p-4 mt-4">
            <h3 className="font-medium mb-3">📍 Shipping Destination</h3>
            <RajaongkirDestinationSearch
              value={formData.shipping?.destination_id}
              onChange={(id, label) => {
                setFormData({
                  ...formData,
                  shipping: {
                    ...formData.shipping,
                    destination_id: id,
                    destination_label: label,
                  }
                });
              }}
            />
          </div>
        </>
      );
    });
  }
});

Option B: Code Snippet (No Plugin)

For users who don't want a separate plugin, provide a code snippet:

// Add to theme's functions.php or custom plugin

// Bridge Rajaongkir with WooNooW
add_filter('woonoow_shipping_data', function($data) {
    if ($data['country'] === 'ID' && !empty($data['city'])) {
        // Auto-search and set destination
        $api = Cekongkir_API::get_instance();
        $results = $api->search_destination_api($data['city']);
        if (!empty($results[0])) {
            WC()->session->set('selected_destination_id', $results[0]['id']);
        }
    }
    return $data;
});

---

Proper Solution: Build WooNooW Addon

Instead of bridging Rajaongkir, build a proper WooNooW addon:

WooNooW Indonesia Shipping Addon

<?php
/**
 * Plugin Name: WooNooW Indonesia Shipping
 * Description: Indonesia shipping with Rajaongkir API
 * Version: 1.0.0
 * Requires: WooNooW 1.0.0+
 */

// Register addon
add_filter('woonoow/addon_registry', function($addons) {
    $addons['indonesia-shipping'] = [
        'id'           => 'indonesia-shipping',
        'name'         => 'Indonesia Shipping',
        'version'      => '1.0.0',
        'spa_bundle'   => plugin_dir_url(__FILE__) . 'dist/addon.js',
        'dependencies' => ['woocommerce' => '8.0'],
    ];
    return $addons;
});

// Add API endpoints
add_action('rest_api_init', function() {
    register_rest_route('woonoow/v1', '/indonesia/search-destination', [
        'methods' => 'GET',
        'callback' => function($req) {
            $query = $req->get_param('query');
            $api = new RajaongkirAPI(get_option('rajaongkir_api_key'));
            return $api->searchDestination($query);
        },
    ]);
    
    register_rest_route('woonoow/v1', '/indonesia/calculate-shipping', [
        'methods' => 'POST',
        'callback' => function($req) {
            $origin = $req->get_param('origin');
            $destination = $req->get_param('destination');
            $weight = $req->get_param('weight');
            
            $api = new RajaongkirAPI(get_option('rajaongkir_api_key'));
            return $api->calculateShipping($origin, $destination, $weight);
        },
    ]);
});

Frontend:

// dist/addon.ts

import { addonLoader, addFilter } from '@woonoow/hooks';
import { DestinationSearch } from './components/DestinationSearch';

addonLoader.register({
  id: 'indonesia-shipping',
  name: 'Indonesia Shipping',
  version: '1.0.0',
  init: () => {
    // Add destination field
    addFilter('woonoow_order_form_after_shipping', (content, formData, setFormData) => {
      if (formData.shipping?.country !== 'ID') return content;
      
      return (
        <>
          {content}
          <DestinationSearch
            value={formData.shipping?.destination_id}
            onChange={(id, label) => {
              setFormData({
                ...formData,
                shipping: { ...formData.shipping, destination_id: id, destination_label: label }
              });
            }}
          />
        </>
      );
    });
    
    // Add validation
    addFilter('woonoow_order_form_validation', (errors, formData) => {
      if (formData.shipping?.country === 'ID' && !formData.shipping?.destination_id) {
        errors.destination = 'Please select shipping destination';
      }
      return errors;
    });
  }
});

---

Comparison

Bridge Snippet (Quick Fix)

✅ Works immediately ✅ No new plugin needed ✅ Minimal code ❌ Depends on Rajaongkir plugin ❌ Limited features ❌ Not ideal UX

Proper WooNooW Addon (Best Practice)

✅ Native WooNooW integration ✅ Better UX ✅ More features ✅ Independent of Rajaongkir plugin ✅ Can use any shipping API ❌ More development effort ❌ Separate plugin to maintain

---

Recommendation

For WooNooW Core:

• ❌ Don't integrate Rajaongkir
• ✅ Provide hook system
• ✅ Document bridge pattern
• ✅ Provide code snippets

For Users:

• Quick fix: Use bridge snippet
• Best practice: Build proper addon or use community addon

For Community:

• Build "WooNooW Indonesia Shipping" addon
• Publish on WordPress.org
• Support Rajaongkir, Biteship, and other Indonesian shipping APIs

---

Hook Points Needed in WooNooW Core

To support addons like this, WooNooW core should provide:

// Before shipping calculation
apply_filters('woonoow_before_shipping_calculate', $shipping_data);

// After shipping calculation
apply_filters('woonoow_after_shipping_calculate', $rates, $shipping_data);

// Modify shipping data
apply_filters('woonoow_shipping_data', $data);

// Frontend hooks
'woonoow_order_form_after_shipping'
'woonoow_order_form_shipping_fields'
'woonoow_order_form_validation'
'woonoow_order_form_submit'

These hooks already exist in our addon system!

---

Conclusion

WooNooW Core = Zero addon dependencies

Instead of integrating Rajaongkir into core:

1. Provide hook system ✅ (Already done)
2. Document bridge pattern ✅ (This document)
3. Encourage community addons ✅

This keeps WooNooW core:

• Clean
• Maintainable
• Flexible
• Extensible

Users can choose:

• Bridge snippet (quick fix)
• Proper addon (best practice)
• Build their own

No bloat in core!