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

296
includes/Api/ModuleSettingsController.php Normal file
View File

@@ -0,0 +1,296 @@
<?php
/**
* Module Settings REST API Controller
*
* Handles module-specific settings storage and retrieval
*
* @package WooNooW\Api
*/
namespace WooNooW\Api;
use WP_REST_Controller;
use WP_REST_Server;
use WP_REST_Request;
use WP_REST_Response;
use WP_Error;
use WooNooW\Core\ModuleRegistry;
class ModuleSettingsController extends WP_REST_Controller {
/**
* REST API namespace
*/
protected $namespace = 'woonoow/v1';
/**
* REST API base
*/
protected $rest_base = 'modules';
/**
* Register routes
*/
public function register_routes() {
// GET /woonoow/v1/modules/{module_id}/settings
register_rest_route($this->namespace, '/' . $this->rest_base . '/(?P<module_id>[a-zA-Z0-9_-]+)/settings', [
[
'methods' => WP_REST_Server::READABLE,
'callback' => [$this, 'get_settings'],
'permission_callback' => [$this, 'check_permission'],
'args' => [
'module_id' => [
'required' => true,
'type' => 'string',
'sanitize_callback' => 'sanitize_text_field',
],
],
],
]);
// POST /woonoow/v1/modules/{module_id}/settings
register_rest_route($this->namespace, '/' . $this->rest_base . '/(?P<module_id>[a-zA-Z0-9_-]+)/settings', [
[
'methods' => WP_REST_Server::CREATABLE,
'callback' => [$this, 'update_settings'],
'permission_callback' => [$this, 'check_permission'],
'args' => [
'module_id' => [
'required' => true,
'type' => 'string',
'sanitize_callback' => 'sanitize_text_field',
],
],
],
]);
// GET /woonoow/v1/modules/{module_id}/schema
register_rest_route($this->namespace, '/' . $this->rest_base . '/(?P<module_id>[a-zA-Z0-9_-]+)/schema', [
[
'methods' => WP_REST_Server::READABLE,
'callback' => [$this, 'get_schema'],
'permission_callback' => [$this, 'check_permission'],
'args' => [
'module_id' => [
'required' => true,
'type' => 'string',
'sanitize_callback' => 'sanitize_text_field',
],
],
],
]);
}
/**
* Check permission
*
* @return bool
*/
public function check_permission() {
return current_user_can('manage_options');
}
/**
* Get module settings
*
* @param WP_REST_Request $request
* @return WP_REST_Response|WP_Error
*/
public function get_settings($request) {
$module_id = $request['module_id'];
// Verify module exists
$modules = ModuleRegistry::get_all_modules();
if (!isset($modules[$module_id])) {
return new WP_Error(
'invalid_module',
__('Invalid module ID', 'woonoow'),
['status' => 404]
);
}
// Get settings from database
$settings = get_option("woonoow_module_{$module_id}_settings", []);
// Apply defaults from schema if available
$schema = apply_filters('woonoow/module_settings_schema', []);
if (isset($schema[$module_id])) {
$defaults = $this->get_schema_defaults($schema[$module_id]);
$settings = wp_parse_args($settings, $defaults);
}
return new WP_REST_Response($settings, 200);
}
/**
* Update module settings
*
* @param WP_REST_Request $request
* @return WP_REST_Response|WP_Error
*/
public function update_settings($request) {
$module_id = $request['module_id'];
$new_settings = $request->get_json_params();
// Verify module exists
$modules = ModuleRegistry::get_all_modules();
if (!isset($modules[$module_id])) {
return new WP_Error(
'invalid_module',
__('Invalid module ID', 'woonoow'),
['status' => 404]
);
}
// Validate against schema if available
$schema = apply_filters('woonoow/module_settings_schema', []);
if (isset($schema[$module_id])) {
$validated = $this->validate_settings($new_settings, $schema[$module_id]);
if (is_wp_error($validated)) {
return $validated;
}
$new_settings = $validated;
}
// Save settings
update_option("woonoow_module_{$module_id}_settings", $new_settings);
// Allow addons to react to settings changes
do_action("woonoow/module_settings_updated/{$module_id}", $new_settings);
do_action('woonoow/module_settings_updated', $module_id, $new_settings);
return rest_ensure_response([
'success' => true,
'message' => __('Settings saved successfully', 'woonoow'),
'settings' => $new_settings,
], 200);
}
/**
* Get settings schema for a module
*
* @param WP_REST_Request $request
* @return WP_REST_Response|WP_Error
*/
public function get_schema($request) {
$module_id = $request['module_id'];
// Verify module exists
$modules = ModuleRegistry::get_all_modules();
if (!isset($modules[$module_id])) {
return new WP_Error(
'invalid_module',
__('Invalid module ID', 'woonoow'),
['status' => 404]
);
}
// Get schema from filter
$all_schemas = apply_filters('woonoow/module_settings_schema', []);
$schema = $all_schemas[$module_id] ?? null;
if (!$schema) {
return new WP_REST_Response([
'schema' => null,
'message' => __('No schema available for this module', 'woonoow'),
], 200);
}
return new WP_REST_Response([
'schema' => $schema,
], 200);
}
/**
* Get default values from schema
*
* @param array $schema
* @return array
*/
private function get_schema_defaults($schema) {
$defaults = [];
foreach ($schema as $key => $field) {
if (isset($field['default'])) {
$defaults[$key] = $field['default'];
}
}
return $defaults;
}
/**
* Validate settings against schema
*
* @param array $settings
* @param array $schema
* @return array|WP_Error
*/
private function validate_settings($settings, $schema) {
$validated = [];
$errors = [];
foreach ($schema as $key => $field) {
$value = $settings[$key] ?? null;
// Check required fields
if (!empty($field['required']) && ($value === null || $value === '')) {
$errors[$key] = sprintf(
__('%s is required', 'woonoow'),
$field['label'] ?? $key
);
continue;
}
// Skip validation if value is null and not required
if ($value === null) {
continue;
}
// Type validation
$type = $field['type'] ?? 'text';
switch ($type) {
case 'text':
case 'textarea':
case 'email':
case 'url':
$validated[$key] = sanitize_text_field($value);
break;
case 'number':
$validated[$key] = floatval($value);
break;
case 'toggle':
case 'checkbox':
$validated[$key] = (bool) $value;
break;
case 'select':
// Validate against allowed options
if (isset($field['options']) && !isset($field['options'][$value])) {
$errors[$key] = sprintf(
__('Invalid value for %s', 'woonoow'),
$field['label'] ?? $key
);
} else {
$validated[$key] = sanitize_text_field($value);
}
break;
default:
$validated[$key] = $value;
}
}
if (!empty($errors)) {
return new WP_Error(
'validation_failed',
__('Settings validation failed', 'woonoow'),
['status' => 400, 'errors' => $errors]
);
}
return $validated;
}
}

18
includes/Api/ModulesController.php
View File

@@ -86,24 +86,20 @@ class ModulesController extends WP_REST_Controller {
*/
public function get_modules($request) {
$modules = ModuleRegistry::get_all_with_status();
$grouped = ModuleRegistry::get_grouped_modules();
// Group by category
$grouped = [
'marketing' => [],
'customers' => [],
'products' => [],
];
foreach ($modules as $module) {
$category = $module['category'];
if (isset($grouped[$category])) {
$grouped[$category][] = $module;
// Add enabled status to grouped modules
$enabled_modules = ModuleRegistry::get_enabled_modules();
foreach ($grouped as $category => &$category_modules) {
foreach ($category_modules as &$module) {
$module['enabled'] = in_array($module['id'], $enabled_modules);
}
}
return new WP_REST_Response([
'modules' => $modules,
'grouped' => $grouped,
'categories' => ModuleRegistry::get_categories(),
], 200);
}

5
includes/Api/Routes.php
View File

@@ -22,6 +22,7 @@ use WooNooW\Api\CouponsController;
use WooNooW\Api\CustomersController;
use WooNooW\Api\NewsletterController;
use WooNooW\Api\ModulesController;
use WooNooW\Api\ModuleSettingsController;
use WooNooW\Frontend\ShopController;
use WooNooW\Frontend\CartController as FrontendCartController;
use WooNooW\Frontend\AccountController;
@@ -128,6 +129,10 @@ class Routes {
$modules_controller = new ModulesController();
$modules_controller->register_routes();
// Module Settings controller
$module_settings_controller = new ModuleSettingsController();
$module_settings_controller->register_routes();
// Frontend controllers (customer-facing)
ShopController::register_routes();
FrontendCartController::register_routes();

118
includes/Core/ModuleRegistry.php
View File

@@ -13,11 +13,11 @@ namespace WooNooW\Core;
class ModuleRegistry {
/**
* Get all registered modules
* Get built-in modules
*
* @return array
*/
public static function get_all_modules() {
private static function get_builtin_modules() {
$modules = [
'newsletter' => [
'id' => 'newsletter',
@@ -26,6 +26,7 @@ class ModuleRegistry {
'category' => 'marketing',
'icon' => 'mail',
'default_enabled' => true,
'has_settings' => true,
'features' => [
__('Subscriber management', 'woonoow'),
__('Email campaigns', 'woonoow'),
@@ -89,7 +90,118 @@ class ModuleRegistry {
],
];
return apply_filters('woonoow/modules/registry', $modules);
return $modules;
}
/**
* Get addon modules from AddonRegistry
*
* @return array
*/
private static function get_addon_modules() {
$addons = apply_filters('woonoow/addon_registry', []);
$modules = [];
foreach ($addons as $addon_id => $addon) {
$modules[$addon_id] = [
'id' => $addon_id,
'label' => $addon['name'] ?? ucfirst($addon_id),
'description' => $addon['description'] ?? '',
'category' => $addon['category'] ?? 'other',
'icon' => $addon['icon'] ?? 'puzzle',
'default_enabled' => false,
'features' => $addon['features'] ?? [],
'is_addon' => true,
'version' => $addon['version'] ?? '1.0.0',
'author' => $addon['author'] ?? '',
'has_settings' => !empty($addon['has_settings']),
'settings_component' => $addon['settings_component'] ?? null,
];
}
return $modules;
}
/**
* Get all modules (built-in + addons)
*
* @return array
*/
public static function get_all_modules() {
$builtin = self::get_builtin_modules();
$addons = self::get_addon_modules();
return array_merge($builtin, $addons);
}
/**
* Get categories dynamically from registered modules
*
* @return array Associative array of category_id => label
*/
public static function get_categories() {
$all_modules = self::get_all_modules();
$categories = [];
// Extract unique categories from modules
foreach ($all_modules as $module) {
$cat = $module['category'] ?? 'other';
if (!isset($categories[$cat])) {
$categories[$cat] = self::get_category_label($cat);
}
}
// Sort by predefined order
$order = ['marketing', 'customers', 'products', 'shipping', 'payments', 'analytics', 'other'];
uksort($categories, function($a, $b) use ($order) {
$pos_a = array_search($a, $order);
$pos_b = array_search($b, $order);
if ($pos_a === false) $pos_a = 999;
if ($pos_b === false) $pos_b = 999;
return $pos_a - $pos_b;
});
return $categories;
}
/**
* Get human-readable label for category
*
* @param string $category Category ID
* @return string
*/
private static function get_category_label($category) {
$labels = [
'marketing' => __('Marketing & Sales', 'woonoow'),
'customers' => __('Customer Experience', 'woonoow'),
'products' => __('Products & Inventory', 'woonoow'),
'shipping' => __('Shipping & Fulfillment', 'woonoow'),
'payments' => __('Payments & Checkout', 'woonoow'),
'analytics' => __('Analytics & Reports', 'woonoow'),
'other' => __('Other Extensions', 'woonoow'),
];
return $labels[$category] ?? ucfirst($category);
}
/**
* Group modules by category
*
* @return array
*/
public static function get_grouped_modules() {
$all_modules = self::get_all_modules();
$grouped = [];
foreach ($all_modules as $module) {
$cat = $module['category'] ?? 'other';
if (!isset($grouped[$cat])) {
$grouped[$cat] = [];
}
$grouped[$cat][] = $module;
}
return $grouped;
}
/**

96
includes/Modules/NewsletterSettings.php Normal file
View File

@@ -0,0 +1,96 @@
<?php
/**
* Newsletter Module Settings Schema
*
* Example of schema-based settings for the Newsletter module
*
* @package WooNooW\Modules
*/
namespace WooNooW\Modules;
class NewsletterSettings {
public static function init() {
// Register settings schema
add_filter('woonoow/module_settings_schema', [__CLASS__, 'register_schema']);
}
/**
* Register newsletter settings schema
*/
public static function register_schema($schemas) {
$schemas['newsletter'] = [
'sender_name' => [
'type' => 'text',
'label' => __('Sender Name', 'woonoow'),
'description' => __('The name that appears in the "From" field of newsletter emails', 'woonoow'),
'placeholder' => get_bloginfo('name'),
'default' => get_bloginfo('name'),
'required' => true,
],
'sender_email' => [
'type' => 'email',
'label' => __('Sender Email', 'woonoow'),
'description' => __('The email address that appears in the "From" field', 'woonoow'),
'placeholder' => get_option('admin_email'),
'default' => get_option('admin_email'),
'required' => true,
],
'reply_to_email' => [
'type' => 'email',
'label' => __('Reply-To Email', 'woonoow'),
'description' => __('Email address for replies (leave empty to use sender email)', 'woonoow'),
'placeholder' => get_option('admin_email'),
],
'double_opt_in' => [
'type' => 'toggle',
'label' => __('Double Opt-In', 'woonoow'),
'description' => __('Require subscribers to confirm their email address before being added to the list', 'woonoow'),
'default' => true,
],
'welcome_email' => [
'type' => 'toggle',
'label' => __('Send Welcome Email', 'woonoow'),
'description' => __('Automatically send a welcome email to new subscribers', 'woonoow'),
'default' => true,
],
'unsubscribe_page' => [
'type' => 'select',
'label' => __('Unsubscribe Page', 'woonoow'),
'description' => __('Page to redirect users after unsubscribing', 'woonoow'),
'placeholder' => __('-- Select Page --', 'woonoow'),
'options' => self::get_pages_options(),
],
'gdpr_consent' => [
'type' => 'toggle',
'label' => __('GDPR Consent Checkbox', 'woonoow'),
'description' => __('Show a consent checkbox on subscription forms (recommended for EU compliance)', 'woonoow'),
'default' => false,
],
'consent_text' => [
'type' => 'textarea',
'label' => __('Consent Text', 'woonoow'),
'description' => __('Text shown next to the consent checkbox', 'woonoow'),
'placeholder' => __('I agree to receive marketing emails', 'woonoow'),
'default' => __('I agree to receive marketing emails and understand I can unsubscribe at any time.', 'woonoow'),
],
];
return $schemas;
}
/**
* Get pages as options for select field
*/
private static function get_pages_options() {
$pages = get_pages();
$options = [];
foreach ($pages as $page) {
$options[$page->ID] = $page->post_title;
}
return $options;
}
}