WooNooW/examples/biteship-addon/README.md

# Biteship Shipping Addon - Example

This is a **complete example** of a WooNooW addon that integrates with the module system.

## Features Demonstrated

### 1. Module Registration
- Registers as a shipping module with icon, category, and features
- Appears in Settings > Modules automatically
- Shows gear icon for settings access

### 2. Two Settings Approaches

#### Option A: Schema-Based (No React Needed)
Uncomment the schema registration in `biteship-addon.php` and set `settings_component` to `null`.

**Benefits**:
- No build process required
- Automatic form generation
- Built-in validation
- Perfect for simple settings

#### Option B: Custom React Component (Current)
Uses `src/Settings.jsx` with WooNooW's exposed React API.

**Benefits**:
- Full UI control
- Custom validation logic
- Advanced interactions (like "Test Connection" button)
- Better for complex settings

### 3. Settings Persistence
Both approaches use the same storage:
- Stored in: `woonoow_module_biteship-shipping_settings`
- Accessed via: `get_option('woonoow_module_biteship-shipping_settings')`
- React hook: `useModuleSettings('biteship-shipping')`

### 4. Module Integration
- Hooks into `woonoow/shipping/calculate_rates` filter
- Checks if module is enabled before running
- Reacts to settings changes via action hook

## Installation

### Development Mode (No Build)

1. Copy this folder to `wp-content/plugins/`
2. Activate the plugin
3. Go to Settings > Modules
4. Enable "Biteship Shipping"
5. Click gear icon to configure

### Production Mode (With Build)

```bash
cd biteship-addon
npm install
npm run build
```

This compiles `src/Settings.jsx` to `dist/Settings.js`.

## File Structure

```
biteship-addon/
├── biteship-addon.php          # Main plugin file
├── src/
│   └── Settings.jsx            # Custom React settings component
├── dist/
│   └── Settings.js             # Compiled component (after build)
├── package.json                # Build configuration
└── README.md                   # This file
```

## Using WooNooW API

The custom settings component uses `window.WooNooW` API:

```javascript
const { React, hooks, components, icons, utils } = window.WooNooW;

// Hooks
const { useModuleSettings } = hooks;
const { settings, updateSettings } = useModuleSettings('biteship-shipping');

// Components
const { SettingsLayout, SettingsCard, Button, Input } = components;

// Icons
const { Save, Settings } = icons;

// Utils
const { toast, api } = utils;
```

## Build Configuration

```json
{
  "scripts": {
    "build": "esbuild src/Settings.jsx --bundle --outfile=dist/Settings.js --format=iife --external:react --external:react-dom"
  }
}
```

**Important**: Externalize React and React-DOM since WooNooW provides them!

## API Integration

The example shows placeholder shipping rates. In production:

1. Call Biteship API in `woonoow/shipping/calculate_rates` filter
2. Use settings from `get_option('woonoow_module_biteship-shipping_settings')`
3. Return formatted rates array

## Settings Schema Reference

```php
'field_name' => [
    'type' => 'text|textarea|email|url|number|toggle|checkbox|select',
    'label' => 'Field Label',
    'description' => 'Help text',
    'placeholder' => 'Placeholder text',
    'required' => true|false,
    'default' => 'default value',
    'options' => ['key' => 'Label'], // For select fields
    'min' => 0, // For number fields
    'max' => 100, // For number fields
]
```

## Module Registration Reference

```php
add_filter('woonoow/addon_registry', function($addons) {
    $addons['your-addon-id'] = [
        'id'           => 'your-addon-id',
        'name'         => 'Your Addon Name',
        'description'  => 'Short description',
        'version'      => '1.0.0',
        'author'       => 'Your Name',
        'category'     => 'shipping|payments|marketing|customers|products|analytics|other',
        'icon'         => 'truck|credit-card|mail|users|package|bar-chart-3|puzzle',
        'features'     => ['Feature 1', 'Feature 2'],
        'has_settings' => true,
        'settings_component' => plugin_dir_url(__FILE__) . 'dist/Settings.js', // Or null for schema
    ];
    return $addons;
});
```

## Testing

1. Enable the module in Settings > Modules
2. Click gear icon
3. Enter a test API key (format: `biteship_xxxxx`)
4. Click "Test Connection" button
5. Save settings
6. Check that settings persist on page refresh

## Next Steps

- Implement real Biteship API integration
- Add courier selection UI
- Add tracking number display
- Add shipping label generation
- Add webhook handling for status updates

## Support

For questions about WooNooW addon development:
- Read: `ADDON_DEVELOPMENT_GUIDE.md`
- Read: `ADDON_MODULE_DESIGN_DECISIONS.md`
- Check: `types/woonoow-addon.d.ts` for TypeScript definitions