Module Registry

Register custom modules and addons with WooNooW's unified module system

WooNooW's modular architecture allows developers to create custom modules and addons that integrate seamlessly with the Settings > Modules UI.

Overview

The Module Registry provides a unified system for:

  • Enable/disable toggle in the admin UI
  • Custom settings with schema-based forms
  • Dependencies on other modules
  • SPA route registration for custom settings pages

Registering a Module

Add your module using the woonoow/modules/registry filter:

php
add_filter('woonoow/modules/registry', 'my_plugin_register_module');

function my_plugin_register_module($modules) {
    $modules['my-module'] = [
        'id'          => 'my-module',
        'name'        => __('My Custom Module', 'my-plugin'),
        'description' => __('Description of what this module does.', 'my-plugin'),
        'icon'        => 'Sparkles', // Lucide icon name
        'category'    => 'marketing', // marketing, sales, developer, etc.
        'requires'    => [], // Array of required module IDs
        'settings'    => [], // Settings schema array
    ];
    
    return $modules;
}

Module Properties

PropertyTypeRequiredDescription
idstringYesUnique identifier (lowercase, hyphens)
namestringYesDisplay name in the UI
descriptionstringYesBrief description of functionality
iconstringNoLucide icon name (e.g., Package, Mail)
categorystringNoGrouping category: marketing, sales, developer
requiresarrayNoArray of module IDs this depends on
settingsarrayNoSettings schema for module configuration

Settings Schema

Define a settings schema to allow users to configure your module:

php
'settings' => [
    [
        'id'          => 'api_key',
        'type'        => 'text',
        'label'       => __('API Key', 'my-plugin'),
        'description' => __('Enter your API key', 'my-plugin'),
        'default'     => '',
    ],
    [
        'id'          => 'rate_limit',
        'type'        => 'number',
        'label'       => __('Rate Limit', 'my-plugin'),
        'description' => __('Max requests per minute', 'my-plugin'),
        'default'     => 10,
        'min'         => 1,
        'max'         => 100,
    ],
    [
        'id'          => 'enable_debug',
        'type'        => 'toggle',
        'label'       => __('Enable Debug Mode', 'my-plugin'),
        'default'     => false,
    ],
],

Available Field Types

TypeDescriptionProperties
textSingle-line text inputdefault, placeholder
textareaMulti-line text inputdefault, rows
numberNumeric input with validationdefault, min, max, step
toggleBoolean on/off switchdefault (true/false)
selectDropdown selectiondefault, options (array of {value, label})
checkboxSingle checkboxdefault (true/false)
colorColor pickerdefault (#hex value)
urlURL input with validationdefault, placeholder
emailEmail input with validationdefault, placeholder
passwordPassword input (masked)default

Common Field Properties

PropertyTypeDescription
idstringUnique field identifier
typestringField type from list above
labelstringDisplay label
descriptionstringHelp text below field
defaultmixedDefault value

Select Field Example

php
[
    'id'      => 'display_mode',
    'type'    => 'select',
    'label'   => __('Display Mode', 'my-plugin'),
    'default' => 'grid',
    'options' => [
        ['value' => 'grid', 'label' => __('Grid', 'my-plugin')],
        ['value' => 'list', 'label' => __('List', 'my-plugin')],
        ['value' => 'carousel', 'label' => __('Carousel', 'my-plugin')],
    ],
],

Checking Module Status

Use ModuleRegistry::is_enabled() to check if your module is active:

php
use WooNooW\Core\ModuleRegistry;

if (ModuleRegistry::is_enabled('my-module')) {
    // Module is enabled, initialize features
    My_Module_Manager::init();
}

Module Lifecycle Events

Hook into module enable/disable events:

php
// When any module is enabled
add_action('woonoow/module/enabled', function($module_id) {
    if ($module_id === 'my-module') {
        // Create database tables, initialize settings, etc.
        My_Module_Manager::install();
    }
});

// When any module is disabled
add_action('woonoow/module/disabled', function($module_id) {
    if ($module_id === 'my-module') {
        // Cleanup if necessary
    }
});

SPA Routes for Settings Pages

Addons can register custom React settings pages:

php
add_filter('woonoow/spa_routes', function($routes) {
    $routes[] = [
        'path'          => '/settings/my-addon',
        'component_url' => plugin_dir_url(__FILE__) . 'dist/Settings.js',
        'title'         => 'My Addon Settings',
    ];
    return $routes;
});

Addon Registry (External Addons)

External addons can also register via woonoow/addon_registry for extended metadata:

php
add_filter('woonoow/addon_registry', function($addons) {
    $addons['my-shipping-addon'] = [
        'id'           => 'my-shipping-addon',
        'name'         => 'My Shipping',
        'description'  => 'Custom shipping integration',
        'version'      => '1.0.0',
        'author'       => 'My Company',
        'category'     => 'shipping',
        'icon'         => 'truck',
        'settings_url' => '/settings/shipping/my-addon',
        'spa_bundle'   => plugin_dir_url(__FILE__) . 'dist/addon.js',
    ];
    return $addons;
});

Complete Example

php
<?php
namespace MyPlugin;

class MyModuleSettings {
    
    public static function init() {
        add_filter('woonoow/modules/registry', [__CLASS__, 'register']);
    }
    
    public static function register($modules) {
        $modules['my-module'] = [
            'id'          => 'my-module',
            'name'        => __('My Module', 'my-plugin'),
            'description' => __('Adds awesome features to your store.', 'my-plugin'),
            'icon'        => 'Zap',
            'category'    => 'marketing',
            'requires'    => [], // No dependencies
            'settings'    => [
                [
                    'id'      => 'feature_enabled',
                    'type'    => 'toggle',
                    'label'   => __('Enable Feature', 'my-plugin'),
                    'default' => true,
                ],
            ],
        ];
        
        return $modules;
    }
}

// Initialize on plugins_loaded
add_action('plugins_loaded', ['MyPlugin\MyModuleSettings', 'init']);

Best Practices

  1. Check module status before loading heavy features
  2. Use the woonoow/module/enabled hook to run installation routines only when needed
  3. Specify dependencies so WooNooW can prompt users to enable required modules
  4. Provide meaningful descriptions to help users understand what each module does

Last updated Dec 12, 2025