dwindown/WooNooW
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Implement Phase 2, 3, 4 - Module Settings System with Schema Forms and Addon API

Browse Source 
Phase 2: Schema-Based Form System
- Add ModuleSettingsController with GET/POST/schema endpoints
- Create SchemaField component supporting 8 field types (text, textarea, email, url, number, toggle, checkbox, select)
- Create SchemaForm component for automatic form generation from schema
- Add ModuleSettings page with dynamic routing (/settings/modules/:moduleId)
- Add useModuleSettings React hook for settings management
- Implement NewsletterSettings as example with 8 configurable fields
- Add has_settings flag to module registry
- Settings stored as woonoow_module_{module_id}_settings

Phase 3: Advanced Features
- Create windowAPI.ts exposing React, hooks, components, icons, utils to addons via window.WooNooW
- Add DynamicComponentLoader for loading external React components
- Create TypeScript definitions (woonoow-addon.d.ts) for addon developers
- Initialize Window API in App.tsx on mount
- Enable custom React components for addon settings pages

Phase 4: Production Polish & Example
- Create complete Biteship addon example demonstrating both approaches:
  * Schema-based settings (no build required)
  * Custom React component (with build)
- Add comprehensive README with installation and testing guide
- Include package.json with esbuild configuration
- Demonstrate window.WooNooW API usage in custom component

Bug Fixes:
- Fix footer newsletter form visibility (remove redundant module check)
- Fix footer contact_data and social_links not saving (parameter name mismatch: snake_case vs camelCase)
- Fix useModules hook returning undefined (remove .data wrapper, add fallback)
- Add optional chaining to footer settings rendering
- Fix TypeScript errors in woonoow-addon.d.ts (use any for external types)

Files Added (15):
- includes/Api/ModuleSettingsController.php
- includes/Modules/NewsletterSettings.php
- admin-spa/src/components/forms/SchemaField.tsx
- admin-spa/src/components/forms/SchemaForm.tsx
- admin-spa/src/routes/Settings/ModuleSettings.tsx
- admin-spa/src/hooks/useModuleSettings.ts
- admin-spa/src/lib/windowAPI.ts
- admin-spa/src/components/DynamicComponentLoader.tsx
- types/woonoow-addon.d.ts
- examples/biteship-addon/biteship-addon.php
- examples/biteship-addon/src/Settings.jsx
- examples/biteship-addon/package.json
- examples/biteship-addon/README.md
- PHASE_2_3_4_SUMMARY.md

Files Modified (11):
- admin-spa/src/App.tsx
- admin-spa/src/hooks/useModules.ts
- admin-spa/src/routes/Appearance/Footer.tsx
- admin-spa/src/routes/Settings/Modules.tsx
- customer-spa/src/hooks/useModules.ts
- customer-spa/src/layouts/BaseLayout.tsx
- customer-spa/src/components/NewsletterForm.tsx
- includes/Api/Routes.php
- includes/Api/ModulesController.php
- includes/Core/ModuleRegistry.php
- woonoow.php

API Endpoints Added:
- GET /woonoow/v1/modules/{module_id}/settings
- POST /woonoow/v1/modules/{module_id}/settings
- GET /woonoow/v1/modules/{module_id}/schema

For Addon Developers:
- Schema-based: Define settings via woonoow/module_settings_schema filter
- Custom React: Build component using window.WooNooW API, externalize react/react-dom
- Both approaches use same storage and retrieval methods
- TypeScript definitions provided for type safety
- Complete working example (Biteship) included
This commit is contained in:
Dwindi Ramadhana
2025-12-26 21:16:06 +07:00
parent 07020bc0dd
commit c6cef97ef8
25 changed files with 2512 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
examples/biteship-addon/README.md Normal file
View File

@@ -0,0 +1,175 @@
# 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

177
examples/biteship-addon/biteship-addon.php Normal file
View File

@@ -0,0 +1,177 @@
<?php
/**
* Plugin Name: WooNooW Biteship Shipping
* Plugin URI: https://woonoow.com/addons/biteship
* Description: Indonesia shipping integration with Biteship API - Example WooNooW Addon
* Version: 1.0.0
* Author: WooNooW Team
* Author URI: https://woonoow.com
* Requires Plugins: woonoow
*
* This is an EXAMPLE addon demonstrating the WooNooW module system integration.
* It shows both schema-based settings AND custom React component patterns.
*/
if (!defined('ABSPATH')) exit;
/**
* Register Biteship as a WooNooW Module
*/
add_filter('woonoow/addon_registry', function($addons) {
$addons['biteship-shipping'] = [
'id' => 'biteship-shipping',
'name' => 'Biteship Shipping',
'description' => 'Real-time shipping rates from Indonesian couriers (JNE, J&T, SiCepat, and more)',
'version' => '1.0.0',
'author' => 'WooNooW Team',
'category' => 'shipping',
'icon' => 'truck',
'features' => [
'Real-time shipping rates',
'Multiple courier support (JNE, J&T, SiCepat, AnterAja, Ninja Express)',
'Automatic tracking integration',
'Shipping label generation',
'Cash on Delivery (COD) support',
],
'has_settings' => true,
// Option 1: Use schema-based settings (uncomment to use)
// 'settings_component' => null,
// Option 2: Use custom React component (current)
'settings_component' => plugin_dir_url(__FILE__) . 'dist/Settings.js',
];
return $addons;
});
/**
* Register Settings Schema (Option 1: Schema-based)
*
* This provides a no-code settings form automatically
*/
add_filter('woonoow/module_settings_schema', function($schemas) {
$schemas['biteship-shipping'] = [
'api_key' => [
'type' => 'text',
'label' => __('Biteship API Key', 'biteship'),
'description' => __('Get your API key from Biteship dashboard', 'biteship'),
'placeholder' => 'biteship_xxxxxxxxxxxxx',
'required' => true,
],
'environment' => [
'type' => 'select',
'label' => __('Environment', 'biteship'),
'description' => __('Use test mode for development', 'biteship'),
'options' => [
'test' => __('Test Mode', 'biteship'),
'production' => __('Production', 'biteship'),
],
'default' => 'test',
],
'origin_lat' => [
'type' => 'text',
'label' => __('Origin Latitude', 'biteship'),
'description' => __('Your warehouse latitude coordinate', 'biteship'),
'placeholder' => '-6.200000',
],
'origin_lng' => [
'type' => 'text',
'label' => __('Origin Longitude', 'biteship'),
'description' => __('Your warehouse longitude coordinate', 'biteship'),
'placeholder' => '106.816666',
],
'enable_cod' => [
'type' => 'toggle',
'label' => __('Enable Cash on Delivery', 'biteship'),
'description' => __('Allow customers to pay on delivery', 'biteship'),
'default' => false,
],
'enable_insurance' => [
'type' => 'toggle',
'label' => __('Enable Shipping Insurance', 'biteship'),
'description' => __('Automatically add insurance to shipments', 'biteship'),
'default' => true,
],
'enabled_couriers' => [
'type' => 'select',
'label' => __('Enabled Couriers', 'biteship'),
'description' => __('Select which couriers to show to customers', 'biteship'),
'options' => [
'jne' => 'JNE',
'jnt' => 'J&T Express',
'sicepat' => 'SiCepat',
'anteraja' => 'AnterAja',
'ninja' => 'Ninja Express',
'idexpress' => 'ID Express',
],
],
'debug_mode' => [
'type' => 'toggle',
'label' => __('Debug Mode', 'biteship'),
'description' => __('Log API requests for troubleshooting', 'biteship'),
'default' => false,
],
];
return $schemas;
});
/**
* Hook into WooNooW shipping calculation
*
* This is where the actual shipping logic would go
*/
add_filter('woonoow/shipping/calculate_rates', function($rates, $package) {
// Check if module is enabled
if (!class_exists('WooNooW\Core\ModuleRegistry')) {
return $rates;
}
if (!\WooNooW\Core\ModuleRegistry::is_enabled('biteship-shipping')) {
return $rates;
}
// Get settings
$settings = get_option('woonoow_module_biteship-shipping_settings', []);
if (empty($settings['api_key'])) {
return $rates;
}
// TODO: Call Biteship API to get real rates
// For now, return example rates
$rates[] = [
'id' => 'biteship_jne_reg',
'label' => 'JNE Regular',
'cost' => 15000,
'meta_data' => [
'courier' => 'JNE',
'service' => 'REG',
'etd' => '2-3 days',
],
];
$rates[] = [
'id' => 'biteship_jnt_reg',
'label' => 'J&T Express Regular',
'cost' => 12000,
'meta_data' => [
'courier' => 'J&T',
'service' => 'REG',
'etd' => '2-4 days',
],
];
return $rates;
}, 10, 2);
/**
* React to settings changes
*/
add_action('woonoow/module_settings_updated/biteship-shipping', function($settings) {
// Clear any caches
delete_transient('biteship_courier_list');
// Log settings update in debug mode
if (!empty($settings['debug_mode'])) {
error_log('Biteship settings updated: ' . print_r($settings, true));
}
});

15
examples/biteship-addon/package.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "woonoow-biteship-addon",
"version": "1.0.0",
"description": "Biteship shipping integration for WooNooW",
"scripts": {
"build": "esbuild src/Settings.jsx --bundle --outfile=dist/Settings.js --format=iife --external:react --external:react-dom --minify",
"dev": "esbuild src/Settings.jsx --bundle --outfile=dist/Settings.js --format=iife --external:react --external:react-dom --watch"
},
"devDependencies": {
"esbuild": "^0.19.0"
},
"keywords": ["woonoow", "addon", "shipping", "biteship", "indonesia"],
"author": "WooNooW Team",
"license": "GPL-2.0-or-later"
}

202
examples/biteship-addon/src/Settings.jsx Normal file
View File

@@ -0,0 +1,202 @@
/**
* Biteship Custom Settings Component
*
* This demonstrates how to create a custom React settings page for a WooNooW addon
* using the exposed window.WooNooW API
*/
// Access WooNooW API from window
const { React, hooks, components, icons, utils } = window.WooNooW;
const { useModuleSettings } = hooks;
const { SettingsLayout, SettingsCard, Input, Button, Switch, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Badge } = components;
const { Settings: SettingsIcon, Save, AlertCircle, Check } = icons;
const { toast } = utils;
function BiteshipSettings() {
const { settings, isLoading, updateSettings } = useModuleSettings('biteship-shipping');
const [formData, setFormData] = React.useState({});
const [testingConnection, setTestingConnection] = React.useState(false);
const [connectionStatus, setConnectionStatus] = React.useState(null);
// Initialize form data from settings
React.useEffect(() => {
if (settings) {
setFormData(settings);
}
}, [settings]);
const handleChange = (key, value) => {
setFormData(prev => ({ ...prev, [key]: value }));
};
const handleSave = () => {
updateSettings.mutate(formData);
};
const testConnection = async () => {
if (!formData.api_key) {
toast.error('Please enter an API key first');
return;
}
setTestingConnection(true);
setConnectionStatus(null);
// Simulate API test (in real addon, call Biteship API)
setTimeout(() => {
const isValid = formData.api_key.startsWith('biteship_');
setConnectionStatus(isValid ? 'success' : 'error');
setTestingConnection(false);
if (isValid) {
toast.success('Connection successful!');
} else {
toast.error('Invalid API key format');
}
}, 1500);
};
if (isLoading) {
return React.createElement(SettingsLayout, { title: 'Biteship Settings', isLoading: true });
}
return React.createElement(SettingsLayout, {
title: 'Biteship Shipping Settings',
description: 'Configure your Biteship integration for Indonesian shipping'
},
// API Configuration Card
React.createElement(SettingsCard, {
title: 'API Configuration',
description: 'Connect your Biteship account'
},
React.createElement('div', { className: 'space-y-4' },
// API Key
React.createElement('div', { className: 'space-y-2' },
React.createElement('label', { className: 'text-sm font-medium' }, 'API Key'),
React.createElement('div', { className: 'flex gap-2' },
React.createElement(Input, {
type: 'password',
value: formData.api_key || '',
onChange: (e) => handleChange('api_key', e.target.value),
placeholder: 'biteship_xxxxxxxxxxxxx'
}),
React.createElement(Button, {
variant: 'outline',
onClick: testConnection,
disabled: testingConnection
}, testingConnection ? 'Testing...' : 'Test Connection')
),
connectionStatus && React.createElement('div', {
className: `flex items-center gap-2 text-sm ${connectionStatus === 'success' ? 'text-green-600' : 'text-red-600'}`
},
React.createElement(connectionStatus === 'success' ? Check : AlertCircle, { className: 'h-4 w-4' }),
connectionStatus === 'success' ? 'Connection successful' : 'Connection failed'
)
),
// Environment
React.createElement('div', { className: 'space-y-2' },
React.createElement('label', { className: 'text-sm font-medium' }, 'Environment'),
React.createElement(Select, {
value: formData.environment || 'test',
onValueChange: (value) => handleChange('environment', value)
},
React.createElement(SelectTrigger, null,
React.createElement(SelectValue, null)
),
React.createElement(SelectContent, null,
React.createElement(SelectItem, { value: 'test' }, 'Test Mode'),
React.createElement(SelectItem, { value: 'production' }, 'Production')
)
),
React.createElement('p', { className: 'text-xs text-muted-foreground' },
'Use test mode for development and testing'
)
)
)
),
// Origin Location Card
React.createElement(SettingsCard, {
title: 'Origin Location',
description: 'Your warehouse or pickup location'
},
React.createElement('div', { className: 'grid grid-cols-2 gap-4' },
React.createElement('div', { className: 'space-y-2' },
React.createElement('label', { className: 'text-sm font-medium' }, 'Latitude'),
React.createElement(Input, {
value: formData.origin_lat || '',
onChange: (e) => handleChange('origin_lat', e.target.value),
placeholder: '-6.200000'
})
),
React.createElement('div', { className: 'space-y-2' },
React.createElement('label', { className: 'text-sm font-medium' }, 'Longitude'),
React.createElement(Input, {
value: formData.origin_lng || '',
onChange: (e) => handleChange('origin_lng', e.target.value),
placeholder: '106.816666'
})
)
)
),
// Features Card
React.createElement(SettingsCard, {
title: 'Features',
description: 'Enable or disable shipping features'
},
React.createElement('div', { className: 'space-y-4' },
// COD
React.createElement('div', { className: 'flex items-center justify-between' },
React.createElement('div', null,
React.createElement('p', { className: 'font-medium' }, 'Cash on Delivery'),
React.createElement('p', { className: 'text-sm text-muted-foreground' }, 'Allow customers to pay on delivery')
),
React.createElement(Switch, {
checked: formData.enable_cod || false,
onCheckedChange: (checked) => handleChange('enable_cod', checked)
})
),
// Insurance
React.createElement('div', { className: 'flex items-center justify-between' },
React.createElement('div', null,
React.createElement('p', { className: 'font-medium' }, 'Shipping Insurance'),
React.createElement('p', { className: 'text-sm text-muted-foreground' }, 'Automatically add insurance to shipments')
),
React.createElement(Switch, {
checked: formData.enable_insurance !== false,
onCheckedChange: (checked) => handleChange('enable_insurance', checked)
})
),
// Debug Mode
React.createElement('div', { className: 'flex items-center justify-between' },
React.createElement('div', null,
React.createElement('p', { className: 'font-medium' }, 'Debug Mode'),
React.createElement('p', { className: 'text-sm text-muted-foreground' }, 'Log API requests for troubleshooting')
),
React.createElement(Switch, {
checked: formData.debug_mode || false,
onCheckedChange: (checked) => handleChange('debug_mode', checked)
})
)
)
),
// Save Button
React.createElement('div', { className: 'flex justify-end' },
React.createElement(Button, {
onClick: handleSave,
disabled: updateSettings.isPending
},
React.createElement(Save, { className: 'mr-2 h-4 w-4' }),
updateSettings.isPending ? 'Saving...' : 'Save Settings'
)
)
);
}
// Export component to global scope for WooNooW to load
window.WooNooWAddon_biteship_shipping = BiteshipSettings;