├── .bowerrc ├── .gitignore ├── LICENSE ├── README.md ├── assets ├── css │ └── main.css ├── js │ └── main.js └── vendor │ ├── jquery-timepicker │ ├── .bower.json │ ├── GPL-LICENSE.txt │ ├── MIT-LICENSE.txt │ ├── README.md │ ├── i18n │ │ ├── i18n.html │ │ ├── jquery.ui.timepicker-cs.js │ │ ├── jquery.ui.timepicker-de.js │ │ ├── jquery.ui.timepicker-es.js │ │ ├── jquery.ui.timepicker-fr.js │ │ ├── jquery.ui.timepicker-hr.js │ │ ├── jquery.ui.timepicker-hu.js │ │ ├── jquery.ui.timepicker-it.js │ │ ├── jquery.ui.timepicker-ja.js │ │ ├── jquery.ui.timepicker-mk.js │ │ ├── jquery.ui.timepicker-nl.js │ │ ├── jquery.ui.timepicker-pl.js │ │ ├── jquery.ui.timepicker-pt-BR.js │ │ ├── jquery.ui.timepicker-ru.js │ │ ├── jquery.ui.timepicker-sl.js │ │ ├── jquery.ui.timepicker-sv.js │ │ └── jquery.ui.timepicker-tr.js │ ├── include │ │ ├── jquery-1.9.0.min.js │ │ └── ui-1.10.0 │ │ │ ├── jquery.ui.core.min.js │ │ │ ├── jquery.ui.position.min.js │ │ │ ├── jquery.ui.tabs.min.js │ │ │ ├── jquery.ui.widget.min.js │ │ │ └── ui-lightness │ │ │ ├── images │ │ │ ├── ui-bg_diagonals-thick_18_b81900_40x40.png │ │ │ ├── ui-bg_diagonals-thick_20_666666_40x40.png │ │ │ ├── ui-bg_flat_10_000000_40x100.png │ │ │ ├── ui-bg_glass_100_f6f6f6_1x400.png │ │ │ ├── ui-bg_glass_100_fdf5ce_1x400.png │ │ │ ├── ui-bg_glass_65_ffffff_1x400.png │ │ │ ├── ui-bg_gloss-wave_35_f6a828_500x100.png │ │ │ ├── ui-bg_highlight-soft_100_eeeeee_1x100.png │ │ │ ├── ui-bg_highlight-soft_75_ffe45c_1x100.png │ │ │ ├── ui-icons_222222_256x240.png │ │ │ ├── ui-icons_228ef1_256x240.png │ │ │ ├── ui-icons_ef8c08_256x240.png │ │ │ ├── ui-icons_ffd27a_256x240.png │ │ │ └── ui-icons_ffffff_256x240.png │ │ │ └── jquery-ui-1.10.0.custom.min.css │ ├── index.html │ ├── jquery.ui.timepicker.css │ ├── jquery.ui.timepicker.js │ ├── legacy_1.2.6 │ │ ├── index.html │ │ ├── jquery-1.2.6.js │ │ ├── jquery.proxy.fix.js │ │ └── jquery.ui.1.6.all.js │ ├── tests │ │ ├── dialog.html │ │ └── jquery.ui.dialog.min.js │ └── timepicker.png │ └── jquery-ui │ ├── images │ ├── ui-bg_flat_30_cccccc_40x100.png │ ├── ui-bg_flat_50_5c5c5c_40x100.png │ ├── ui-bg_glass_20_555555_1x400.png │ ├── ui-bg_glass_40_0078a3_1x400.png │ ├── ui-bg_glass_40_ffc73d_1x400.png │ ├── ui-bg_gloss-wave_25_333333_500x100.png │ ├── ui-bg_highlight-soft_80_eeeeee_1x100.png │ ├── ui-bg_inset-soft_25_000000_1x100.png │ ├── ui-bg_inset-soft_30_f58400_1x100.png │ ├── ui-icons_222222_256x240.png │ ├── ui-icons_4b8e0b_256x240.png │ ├── ui-icons_a83300_256x240.png │ ├── ui-icons_cccccc_256x240.png │ └── ui-icons_ffffff_256x240.png │ └── jquery-ui.css ├── bower.json ├── changelog.txt ├── composer.json ├── composer.lock ├── phpcs.xml ├── settings └── example-settings.php ├── wp-settings-framework.php └── wpsf-test.php /.bowerrc: -------------------------------------------------------------------------------- 1 | { 2 | "directory" : "assets/vendor" 3 | } -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .idea 2 | .DS_Store 3 | /vendor/ -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2012 Dev7studios 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | WordPress Settings Framework 2 | ============================ 3 | 4 | The WordPress Settings Framework aims to take the pain out of creating settings pages for your WordPress plugins 5 | by effectively creating a wrapper around the WordPress settings API and making it super simple to create and maintain 6 | settings pages. 7 | 8 | This repo is actually a working plugin which demonstrates how to implement WPSF in your plugins. See `wpsf-test.php` 9 | for details. 10 | 11 | Setting Up Your Plugin 12 | ---------------------- 13 | 14 | 1. Create a folder "wp-settings-framework" in the root of your plugin folder, containing `wp-settings-framework.php` and the "assets" folder. 15 | 2. Create a "settings" folder in your plugin root. 16 | 3. Create a settings file in your new "settings" folder (e.g. `settings-general.php`) 17 | 18 | Now you can set up your plugin like: 19 | 20 | ```php 21 | class WPSFTest { 22 | /** 23 | * @var string 24 | */ 25 | private $plugin_path; 26 | 27 | /** 28 | * @var WordPressSettingsFramework 29 | */ 30 | private $wpsf; 31 | 32 | /** 33 | * WPSFTest constructor. 34 | */ 35 | function __construct() { 36 | $this->plugin_path = plugin_dir_path( __FILE__ ); 37 | 38 | // Include and create a new WordPressSettingsFramework 39 | require_once( $this->plugin_path . 'wp-settings-framework/wp-settings-framework.php' ); 40 | $this->wpsf = new WordPressSettingsFramework( $this->plugin_path . 'settings/settings-general.php', 'prefix_settings_general' ); 41 | 42 | // Add admin menu 43 | add_action( 'admin_menu', array( $this, 'add_settings_page' ), 20 ); 44 | 45 | // Add an optional settings validation filter (recommended) 46 | add_filter( $this->wpsf->get_option_group() . '_settings_validate', array( &$this, 'validate_settings' ) ); 47 | } 48 | 49 | /** 50 | * Add settings page. 51 | */ 52 | function add_settings_page() { 53 | $this->wpsf->add_settings_page( array( 54 | 'parent_slug' => 'woocommerce', 55 | 'page_title' => __( 'Page Title', 'text-domain' ), 56 | 'menu_title' => __( 'menu Title', 'text-domain' ), 57 | 'capability' => 'manage_woocommerce', 58 | ) ); 59 | } 60 | 61 | /** 62 | * Validate settings. 63 | * 64 | * @param $input 65 | * 66 | * @return mixed 67 | */ 68 | function validate_settings( $input ) { 69 | // Do your settings validation here 70 | // Same as $sanitize_callback from http://codex.wordpress.org/Function_Reference/register_setting 71 | return $input; 72 | } 73 | 74 | // ... 75 | } 76 | ``` 77 | 78 | Your settings values can be accessed like so: 79 | 80 | ```php 81 | // Get settings 82 | $this->wpsf->get_settings(); 83 | ``` 84 | 85 | This will get either the saved setting values, or the default values that you set in your settings file. 86 | 87 | Or by getting individual settings: 88 | 89 | ```php 90 | // Get individual setting 91 | $setting = wpsf_get_setting( 'prefix_settings_general', 'general', 'text' ); 92 | ``` 93 | 94 | 95 | The Settings Files 96 | ------------------ 97 | 98 | The settings files work by filling the global `$wpsf_settings` array with data in the following format: 99 | 100 | ```php 101 | $wpsf_settings[] = array( 102 | 'section_id' => 'general', // The section ID (required) 103 | 'section_title' => 'General Settings', // The section title (required) 104 | 'section_description' => 'Some intro description about this section.', // The section description (optional) 105 | 'section_order' => 5, // The order of the section (required) 106 | 'fields' => array( 107 | array( 108 | 'id' => 'text', 109 | 'title' => 'Text', 110 | 'desc' => 'This is a description.', 111 | 'placeholder' => 'This is a placeholder.', 112 | 'type' => 'text', 113 | 'default' => 'This is the default value' 114 | ), 115 | array( 116 | 'id' => 'select', 117 | 'title' => 'Select', 118 | 'desc' => 'This is a description.', 119 | 'type' => 'select', 120 | 'default' => 'green', 121 | 'choices' => array( 122 | 'red' => 'Red', 123 | 'green' => 'Green', 124 | 'blue' => 'Blue' 125 | ) 126 | ), 127 | 128 | // add as many fields as you need... 129 | 130 | ) 131 | ); 132 | ``` 133 | 134 | Valid `fields` values are: 135 | 136 | * `id` - Field ID 137 | * `title` - Field title 138 | * `desc` - Field description 139 | * `conditional_desc` - Array of conditional field value descriptions (for select) 140 | * `placeholder` - Field placeholder 141 | * `type` - Field type (text/password/textarea/select/radio/checkbox/checkboxes/color/file/editor/code_editor) 142 | * `default` - Default value (or selected option) 143 | * `choices` - Array of options (for select/radio/checkboxes) 144 | * `mimetype` - Any valid mime type accepted by Code Mirror for syntax highlighting (for code_editor) 145 | 146 | See `settings/example-settings.php` for an example of possible values. 147 | 148 | 149 | API Details 150 | ----------- 151 | 152 | new WordPressSettingsFramework( string $settings_file [, string $option_group = ''] ) 153 | 154 | Creates a new settings [option_group](http://codex.wordpress.org/Function_Reference/register_setting) based on a setttings file. 155 | 156 | * `$settings_file` - path to the settings file 157 | * `$option_group` - optional "option_group" override (by default this will be set to the basename of the settings file) 158 | 159 |
wpsf_get_setting( $option_group, $section_id, $field_id )160 | 161 | Get a setting from an option group 162 | 163 | * `$option_group` - option group id. 164 | * `$section_id` - section id (change to `[{$tab_id}_{$section_id}]` when using tabs. 165 | * `$field_id` - field id. 166 | 167 |
wpsf_delete_settings( $option_group )168 | 169 | Delete all the saved settings from a option group 170 | 171 | * `$option_group` - option group id 172 | 173 | Actions & Filters 174 | --------------- 175 | 176 | **Filters** 177 | 178 | * `wpsf_register_settings_[option_group]` - The filter used to register your settings. See `settings/example-settings.php` for an example. 179 | * `[option_group]_settings_validate` - Basically the `$sanitize_callback` from [register_setting](http://codex.wordpress.org/Function_Reference/register_setting). Use `$wpsf->get_option_group()` to get the option group id. 180 | * `wpsf_defaults_[option_group]` - Default args for a settings field 181 | 182 | **Actions** 183 | 184 | * `wpsf_before_field_[option_group]` - Before a field HTML is output 185 | * `wpsf_before_field_[option_group]_[field_id]` - Before a field HTML is output 186 | * `wpsf_after_field_[option_group]` - After a field HTML is output 187 | * `wpsf_after_field_[option_group]_[field_id]` - After a field HTML is output 188 | * `wpsf_before_settings_[option_group]` - Before settings form HTML is output 189 | * `wpsf_after_settings_[option_group]` - After settings form HTML is output 190 | * `wpsf_before_settings_fields_[option_group]` - Before settings form fields HTML is output (inside the `