Skip to content

appscreo/modern-settings-framework

Repository files navigation

Modern Settings Framework πŸŽ›οΈ

Version WordPress License PRs Welcome

A modern, comprehensive, and developer-friendly settings framework for WordPress plugins and themes. Build beautiful settings pages with 30+ field types, advanced features, and zero configuration hassle.

Donate to support this project at Buy me a coffee Donate to support this project at GitHub

Modern Settings Framework

✨ Features

🎨 30+ Field Types

Text, Textarea, Number, Email, URL, Password, Select, Radio, Checkbox, Switch, Multi-Select Tags, Color Picker, Date/Time, File Upload, Image Upload, Code Editor, WYSIWYG, Range Slider, and more!

πŸš€ Advanced Features

  • ⚑ Auto-save with draft recovery
  • πŸ” Real-time search & filter
  • ⌨️ Keyboard shortcuts (Ctrl+S, Ctrl+Z, etc.)
  • ↩️ Undo/Redo functionality
  • βœ… Field validation
  • πŸ’‘ Tooltips
  • 🎯 Conditional fields
  • πŸ“¦ Import/Export settings
  • πŸŽͺ Accordion panels
  • 🏷️ Tag-based multi-select
  • πŸ“± Mobile responsive

πŸ› οΈ Developer Friendly

  • Simple API
  • Extensive documentation
  • Flexible integration (plugin or theme)
  • Customizable placement (top-level, Settings, Tools, or custom menu)
  • Role-based access control
  • Hooks and filters
  • Custom field types support

πŸ“‹ Table of Contents

πŸ’» Requirements

  • WordPress 6.0 or higher
  • PHP 7.1 or higher

πŸ“₯ Installation

Option 1: Manual Installation

  1. Download the framework
  2. Copy the options-framework folder to your plugin or theme directory
  3. Include the framework class in your code
if (!class_exists('Modern_Settings_Framework')) {
    require_once 'path/to/options-framework/class-modern-settings-framework.php';
}

Option 2: Composer (coming soon)

composer require your-vendor/modern-settings-framework

πŸš€ Quick Start

Basic Usage

<?php
// 1. Include the framework
if (!class_exists('Modern_Settings_Framework')) {
    require_once 'options-framework/class-modern-settings-framework.php';
}

// 2. Create instance
$framework = new Modern_Settings_Framework( 'my_plugin_settings' );

// 3. Register settings page
$framework->register_settings_page( array(
    'type'       => 'top_level',
    'page_title' => 'My Plugin Settings',
    'menu_title' => 'My Plugin',
    'menu_slug'  => 'my-plugin',
    'icon_url'   => 'dashicons-admin-settings',
) );

// 4. Register tabs
$framework->register_tab( 'general', array(
    'title' => 'General Settings',
    'icon'  => 'dashicons-admin-generic',
) );

// 5. Register fields
$framework->register_field( 'general', array(
    'id'          => 'site_name',
    'type'        => 'text',
    'label'       => 'Site Name',
    'description' => 'Enter your site name',
    'default'     => get_bloginfo( 'name' ),
) );

$framework->register_field( 'general', array(
    'id'          => 'enable_feature',
    'type'        => 'switch',
    'label'       => 'Enable Feature',
    'description' => 'Turn feature on or off',
    'default'     => true,
) );

// 6. Get settings values
$settings = get_option( 'my_plugin_settings' );
$site_name = isset( $settings['site_name'] ) ? $settings['site_name'] : '';

Advanced Configuration

// Create framework with custom options
$framework_options = array(
    'enable_search'             => true,
    'enable_autosave'           => true,
    'autosave_interval'         => 30,
    'enable_keyboard_shortcuts' => true,
    'enable_undo_redo'          => true,
    'enable_validation'         => true,
    'capability'                => 'manage_options',
    'svg_logo'                  => '',
    'image_logo'                => '',
    'title'                     => '',
    'allowed_roles'             => array( 'administrator', 'editor' ),
);

$framework = new Modern_Settings_Framework( 'my_settings', $framework_options );

πŸ“š Documentation

Comprehensive documentation is available in the /docs folder:

🎨 Field Types

Text-Based Fields

  • text - Single-line text input
  • textarea - Multi-line text input
  • number - Numeric input with min/max
  • email - Email validation
  • url - URL validation
  • password - Password field with show/hide toggle
  • hidden - Hidden input

Selection Fields

  • select - Dropdown select
  • radio - Radio buttons
  • checkbox - Single checkbox
  • checkbox_group - Multiple checkboxes
  • multi_select_tags - Tag-based multi-select with search
  • switch - Toggle switch

Media Fields

  • color - Color picker
  • file - File upload
  • image - Image upload with preview
  • gallery - Multiple image upload

Advanced Fields

  • code - Code editor with syntax highlighting
  • wysiwyg - WordPress WYSIWYG editor
  • date - Date picker
  • time - Time picker
  • datetime - Date and time picker
  • range - Range slider

Layout Elements

  • divider - Visual separator with optional title
  • info - Information/alert box (success, warning, error, info)
  • accordion - Collapsible panel grouping
  • accordion_end - Close accordion

View detailed field documentation β†’

πŸ’‘ Examples

Conditional Fields

// Show API key field only when feature is enabled
$framework->register_field( 'general', array(
    'id'      => 'enable_api',
    'type'    => 'switch',
    'label'   => 'Enable API',
    'default' => false,
) );

$framework->register_field( 'general', array(
    'id'          => 'api_key',
    'type'        => 'text',
    'label'       => 'API Key',
    'conditional' => array(
        'field' => 'enable_api',
        'value' => true,
    ),
) );

Required Fields with Validation

$framework->register_field( 'general', array(
    'id'         => 'email',
    'type'       => 'email',
    'label'      => 'Contact Email',
    'required'   => true,
    'validation' => array(
        'min_length' => 5,
        'max_length' => 100,
    ),
) );

Accordion Groups

// Start accordion
$framework->register_field( 'advanced', array(
    'type'      => 'accordion',
    'id'        => 'email_settings',
    'title'     => 'Email Configuration',
    'icon'      => 'dashicons-email',
    'collapsed' => false,
) );

// Fields inside accordion
$framework->register_field( 'advanced', array(
    'id'    => 'smtp_host',
    'type'  => 'text',
    'label' => 'SMTP Host',
) );

$framework->register_field( 'advanced', array(
    'id'    => 'smtp_port',
    'type'  => 'number',
    'label' => 'SMTP Port',
) );

// End accordion
$framework->register_field( 'advanced', array(
    'type' => 'accordion_end',
) );

Custom Buttons

// Register export button
$framework->register_custom_button( 'general', array(
    'id'       => 'export_settings',
    'label'    => 'Export Settings',
    'class'    => 'button-secondary',
    'callback' => 'my_export_callback',
) );

// Callback function
function my_export_callback( $framework ) {
    $settings = $framework->get_saved_settings();
    
    return array(
        'message'  => 'Settings exported!',
        'download' => true,
        'filename' => 'settings.json',
        'content'  => wp_json_encode( $settings ),
    );
}

Multi-Select Tags

$framework->register_field( 'general', array(
    'id'             => 'user_roles',
    'type'           => 'multi_select_tags',
    'label'          => 'Allowed Roles',
    'max_selections' => 3,
    'options'        => array(
        'administrator' => 'Administrator',
        'editor'        => 'Editor',
        'author'        => 'Author',
    ),
) );

Different Page Placements

// Top-level menu
$framework->register_settings_page( array(
    'type'       => 'top_level',
    'page_title' => 'My Settings',
    'menu_title' => 'My Plugin',
    'menu_slug'  => 'my-plugin',
) );

// Under Settings menu
$framework->register_settings_page( array(
    'type'       => 'submenu_settings',
    'page_title' => 'My Settings',
    'menu_title' => 'My Plugin',
) );

// Under Tools menu
$framework->register_settings_page( array(
    'type'       => 'submenu_tools',
    'page_title' => 'My Tools',
    'menu_title' => 'My Plugin',
) );

// Under custom parent (e.g., WooCommerce)
$framework->register_settings_page( array(
    'type'        => 'submenu_custom',
    'parent_slug' => 'woocommerce',
    'page_title'  => 'My Settings',
    'menu_title'  => 'My Integration',
) );

View more examples β†’

🎯 Framework API

Main Methods

// Create instance
new Modern_Settings_Framework( string $option_name, array $framework_options = array() )

// Register settings page
$framework->register_settings_page( array $config )

// Register tab
$framework->register_tab( string $tab_id, array $config )

// Register field
$framework->register_field( string $tab_id, array $config )

// Register custom button
$framework->register_custom_button( string $tab_id, array $config )

// Get saved settings
$framework->get_saved_settings()

// Get specific setting
$framework->get_setting( string $key, mixed $default = null )

// Update specific setting
$framework->update_setting( string $key, mixed $value )

View full API documentation β†’

🎁 What's Included

modern-settings-framework/
β”œβ”€β”€ options-framework/
β”‚   β”œβ”€β”€ class-modern-settings-framework.php  # Main framework class
β”‚   β”œβ”€β”€ includes/
β”‚   β”‚   β”œβ”€β”€ admin-page.php                   # Settings page template
β”‚   β”‚   └── field-renderer.php               # Field rendering functions
β”‚   └── assets/
β”‚       β”œβ”€β”€ css/
β”‚       β”‚   β”œβ”€β”€ admin-styles.css             # Main styles
β”‚       β”‚   └── fields.css                   # Field-specific styles
β”‚       └── js/
β”‚           β”œβ”€β”€ admin-scripts.js             # Core functionality
β”‚           └── fields.js                    # Field-specific JS
β”œβ”€β”€ modern-settings-framework-demo.php       # Demo plugin
β”œβ”€β”€ README.md                                # This file
└── docs/                                    # Documentation folder
    β”œβ”€β”€ 01-getting-started.md
    β”œβ”€β”€ 02-framework-options.md
    β”œβ”€β”€ 03-registering-pages.md
    └── ...

🀝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Read contributing guidelines β†’

πŸ“ Changelog

Version 4.1.0 (Latest) - 2026-01-25

New Features

Additional Assets Support

  • Added additional_styles and additional_scripts framework options to enqueue custom CSS and JavaScript files
  • New action hooks for manual asset adjustments after enqueuing
  • View Documentation

Custom Button Enhancements

  • Added location parameter to position buttons at top or bottom of settings page
  • Added reload parameter to automatically reload page after button action
  • View Documentation

Text Domain Customization

  • Added text_domain framework option for embedding in plugins and themes
  • Framework now respects custom text domains for proper internationalization
  • Added get_text_domain() method and public $text_domain property
  • View Documentation

See full changelog: CHANGELOG.md

πŸ“„ License

This project is licensed under the GPL-2.0+ License - see the LICENSE file for details.

πŸ™ Credits

Modern Settings Framework is created and maintained by AppsCreo.

Built With

  • WordPress
  • jQuery
  • CodeMirror
  • WordPress Color Picker

πŸ’¬ Support

⭐ Star History

If you find this project useful, please consider giving it a star on GitHub!


Made with ❀️ for the WordPress community

About

A comprehensive WordPress settings framework that can be integrated into any plugin or theme.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

  •  

Packages

 
 
 

Contributors