feat: Implement Phase 2, 3, 4 - Module Settings System with Schema Forms and Addon API
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
175
examples/biteship-addon/README.md
Normal file
175
examples/biteship-addon/README.md
Normal 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
|
||||
Reference in New Issue
Block a user