ayecode / wp-ayecode-settings-framework
Modern WordPress settings framework with Alpine.js and Bootstrap 5
Package info
github.com/AyeCode/wp-ayecode-settings-framework
Language:JavaScript
pkg:composer/ayecode/wp-ayecode-settings-framework
Requires
- php: >=7.4
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 15:16:02 UTC
README
A modern WordPress settings framework with Alpine.js and Bootstrap 5, designed for creating beautiful, responsive admin interfaces with minimal code.
Features
- π¨ Modern UI - Clean, responsive interface using Bootstrap 5
- β‘ Alpine.js Powered - Reactive UI without complex build steps
- π Smart Search - Find and edit settings instantly
- π± Mobile Responsive - Works perfectly on all devices
- ποΈ Rich Field Types - Text, toggles, colors, selects, and more
- π Action Buttons - AJAX buttons with confirmation dialogs and progress tracking
- π οΈ Tools - Write a job once, run it from the admin UI, a REST route and WP-CLI
- β»οΈ Built-in Reset - One-line reset to defaults functionality
- π Secure - Built-in validation and sanitization
- π Translation Ready - Full i18n support
- π Performance - Lightweight and fast
Installation
Install via Composer:
composer require ayecode//wp-ayecode-settings-framework/
Documentation
- Page setup β class properties, header slots, labels and translation
- Section types β settings, action, import, list table, dashboard, form builder, extensions
- Field types β every field type and its parameters
- Setup wizards β full-page multi-step flows
- Tools β one class per job, run from the admin UI, REST and WP-CLI
- Blueprints - a JSON description of a site, validated, applied in batches and undoable, built on tools
- Setup Builder - a one-screen first-run setup that plans, reviews and builds a blueprint
- Default settings β installing defaults on activation
Working examples for each of these live in examples/.
Quick Start
1. Create Configuration Array
$config = array(
'sections' => array(
array(
'id' => 'general',
'name' => 'General Settings',
'icon' => 'fa-solid fa-gear',
'fields' => array(
array(
'id' => 'site_title',
'type' => 'text',
'label' => 'Site Title',
'description' => 'Enter your site title',
'default' => 'My Awesome Site'
),
array(
'id' => 'enable_feature',
'type' => 'toggle',
'label' => 'Enable Cool Feature',
'description' => 'Turn on the cool feature',
'default' => true
)
)
)
)
);
2. Create Your Settings Class
Settings_Framework is abstract β extend it and return the config from get_config().
Non-user-facing configuration goes in properties; everything the user reads goes in
get_labels(), which is called late enough for __() to be safe:
use AyeCode\SettingsFramework\Settings_Framework;
class My_Plugin_Settings extends Settings_Framework {
protected $option_name = 'my_plugin_settings';
protected $page_slug = 'my-plugin-settings';
protected function get_labels() {
return [
'header_icon' => '<span class="fa-stack fa-1x">...</span>',
'plugin_name' => __( 'My Awesome Plugin', 'my-plugin' ),
'page_title' => __( 'My Plugin Settings', 'my-plugin' ),
'menu_title' => __( 'Plugin Settings', 'my-plugin' ),
];
}
protected function get_config() {
return $config; // the array from step 1
}
}
new My_Plugin_Settings();
See docs/dev/page-setup.md for every property, the header slots and the allowed icon markup.
3. Access Settings
// Get all settings
$settings = get_option('my_plugin_settings', array());
// Get specific setting
$site_title = $settings['site_title'] ?? 'Default Title';
Field Types
Text Fields
array(
'id' => 'username',
'type' => 'text',
'label' => 'Username',
'placeholder' => 'Enter username...',
'required' => true
)
Toggle Switches
array(
'id' => 'enable_notifications',
'type' => 'toggle',
'label' => 'Enable Notifications',
'description' => 'Turn on email notifications',
'default' => false
)
Select Dropdowns
array(
'id' => 'theme_style',
'type' => 'select',
'label' => 'Theme Style',
'options' => array(
'light' => 'Light Theme',
'dark' => 'Dark Theme',
'auto' => 'Auto (System)'
),
'default' => 'light'
)
Color Pickers
array(
'id' => 'brand_color',
'type' => 'color',
'label' => 'Brand Color',
'default' => '#0073aa'
)
Number Fields
array(
'id' => 'max_items',
'type' => 'number',
'label' => 'Maximum Items',
'min' => 1,
'max' => 100,
'step' => 1,
'default' => 10
)
Sections with Subsections
array(
'id' => 'advanced',
'name' => 'Advanced Settings',
'icon' => 'fa-solid fa-tools',
'subsections' => array(
array(
'id' => 'performance',
'name' => 'Performance',
'icon' => 'fa-solid fa-tachometer-alt',
'fields' => array(
// Performance fields here
)
),
array(
'id' => 'security',
'name' => 'Security',
'icon' => 'fa-solid fa-shield-alt',
'fields' => array(
// Security fields here
)
)
)
)
Search Functionality
Add searchable terms to fields for better discovery:
array(
'id' => 'google_maps_api_key',
'type' => 'password',
'label' => 'Google Maps API Key',
'searchable' => array('google', 'maps', 'api', 'key', 'geolocation')
)
Validation
Built-in Validation
array(
'id' => 'email_address',
'type' => 'email',
'label' => 'Email Address',
'required' => true
)
Custom Validation
array(
'id' => 'custom_field',
'type' => 'text',
'label' => 'Custom Field',
'validate_callback' => 'my_custom_validator'
)
function my_custom_validator($value, $field) {
if (strlen($value) < 5) {
return new WP_Error('too_short', 'Value must be at least 5 characters');
}
return true;
}
Addon Integration
Your addons can inject settings into existing sections:
// In your addon β replace 'my_page_slug' with the consuming plugin's $page_slug value
add_filter( 'ayecode_settings_framework_sections_my_page_slug', function( $sections, $option_name, $page_slug ) {
$sections[] = array(
'id' => 'my_addon',
'name' => 'My Addon Settings',
'icon' => 'fa-solid fa-puzzle-piece',
'fields' => array(
// Addon fields here
),
);
return $sections;
}, 10, 3 );
Hooks & Filters
Actions
// After settings are saved
add_action('ayecode_settings_framework_saved', function($settings, $option_name) {
// Clear caches, trigger updates, etc.
}, 10, 2);
// After settings are reset
add_action('ayecode_settings_framework_reset', function($option_name) {
// Handle reset logic
});
Filters
// Inject or modify sections for a specific settings page (replace 'my_page_slug' with the target plugin's $page_slug)
add_filter( 'ayecode_settings_framework_sections_my_page_slug', function( $sections, $option_name, $page_slug ) {
// Modify or add sections
return $sections;
}, 10, 3 );
// Brand every page a plugin registers, including pages registered by its addons
add_filter( 'ayecode_settings_framework_labels', function( $labels, $page_slug ) {
if ( 0 === strpos( $page_slug, 'my_plugin_' ) ) {
$labels['header_icon'] = '<span class="fa-stack fa-1x">...</span>';
$labels['plugin_name'] = __( 'My Awesome Plugin', 'my-plugin' );
}
return $labels;
}, 10, 2 );
// Extend the tags allowed in the header icon markup
add_filter( 'ayecode_settings_framework_allowed_header_icon_html', function( $allowed, $page_slug ) {
return $allowed;
}, 10, 2 );
Styling
The framework uses Bootstrap 5 with minimal custom CSS. To customize:
/* Override framework colors */
:root {
--asf-blue: #your-color;
--asf-blue-dark: #your-dark-color;
}
/* Custom field styling */
.your-plugin .form-control {
border-radius: 8px;
}
JavaScript Integration
Access the Alpine.js app:
// Listen for settings changes
document.addEventListener('alpine:init', () => {
Alpine.data('customExtension', () => ({
// Your custom Alpine.js data/methods
}));
});
Requirements
- PHP 7.4+
- WordPress 5.0+
- Modern browser with JavaScript enabled
Browser Support
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if needed
- Submit a pull request
License
GPL-3.0-or-later
Support
π οΈ Building Assets with Vite
This plugin uses Vite to bundle and optimize its JavaScript.
We build in IIFE format so the output can be safely enqueued in WordPress without requiring a module loader.
π¦ Prerequisites
- Node.js (LTS version recommended, e.g. 20.x)
- npm or yarn
π§ Setup
# install dependencies
npm install
π Development
npm run dev
- Vite will serve unminified builds.
- Update
vite.config.js β server.originif you need a different dev URL.
ποΈ Production Build
Build optimized assets into assets/dist:
npm run build
- Output JS is placed under
assets/dist/js/ - Filenames follow the entry name (
settings.js,admin-keys.js, etc). - A
manifest.jsonis generated inassets/dist/for PHP to resolve correct asset paths.
π Entry Points
Each entry corresponds to a separate admin screen:
settings.jsβ Settings Framework (Alpine.js app)admin-keys.jsβ API Keys admin page
You can add more entries in vite.config.js β build.rollupOptions.input.
βοΈ Notes
- Alpine.js is external β itβs enqueued separately in WordPress, not bundled.
- Output is an IIFE (immediately-invoked function expression) for WP compatibility.
- Static assets (images, fonts, etc.) are handled by WordPress enqueueing, not via Viteβs
public/folder.
Made with β€οΈ by AyeCode Ltd