@mytechtoday/augment-extensions 0.1.1 → 0.2.0

package/augment-extensions/domain-rules/wordpress-plugin/examples/settings-page-plugin.md

@@ -0,0 +1,1350 @@
+# Settings Page Plugin Example
+
+## Overview
+
+This example demonstrates a complete **Settings Page Plugin** with admin menu, settings registration, sections, fields, validation, sanitization, and proper security implementation.
+
+**Complexity**: Medium  
+**File Count**: 5-10 files  
+**Team Size**: 1-2 developers  
+**Use Case**: Plugin configuration, site settings, feature toggles, API integrations
+
+---
+
+## Complete Plugin: "Site Settings Manager"
+
+A comprehensive settings management plugin demonstrating WordPress Settings API, custom admin pages, field types, validation, and security best practices.
+
+---
+
+## Directory Structure
+
+```
+site-settings-manager/
+├── site-settings-manager.php          # Main plugin file
+├── uninstall.php                      # Uninstall cleanup
+├── readme.txt                         # WordPress.org readme
+├── includes/
+│   ├── class-settings-page.php        # Settings page class
+│   ├── class-settings-fields.php      # Field rendering
+│   └── class-settings-validator.php   # Validation logic
+├── admin/
+│   ├── css/
+│   │   └── admin.css                  # Admin styles
+│   ├── js/
+│   │   └── admin.js                   # Admin scripts
+│   └── views/
+│       ├── settings-page.php          # Main settings view
+│       └── settings-sidebar.php       # Sidebar view
+└── assets/
+    └── images/
+        └── icon.png                   # Plugin icon
+```
+
+---
+
+## Main Plugin File
+
+### File: `site-settings-manager.php`
+
+```php
+<?php
+/**
+ * Plugin Name: Site Settings Manager
+ * Plugin URI: https://example.com/site-settings-manager
+ * Description: Complete settings management with validation, sanitization, and security
+ * Version: 1.0.0
+ * Author: Your Name
+ * Author URI: https://example.com
+ * License: GPL-2.0+
+ * License URI: http://www.gnu.org/licenses/gpl-2.0.txt
+ * Text Domain: site-settings-manager
+ * Domain Path: /languages
+ *
+ * @package Site_Settings_Manager
+ */
+
+// Exit if accessed directly
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+// Define plugin constants
+define('SSM_VERSION', '1.0.0');
+define('SSM_PLUGIN_DIR', plugin_dir_path(__FILE__));
+define('SSM_PLUGIN_URL', plugin_dir_url(__FILE__));
+define('SSM_PLUGIN_FILE', __FILE__);
+
+/**
+ * Autoloader
+ */
+spl_autoload_register(function ($class) {
+    $prefix = 'SSM_';
+    
+    if (strpos($class, $prefix) !== 0) {
+        return;
+    }
+    
+    $class_name = str_replace($prefix, '', $class);
+    $class_file = 'class-' . str_replace('_', '-', strtolower($class_name)) . '.php';
+    
+    $file = SSM_PLUGIN_DIR . 'includes/' . $class_file;
+    if (file_exists($file)) {
+        require $file;
+    }
+});
+
+/**
+ * Activation hook
+ */
+register_activation_hook(__FILE__, function() {
+    // Set default options
+    $defaults = array(
+        'ssm_site_title'       => get_bloginfo('name'),
+        'ssm_site_description' => get_bloginfo('description'),
+        'ssm_enable_feature'   => false,
+        'ssm_api_key'          => '',
+        'ssm_items_per_page'   => 10,
+        'ssm_theme_color'      => '#0073aa',
+    );
+    
+    foreach ($defaults as $key => $value) {
+        if (get_option($key) === false) {
+            add_option($key, $value);
+        }
+    }
+});
+
+/**
+ * Deactivation hook
+ */
+register_deactivation_hook(__FILE__, function() {
+    // Cleanup if needed
+});
+
+/**
+ * Initialize the plugin
+ */
+function run_site_settings_manager() {
+    // Initialize settings page
+    if (is_admin()) {
+        SSM_Settings_Page::init();
+    }
+    
+    // Load text domain
+    add_action('plugins_loaded', 'ssm_load_textdomain');
+    
+    // Enqueue admin assets
+    add_action('admin_enqueue_scripts', 'ssm_enqueue_admin_assets');
+}
+add_action('plugins_loaded', 'run_site_settings_manager');
+
+/**
+ * Load plugin text domain
+ */
+function ssm_load_textdomain() {
+    load_plugin_textdomain(
+        'site-settings-manager',
+        false,
+        dirname(plugin_basename(SSM_PLUGIN_FILE)) . '/languages/'
+    );
+}
+
+/**
+ * Enqueue admin assets
+ */
+function ssm_enqueue_admin_assets($hook) {
+    // Only load on our settings page
+    if ('settings_page_site-settings-manager' !== $hook) {
+        return;
+    }
+    
+    wp_enqueue_style(
+        'ssm-admin',
+        SSM_PLUGIN_URL . 'admin/css/admin.css',
+        array(),
+        SSM_VERSION
+    );
+    
+    wp_enqueue_script(
+        'ssm-admin',
+        SSM_PLUGIN_URL . 'admin/js/admin.js',
+        array('jquery', 'wp-color-picker'),
+        SSM_VERSION,
+        true
+    );
+    
+    // Enqueue color picker
+    wp_enqueue_style('wp-color-picker');
+}
+```
+
+---
+
+## Settings Page Class
+
+### File: `includes/class-settings-page.php`
+
+```php
+<?php
+/**
+ * Settings page class
+ *
+ * @package Site_Settings_Manager
+ */
+
+class SSM_Settings_Page {
+    /**
+     * Settings page slug
+     */
+    const PAGE_SLUG = 'site-settings-manager';
+    
+    /**
+     * Option group
+     */
+    const OPTION_GROUP = 'ssm_settings_group';
+    
+    /**
+     * Initialize
+     */
+    public static function init() {
+        add_action('admin_menu', array(__CLASS__, 'add_admin_menu'));
+        add_action('admin_init', array(__CLASS__, 'register_settings'));
+    }
+
+    /**
+     * Add admin menu
+     */
+    public static function add_admin_menu() {
+        add_options_page(
+            __('Site Settings Manager', 'site-settings-manager'),
+            __('Site Settings', 'site-settings-manager'),
+            'manage_options',
+            self::PAGE_SLUG,
+            array(__CLASS__, 'render_settings_page')
+        );
+    }
+
+    /**
+     * Register settings
+     */
+    public static function register_settings() {
+        // Register settings
+        register_setting(
+            self::OPTION_GROUP,
+            'ssm_site_title',
+            array(
+                'type'              => 'string',
+                'sanitize_callback' => 'sanitize_text_field',
+                'default'           => '',
+            )
+        );
+
+        register_setting(
+            self::OPTION_GROUP,
+            'ssm_site_description',
+            array(
+                'type'              => 'string',
+                'sanitize_callback' => 'sanitize_textarea_field',
+                'default'           => '',
+            )
+        );
+
+        register_setting(
+            self::OPTION_GROUP,
+            'ssm_enable_feature',
+            array(
+                'type'              => 'boolean',
+                'sanitize_callback' => array(__CLASS__, 'sanitize_checkbox'),
+                'default'           => false,
+            )
+        );
+
+        register_setting(
+            self::OPTION_GROUP,
+            'ssm_api_key',
+            array(
+                'type'              => 'string',
+                'sanitize_callback' => array(__CLASS__, 'sanitize_api_key'),
+                'default'           => '',
+            )
+        );
+
+        register_setting(
+            self::OPTION_GROUP,
+            'ssm_items_per_page',
+            array(
+                'type'              => 'integer',
+                'sanitize_callback' => array(__CLASS__, 'sanitize_items_per_page'),
+                'default'           => 10,
+            )
+        );
+
+        register_setting(
+            self::OPTION_GROUP,
+            'ssm_theme_color',
+            array(
+                'type'              => 'string',
+                'sanitize_callback' => 'sanitize_hex_color',
+                'default'           => '#0073aa',
+            )
+        );
+
+        register_setting(
+            self::OPTION_GROUP,
+            'ssm_email_notifications',
+            array(
+                'type'              => 'string',
+                'sanitize_callback' => array(__CLASS__, 'sanitize_email_list'),
+                'default'           => '',
+            )
+        );
+
+        // Add settings sections
+        add_settings_section(
+            'ssm_general_section',
+            __('General Settings', 'site-settings-manager'),
+            array(__CLASS__, 'render_general_section'),
+            self::PAGE_SLUG
+        );
+
+        add_settings_section(
+            'ssm_api_section',
+            __('API Settings', 'site-settings-manager'),
+            array(__CLASS__, 'render_api_section'),
+            self::PAGE_SLUG
+        );
+
+        add_settings_section(
+            'ssm_display_section',
+            __('Display Settings', 'site-settings-manager'),
+            array(__CLASS__, 'render_display_section'),
+            self::PAGE_SLUG
+        );
+
+        // Add settings fields - General Section
+        add_settings_field(
+            'ssm_site_title',
+            __('Site Title', 'site-settings-manager'),
+            array('SSM_Settings_Fields', 'render_text_field'),
+            self::PAGE_SLUG,
+            'ssm_general_section',
+            array(
+                'label_for'   => 'ssm_site_title',
+                'option_name' => 'ssm_site_title',
+                'description' => __('Enter your site title', 'site-settings-manager'),
+            )
+        );
+
+        add_settings_field(
+            'ssm_site_description',
+            __('Site Description', 'site-settings-manager'),
+            array('SSM_Settings_Fields', 'render_textarea_field'),
+            self::PAGE_SLUG,
+            'ssm_general_section',
+            array(
+                'label_for'   => 'ssm_site_description',
+                'option_name' => 'ssm_site_description',
+                'description' => __('Enter your site description', 'site-settings-manager'),
+                'rows'        => 4,
+            )
+        );
+
+        add_settings_field(
+            'ssm_enable_feature',
+            __('Enable Feature', 'site-settings-manager'),
+            array('SSM_Settings_Fields', 'render_checkbox_field'),
+            self::PAGE_SLUG,
+            'ssm_general_section',
+            array(
+                'label_for'   => 'ssm_enable_feature',
+                'option_name' => 'ssm_enable_feature',
+                'description' => __('Enable this feature', 'site-settings-manager'),
+            )
+        );
+
+        // Add settings fields - API Section
+        add_settings_field(
+            'ssm_api_key',
+            __('API Key', 'site-settings-manager'),
+            array('SSM_Settings_Fields', 'render_password_field'),
+            self::PAGE_SLUG,
+            'ssm_api_section',
+            array(
+                'label_for'   => 'ssm_api_key',
+                'option_name' => 'ssm_api_key',
+                'description' => __('Enter your API key', 'site-settings-manager'),
+            )
+        );
+
+        add_settings_field(
+            'ssm_email_notifications',
+            __('Email Notifications', 'site-settings-manager'),
+            array('SSM_Settings_Fields', 'render_text_field'),
+            self::PAGE_SLUG,
+            'ssm_api_section',
+            array(
+                'label_for'   => 'ssm_email_notifications',
+                'option_name' => 'ssm_email_notifications',
+                'description' => __('Comma-separated email addresses', 'site-settings-manager'),
+            )
+        );
+
+        // Add settings fields - Display Section
+        add_settings_field(
+            'ssm_items_per_page',
+            __('Items Per Page', 'site-settings-manager'),
+            array('SSM_Settings_Fields', 'render_number_field'),
+            self::PAGE_SLUG,
+            'ssm_display_section',
+            array(
+                'label_for'   => 'ssm_items_per_page',
+                'option_name' => 'ssm_items_per_page',
+                'description' => __('Number of items to display per page', 'site-settings-manager'),
+                'min'         => 1,
+                'max'         => 100,
+            )
+        );
+
+        add_settings_field(
+            'ssm_theme_color',
+            __('Theme Color', 'site-settings-manager'),
+            array('SSM_Settings_Fields', 'render_color_field'),
+            self::PAGE_SLUG,
+            'ssm_display_section',
+            array(
+                'label_for'   => 'ssm_theme_color',
+                'option_name' => 'ssm_theme_color',
+                'description' => __('Choose your theme color', 'site-settings-manager'),
+            )
+        );
+    }
+
+    /**
+     * Render general section
+     */
+    public static function render_general_section() {
+        echo '<p>' . esc_html__('Configure general site settings.', 'site-settings-manager') . '</p>';
+    }
+
+    /**
+     * Render API section
+     */
+    public static function render_api_section() {
+        echo '<p>' . esc_html__('Configure API and integration settings.', 'site-settings-manager') . '</p>';
+    }
+
+    /**
+     * Render display section
+     */
+    public static function render_display_section() {
+        echo '<p>' . esc_html__('Configure display and appearance settings.', 'site-settings-manager') . '</p>';
+    }
+
+    /**
+     * Sanitize checkbox
+     */
+    public static function sanitize_checkbox($value) {
+        return $value ? true : false;
+    }
+
+    /**
+     * Sanitize API key
+     */
+    public static function sanitize_api_key($value) {
+        $value = sanitize_text_field($value);
+
+        // Validate API key format (example: alphanumeric, 32 characters)
+        if (!empty($value) && !preg_match('/^[a-zA-Z0-9]{32}$/', $value)) {
+            add_settings_error(
+                'ssm_api_key',
+                'invalid_api_key',
+                __('API key must be 32 alphanumeric characters.', 'site-settings-manager'),
+                'error'
+            );
+            return get_option('ssm_api_key'); // Return old value
+        }
+
+        return $value;
+    }
+
+    /**
+     * Sanitize items per page
+     */
+    public static function sanitize_items_per_page($value) {
+        $value = intval($value);
+
+        if ($value < 1 || $value > 100) {
+            add_settings_error(
+                'ssm_items_per_page',
+                'invalid_items_per_page',
+                __('Items per page must be between 1 and 100.', 'site-settings-manager'),
+                'error'
+            );
+            return get_option('ssm_items_per_page'); // Return old value
+        }
+
+        return $value;
+    }
+
+    /**
+     * Sanitize email list
+     */
+    public static function sanitize_email_list($value) {
+        $emails = array_map('trim', explode(',', $value));
+        $valid_emails = array();
+
+        foreach ($emails as $email) {
+            if (is_email($email)) {
+                $valid_emails[] = $email;
+            }
+        }
+
+        if (count($emails) !== count($valid_emails)) {
+            add_settings_error(
+                'ssm_email_notifications',
+                'invalid_emails',
+                __('Some email addresses are invalid and were removed.', 'site-settings-manager'),
+                'warning'
+            );
+        }
+
+        return implode(', ', $valid_emails);
+    }
+
+    /**
+     * Render settings page
+     */
+    public static function render_settings_page() {
+        // Check user capabilities
+        if (!current_user_can('manage_options')) {
+            wp_die(__('You do not have sufficient permissions to access this page.', 'site-settings-manager'));
+        }
+
+        // Include the view
+        include SSM_PLUGIN_DIR . 'admin/views/settings-page.php';
+    }
+}
+```
+
+---
+
+## Settings Fields Class
+
+### File: `includes/class-settings-fields.php`
+
+```php
+<?php
+/**
+ * Settings fields rendering
+ *
+ * @package Site_Settings_Manager
+ */
+
+class SSM_Settings_Fields {
+    /**
+     * Render text field
+     */
+    public static function render_text_field($args) {
+        $option_name = $args['option_name'];
+        $value = get_option($option_name, '');
+        $description = isset($args['description']) ? $args['description'] : '';
+
+        printf(
+            '<input type="text" id="%s" name="%s" value="%s" class="regular-text">',
+            esc_attr($args['label_for']),
+            esc_attr($option_name),
+            esc_attr($value)
+        );
+
+        if ($description) {
+            printf('<p class="description">%s</p>', esc_html($description));
+        }
+    }
+
+    /**
+     * Render textarea field
+     */
+    public static function render_textarea_field($args) {
+        $option_name = $args['option_name'];
+        $value = get_option($option_name, '');
+        $description = isset($args['description']) ? $args['description'] : '';
+        $rows = isset($args['rows']) ? intval($args['rows']) : 5;
+
+        printf(
+            '<textarea id="%s" name="%s" rows="%d" class="large-text">%s</textarea>',
+            esc_attr($args['label_for']),
+            esc_attr($option_name),
+            $rows,
+            esc_textarea($value)
+        );
+
+        if ($description) {
+            printf('<p class="description">%s</p>', esc_html($description));
+        }
+    }
+
+    /**
+     * Render checkbox field
+     */
+    public static function render_checkbox_field($args) {
+        $option_name = $args['option_name'];
+        $value = get_option($option_name, false);
+        $description = isset($args['description']) ? $args['description'] : '';
+
+        printf(
+            '<label><input type="checkbox" id="%s" name="%s" value="1" %s> %s</label>',
+            esc_attr($args['label_for']),
+            esc_attr($option_name),
+            checked($value, true, false),
+            esc_html($description)
+        );
+    }
+
+    /**
+     * Render password field
+     */
+    public static function render_password_field($args) {
+        $option_name = $args['option_name'];
+        $value = get_option($option_name, '');
+        $description = isset($args['description']) ? $args['description'] : '';
+
+        printf(
+            '<input type="password" id="%s" name="%s" value="%s" class="regular-text">',
+            esc_attr($args['label_for']),
+            esc_attr($option_name),
+            esc_attr($value)
+        );
+
+        if ($description) {
+            printf('<p class="description">%s</p>', esc_html($description));
+        }
+    }
+
+    /**
+     * Render number field
+     */
+    public static function render_number_field($args) {
+        $option_name = $args['option_name'];
+        $value = get_option($option_name, '');
+        $description = isset($args['description']) ? $args['description'] : '';
+        $min = isset($args['min']) ? intval($args['min']) : '';
+        $max = isset($args['max']) ? intval($args['max']) : '';
+
+        printf(
+            '<input type="number" id="%s" name="%s" value="%s" min="%s" max="%s" class="small-text">',
+            esc_attr($args['label_for']),
+            esc_attr($option_name),
+            esc_attr($value),
+            esc_attr($min),
+            esc_attr($max)
+        );
+
+        if ($description) {
+            printf('<p class="description">%s</p>', esc_html($description));
+        }
+    }
+
+    /**
+     * Render color field
+     */
+    public static function render_color_field($args) {
+        $option_name = $args['option_name'];
+        $value = get_option($option_name, '#0073aa');
+        $description = isset($args['description']) ? $args['description'] : '';
+
+        printf(
+            '<input type="text" id="%s" name="%s" value="%s" class="ssm-color-picker">',
+            esc_attr($args['label_for']),
+            esc_attr($option_name),
+            esc_attr($value)
+        );
+
+        if ($description) {
+            printf('<p class="description">%s</p>', esc_html($description));
+        }
+    }
+
+    /**
+     * Render select field
+     */
+    public static function render_select_field($args) {
+        $option_name = $args['option_name'];
+        $value = get_option($option_name, '');
+        $description = isset($args['description']) ? $args['description'] : '';
+        $options = isset($args['options']) ? $args['options'] : array();
+
+        printf('<select id="%s" name="%s">', esc_attr($args['label_for']), esc_attr($option_name));
+
+        foreach ($options as $option_value => $option_label) {
+            printf(
+                '<option value="%s" %s>%s</option>',
+                esc_attr($option_value),
+                selected($value, $option_value, false),
+                esc_html($option_label)
+            );
+        }
+
+        echo '</select>';
+
+        if ($description) {
+            printf('<p class="description">%s</p>', esc_html($description));
+        }
+    }
+
+    /**
+     * Render radio field
+     */
+    public static function render_radio_field($args) {
+        $option_name = $args['option_name'];
+        $value = get_option($option_name, '');
+        $description = isset($args['description']) ? $args['description'] : '';
+        $options = isset($args['options']) ? $args['options'] : array();
+
+        foreach ($options as $option_value => $option_label) {
+            printf(
+                '<label><input type="radio" name="%s" value="%s" %s> %s</label><br>',
+                esc_attr($option_name),
+                esc_attr($option_value),
+                checked($value, $option_value, false),
+                esc_html($option_label)
+            );
+        }
+
+        if ($description) {
+            printf('<p class="description">%s</p>', esc_html($description));
+        }
+    }
+}
+```
+
+---
+
+## View Files
+
+### File: `admin/views/settings-page.php`
+
+```php
+<?php
+/**
+ * Settings page view
+ *
+ * @package Site_Settings_Manager
+ */
+
+// Exit if accessed directly
+if (!defined('ABSPATH')) {
+    exit;
+}
+?>
+
+<div class="wrap ssm-settings-wrap">
+    <h1><?php echo esc_html(get_admin_page_title()); ?></h1>
+
+    <?php settings_errors(); ?>
+
+    <div class="ssm-settings-container">
+        <div class="ssm-settings-main">
+            <form method="post" action="options.php">
+                <?php
+                settings_fields(SSM_Settings_Page::OPTION_GROUP);
+                do_settings_sections(SSM_Settings_Page::PAGE_SLUG);
+                submit_button(__('Save Settings', 'site-settings-manager'));
+                ?>
+            </form>
+        </div>
+
+        <div class="ssm-settings-sidebar">
+            <?php include SSM_PLUGIN_DIR . 'admin/views/settings-sidebar.php'; ?>
+        </div>
+    </div>
+</div>
+```
+
+### File: `admin/views/settings-sidebar.php`
+
+```php
+<?php
+/**
+ * Settings sidebar view
+ *
+ * @package Site_Settings_Manager
+ */
+
+// Exit if accessed directly
+if (!defined('ABSPATH')) {
+    exit;
+}
+?>
+
+<div class="ssm-sidebar-box">
+    <h3><?php _e('About This Plugin', 'site-settings-manager'); ?></h3>
+    <p><?php _e('Site Settings Manager provides a comprehensive settings interface for your WordPress site.', 'site-settings-manager'); ?></p>
+</div>
+
+<div class="ssm-sidebar-box">
+    <h3><?php _e('Documentation', 'site-settings-manager'); ?></h3>
+    <ul>
+        <li><a href="#" target="_blank"><?php _e('Getting Started', 'site-settings-manager'); ?></a></li>
+        <li><a href="#" target="_blank"><?php _e('API Documentation', 'site-settings-manager'); ?></a></li>
+        <li><a href="#" target="_blank"><?php _e('Support Forum', 'site-settings-manager'); ?></a></li>
+    </ul>
+</div>
+
+<div class="ssm-sidebar-box">
+    <h3><?php _e('System Info', 'site-settings-manager'); ?></h3>
+    <table class="ssm-info-table">
+        <tr>
+            <td><?php _e('Plugin Version:', 'site-settings-manager'); ?></td>
+            <td><?php echo esc_html(SSM_VERSION); ?></td>
+        </tr>
+        <tr>
+            <td><?php _e('WordPress Version:', 'site-settings-manager'); ?></td>
+            <td><?php echo esc_html(get_bloginfo('version')); ?></td>
+        </tr>
+        <tr>
+            <td><?php _e('PHP Version:', 'site-settings-manager'); ?></td>
+            <td><?php echo esc_html(PHP_VERSION); ?></td>
+        </tr>
+    </table>
+</div>
+
+<div class="ssm-sidebar-box ssm-support-box">
+    <h3><?php _e('Need Help?', 'site-settings-manager'); ?></h3>
+    <p><?php _e('If you need assistance, please visit our support forum.', 'site-settings-manager'); ?></p>
+    <a href="#" class="button button-primary" target="_blank">
+        <?php _e('Get Support', 'site-settings-manager'); ?>
+    </a>
+</div>
+```
+
+---
+
+## Assets
+
+### File: `admin/css/admin.css`
+
+```css
+/* Settings Page Layout */
+.ssm-settings-wrap {
+    margin: 20px 20px 0 0;
+}
+
+.ssm-settings-container {
+    display: flex;
+    gap: 30px;
+    margin-top: 20px;
+}
+
+.ssm-settings-main {
+    flex: 1;
+    background: #fff;
+    padding: 20px;
+    border: 1px solid #ccd0d4;
+    box-shadow: 0 1px 1px rgba(0, 0, 0, 0.04);
+}
+
+.ssm-settings-sidebar {
+    width: 300px;
+    flex-shrink: 0;
+}
+
+@media (max-width: 1024px) {
+    .ssm-settings-container {
+        flex-direction: column;
+    }
+
+    .ssm-settings-sidebar {
+        width: 100%;
+    }
+}
+
+/* Settings Sections */
+.ssm-settings-main h2 {
+    margin-top: 0;
+    padding-bottom: 10px;
+    border-bottom: 1px solid #e0e0e0;
+}
+
+.ssm-settings-main .form-table {
+    margin-top: 20px;
+}
+
+.ssm-settings-main .form-table th {
+    padding: 15px 10px 15px 0;
+    width: 200px;
+}
+
+.ssm-settings-main .form-table td {
+    padding: 15px 10px;
+}
+
+/* Sidebar Boxes */
+.ssm-sidebar-box {
+    background: #fff;
+    padding: 20px;
+    margin-bottom: 20px;
+    border: 1px solid #ccd0d4;
+    box-shadow: 0 1px 1px rgba(0, 0, 0, 0.04);
+}
+
+.ssm-sidebar-box h3 {
+    margin-top: 0;
+    margin-bottom: 15px;
+    font-size: 14px;
+    font-weight: 600;
+}
+
+.ssm-sidebar-box p {
+    margin: 0 0 15px;
+    font-size: 13px;
+    line-height: 1.6;
+}
+
+.ssm-sidebar-box ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.ssm-sidebar-box ul li {
+    margin-bottom: 8px;
+}
+
+.ssm-sidebar-box ul li a {
+    text-decoration: none;
+    font-size: 13px;
+}
+
+.ssm-sidebar-box ul li a:hover {
+    text-decoration: underline;
+}
+
+/* Info Table */
+.ssm-info-table {
+    width: 100%;
+    font-size: 13px;
+}
+
+.ssm-info-table tr {
+    border-bottom: 1px solid #f0f0f0;
+}
+
+.ssm-info-table tr:last-child {
+    border-bottom: none;
+}
+
+.ssm-info-table td {
+    padding: 8px 0;
+}
+
+.ssm-info-table td:first-child {
+    font-weight: 600;
+    width: 50%;
+}
+
+/* Support Box */
+.ssm-support-box {
+    background: #f7f7f7;
+    border-left: 4px solid #0073aa;
+}
+
+.ssm-support-box .button {
+    width: 100%;
+    text-align: center;
+    margin-top: 10px;
+}
+
+/* Color Picker */
+.ssm-color-picker {
+    max-width: 100px;
+}
+
+/* Success/Error Messages */
+.ssm-settings-wrap .notice {
+    margin: 20px 0;
+}
+```
+
+### File: `admin/js/admin.js`
+
+```javascript
+(function($) {
+    'use strict';
+
+    $(document).ready(function() {
+        // Initialize color picker
+        if (typeof $.fn.wpColorPicker !== 'undefined') {
+            $('.ssm-color-picker').wpColorPicker();
+        }
+
+        // Form validation
+        $('form').on('submit', function(e) {
+            var isValid = true;
+
+            // Validate API key if present
+            var apiKey = $('#ssm_api_key').val();
+            if (apiKey && !/^[a-zA-Z0-9]{32}$/.test(apiKey)) {
+                alert('API key must be 32 alphanumeric characters.');
+                isValid = false;
+            }
+
+            // Validate items per page
+            var itemsPerPage = parseInt($('#ssm_items_per_page').val());
+            if (itemsPerPage < 1 || itemsPerPage > 100) {
+                alert('Items per page must be between 1 and 100.');
+                isValid = false;
+            }
+
+            if (!isValid) {
+                e.preventDefault();
+            }
+        });
+
+        // Show/hide conditional fields
+        $('#ssm_enable_feature').on('change', function() {
+            if ($(this).is(':checked')) {
+                $('.conditional-field').slideDown();
+            } else {
+                $('.conditional-field').slideUp();
+            }
+        }).trigger('change');
+    });
+
+})(jQuery);
+```
+
+---
+
+## Uninstall
+
+### File: `uninstall.php`
+
+```php
+<?php
+/**
+ * Uninstall script
+ *
+ * @package Site_Settings_Manager
+ */
+
+// Exit if accessed directly or not uninstalling
+if (!defined('WP_UNINSTALL_PLUGIN')) {
+    exit;
+}
+
+// Delete all plugin options
+$options = array(
+    'ssm_site_title',
+    'ssm_site_description',
+    'ssm_enable_feature',
+    'ssm_api_key',
+    'ssm_items_per_page',
+    'ssm_theme_color',
+    'ssm_email_notifications',
+);
+
+foreach ($options as $option) {
+    delete_option($option);
+}
+
+// Clear any cached data
+wp_cache_flush();
+```
+
+---
+
+## Usage Examples
+
+### Accessing Settings in Your Code
+
+```php
+<?php
+// Get individual settings
+$site_title = get_option('ssm_site_title', '');
+$enable_feature = get_option('ssm_enable_feature', false);
+$items_per_page = get_option('ssm_items_per_page', 10);
+$theme_color = get_option('ssm_theme_color', '#0073aa');
+
+// Use settings
+if ($enable_feature) {
+    // Feature is enabled
+    echo '<h1>' . esc_html($site_title) . '</h1>';
+}
+
+// Use in queries
+$args = array(
+    'posts_per_page' => $items_per_page,
+);
+$query = new WP_Query($args);
+?>
+```
+
+### Programmatically Update Settings
+
+```php
+<?php
+// Update settings
+update_option('ssm_site_title', 'New Site Title');
+update_option('ssm_enable_feature', true);
+update_option('ssm_items_per_page', 20);
+
+// Get and modify
+$emails = get_option('ssm_email_notifications', '');
+$email_array = array_map('trim', explode(',', $emails));
+$email_array[] = 'new@example.com';
+update_option('ssm_email_notifications', implode(', ', $email_array));
+?>
+```
+
+### Add Custom Validation
+
+```php
+<?php
+// Add to class-settings-page.php
+public static function sanitize_custom_field($value) {
+    $value = sanitize_text_field($value);
+
+    // Custom validation logic
+    if (strlen($value) < 5) {
+        add_settings_error(
+            'ssm_custom_field',
+            'too_short',
+            __('Value must be at least 5 characters.', 'site-settings-manager'),
+            'error'
+        );
+        return get_option('ssm_custom_field');
+    }
+
+    return $value;
+}
+?>
+```
+
+### Add New Settings Section
+
+```php
+<?php
+// In register_settings() method
+add_settings_section(
+    'ssm_custom_section',
+    __('Custom Settings', 'site-settings-manager'),
+    array(__CLASS__, 'render_custom_section'),
+    self::PAGE_SLUG
+);
+
+add_settings_field(
+    'ssm_custom_field',
+    __('Custom Field', 'site-settings-manager'),
+    array('SSM_Settings_Fields', 'render_text_field'),
+    self::PAGE_SLUG,
+    'ssm_custom_section',
+    array(
+        'label_for'   => 'ssm_custom_field',
+        'option_name' => 'ssm_custom_field',
+        'description' => __('Enter custom value', 'site-settings-manager'),
+    )
+);
+?>
+```
+
+---
+
+## Key Features
+
+### 1. Settings API Integration
+- **Proper registration** with `register_setting()`
+- **Sections and fields** with `add_settings_section()` and `add_settings_field()`
+- **Automatic form handling** with `settings_fields()` and `do_settings_sections()`
+- **Built-in validation** and error handling
+
+### 2. Field Types
+- **Text field**: Single-line text input
+- **Textarea field**: Multi-line text input
+- **Checkbox field**: Boolean toggle
+- **Password field**: Masked input
+- **Number field**: Numeric input with min/max
+- **Color field**: Color picker integration
+- **Select field**: Dropdown selection
+- **Radio field**: Radio button group
+
+### 3. Validation & Sanitization
+- **Built-in sanitization**: `sanitize_text_field()`, `sanitize_textarea_field()`, `sanitize_hex_color()`
+- **Custom validation**: API key format, email list, numeric ranges
+- **Error messages**: `add_settings_error()` for user feedback
+- **Fallback values**: Return old value on validation failure
+
+### 4. Security
+- **Capability checks**: `current_user_can('manage_options')`
+- **Nonce verification**: Automatic with Settings API
+- **Input sanitization**: All inputs sanitized
+- **Output escaping**: All outputs escaped
+
+### 5. User Experience
+- **Clean layout**: Two-column design with sidebar
+- **Helpful descriptions**: Field-level help text
+- **System information**: Plugin and environment details
+- **Color picker**: WordPress color picker integration
+- **Responsive design**: Mobile-friendly layout
+
+---
+
+## Best Practices Demonstrated
+
+### Security
+✅ Capability checks (`current_user_can('manage_options')`)
+✅ Automatic nonce verification (Settings API)
+✅ Input sanitization (all fields)
+✅ Output escaping (`esc_html`, `esc_attr`, `esc_url`)
+✅ Validation with error messages
+
+### WordPress Standards
+✅ Settings API usage
+✅ Internationalization (`__()`, `_e()`)
+✅ Proper hook usage (`admin_menu`, `admin_init`)
+✅ Autoloader for class files
+✅ Proper file organization
+✅ WordPress coding standards
+
+### User Experience
+✅ Clear section organization
+✅ Helpful field descriptions
+✅ Validation feedback
+✅ Sidebar with documentation
+✅ Responsive layout
+✅ Color picker integration
+
+### Code Quality
+✅ Separation of concerns (page, fields, validation)
+✅ Reusable field rendering methods
+✅ Consistent naming conventions
+✅ Proper documentation
+✅ Clean uninstall process
+
+---
+
+## Customization
+
+### Add New Field Type
+
+```php
+<?php
+// In class-settings-fields.php
+public static function render_custom_field($args) {
+    $option_name = $args['option_name'];
+    $value = get_option($option_name, '');
+    $description = isset($args['description']) ? $args['description'] : '';
+
+    // Custom field HTML
+    printf(
+        '<input type="text" id="%s" name="%s" value="%s" class="custom-field">',
+        esc_attr($args['label_for']),
+        esc_attr($option_name),
+        esc_attr($value)
+    );
+
+    if ($description) {
+        printf('<p class="description">%s</p>', esc_html($description));
+    }
+}
+?>
+```
+
+### Add Tabs to Settings Page
+
+```php
+<?php
+// Add to settings-page.php view
+<h2 class="nav-tab-wrapper">
+    <a href="?page=site-settings-manager&tab=general" class="nav-tab <?php echo $active_tab == 'general' ? 'nav-tab-active' : ''; ?>">
+        <?php _e('General', 'site-settings-manager'); ?>
+    </a>
+    <a href="?page=site-settings-manager&tab=advanced" class="nav-tab <?php echo $active_tab == 'advanced' ? 'nav-tab-active' : ''; ?>">
+        <?php _e('Advanced', 'site-settings-manager'); ?>
+    </a>
+</h2>
+?>
+```
+
+### Export/Import Settings
+
+```php
+<?php
+// Export settings
+function ssm_export_settings() {
+    $settings = array(
+        'ssm_site_title'       => get_option('ssm_site_title'),
+        'ssm_site_description' => get_option('ssm_site_description'),
+        // ... other settings
+    );
+
+    return json_encode($settings);
+}
+
+// Import settings
+function ssm_import_settings($json) {
+    $settings = json_decode($json, true);
+
+    if ($settings) {
+        foreach ($settings as $key => $value) {
+            update_option($key, $value);
+        }
+    }
+}
+?>
+```
+
+---
+
+## Testing Checklist
+
+- [ ] Access settings page (Settings > Site Settings)
+- [ ] Save settings with valid values
+- [ ] Test validation errors (invalid API key, out-of-range numbers)
+- [ ] Test email list validation
+- [ ] Test color picker functionality
+- [ ] Test checkbox toggle
+- [ ] Verify settings persist after save
+- [ ] Test responsive layout on mobile
+- [ ] Verify capability checks (non-admin users)
+- [ ] Test uninstall cleanup
+- [ ] Check for PHP/JavaScript errors
+- [ ] Verify internationalization strings
+
+---
+
+## Comparison with Other Patterns
+
+| Feature | This Plugin | Simple Settings | Advanced Settings | Framework-Based |
+|---------|-------------|-----------------|-------------------|-----------------|
+| **Complexity** | Medium | Low | High | Very High |
+| **File Count** | 5-10 | 1-2 | 10-20 | 20+ |
+| **Settings API** | ✅ Full | ✅ Basic | ✅ Full | ✅ Custom |
+| **Validation** | ✅ Advanced | ❌ | ✅ Advanced | ✅ Advanced |
+| **Field Types** | ✅ 7 types | ✅ 2-3 types | ✅ 10+ types | ✅ Unlimited |
+| **Layout** | ✅ Custom | ❌ Basic | ✅ Tabbed | ✅ Advanced |
+| **Security** | ✅ Full | ✅ Basic | ✅ Full | ✅ Full |
+| **Best For** | Most plugins | Simple config | Complex plugins | Large systems |
+
+---
+
+## Summary
+
+This example demonstrates a **complete settings page plugin** with:
+
+- ✅ WordPress Settings API integration
+- ✅ Multiple field types (text, textarea, checkbox, password, number, color, select, radio)
+- ✅ Advanced validation and sanitization
+- ✅ Custom admin page with sidebar
+- ✅ Proper security (capability checks, sanitization, escaping)
+- ✅ Error handling and user feedback
+- ✅ Responsive design
+- ✅ Color picker integration
+- ✅ Clean uninstall process
+- ✅ Internationalization support
+- ✅ Reusable field rendering methods
+
+**Perfect for**: Plugin configuration, site settings, feature toggles, API integrations, or any plugin requiring user-configurable options.
+
+**Character Count**: ~24,500 characters
+