classes
4 years ago
css
4 years ago
img
4 years ago
js
4 years ago
lib
4 years ago
.gitignore
4 years ago
README.md
4 years ago
simple-admin-pages.php
4 years ago
README.md
435 lines
| 1 | Simple Admin Pages for WordPress |
| 2 | ================================ |
| 3 | |
| 4 | Simple Admin Pages is a very small utility library to easily add new admin |
| 5 | pages to the WordPress admin interface. It collects WordPress' useful |
| 6 | Settings API into reuseable classes and implements a set of simple controls. |
| 7 | |
| 8 | |
| 9 | ## Settings Pages Supported |
| 10 | |
| 11 | - Settings sub-page |
| 12 | - Themes sub-page |
| 13 | - Submenu pages for custom menu items |
| 14 | |
| 15 | ## General Controls Supported |
| 16 | |
| 17 | - Text field |
| 18 | - Textarea field |
| 19 | - Image field |
| 20 | - Toggle (checkbox to enable/disable setting) |
| 21 | - Select dropdown with custom options |
| 22 | - Select dropdown of any post type |
| 23 | - Select dropdown of any taxonomy type |
| 24 | - HTML Content (for instructions, links or other inert text) |
| 25 | - WordPress Editor |
| 26 | |
| 27 | ## Controls Supported for Special Use Cases |
| 28 | |
| 29 | - Date and Time Scheduler |
| 30 | - Google Map Address (with GeoLocation) |
| 31 | - Business Opening Hours |
| 32 | |
| 33 | ## Usage |
| 34 | |
| 35 | Here's an example of how you can use this library to create an admin page. |
| 36 | |
| 37 | ``` |
| 38 | // Instantiate the Simple Admin Library |
| 39 | require_once( 'path/to/simple-admin-pages/simple-admin-pages.php' ); |
| 40 | $sap = sap_initialize_library( |
| 41 | array( |
| 42 | 'version' => '2.4.0', // Version of the library |
| 43 | 'lib_url' => PLUGIN_URL . '/lib/simple-admin-pages/', // URL path to sap library |
| 44 | ) |
| 45 | ); |
| 46 | |
| 47 | // Create a page for the options under the Settings (options) menu |
| 48 | $sap->add_page( |
| 49 | 'options', // Admin menu which this page should be added to |
| 50 | array( // Array of key/value pairs matching the AdminPage class constructor variables |
| 51 | 'id' => 'basic-settings', |
| 52 | 'title' => __( 'Page Title', 'textdomain' ), |
| 53 | 'menu_title' => __( 'menu Title', 'textdomain' ), |
| 54 | 'description' => '', |
| 55 | 'capability' => 'manage_options' // User permissions access level |
| 56 | ) |
| 57 | ); |
| 58 | |
| 59 | // Create a basic details section |
| 60 | $sap->add_section( |
| 61 | 'basic-settings', // Page to add this section to |
| 62 | array( // Array of key/value pairs matching the AdminPageSection class constructor variables |
| 63 | 'id' => 'basic-details', |
| 64 | 'title' => __( 'Basic Details', 'textdomain' ), |
| 65 | 'description' => __( 'This section includes some basic details for you to configure.', 'textdomain' ) |
| 66 | ) |
| 67 | ); |
| 68 | |
| 69 | // Create the options fields |
| 70 | $sap->add_setting( |
| 71 | 'basic-settings', // Page to add this setting to |
| 72 | 'basic-details', // Section to add this setting to |
| 73 | 'select', // Type of setting (see sapLibrary::get_setting_classname() |
| 74 | array( |
| 75 | 'id' => 'select-field', |
| 76 | 'title' => __( 'Select Field', 'textdomain' ), |
| 77 | 'description' => __( 'A demonstration of the select field type.', 'textdomain' ), |
| 78 | 'options' => array( |
| 79 | 'one' => __( 'Option 1', 'textdomain' ), |
| 80 | 'two' => __( 'Option 2', 'textdomain' ), |
| 81 | 'three' => __( 'Option 3', 'textdomain' ) |
| 82 | ) |
| 83 | ) |
| 84 | ); |
| 85 | |
| 86 | // Allow third-party addons to hook into your settings page |
| 87 | $sap = apply_filters( 'sap_page_setup', $sap ); |
| 88 | |
| 89 | // Register all admin pages and settings with WordPress |
| 90 | $sap->add_admin_menus(); |
| 91 | ``` |
| 92 | |
| 93 | Check out the documentation section below for more examples and explanation. |
| 94 | |
| 95 | ## License |
| 96 | |
| 97 | Simple Admin Pages is released under the GNU GPL 2 or later. |
| 98 | |
| 99 | ## Requirements |
| 100 | |
| 101 | Simple Admin Pages has been tested with WordPress versions 3.5 and above. |
| 102 | |
| 103 | ## Roadmap |
| 104 | |
| 105 | - Better documentation |
| 106 | - Support custom top-level admin pages |
| 107 | - More custom data types |
| 108 | |
| 109 | ## Documentation |
| 110 | |
| 111 | ### sap_initialize_library() |
| 112 | Instantiate the library by loading the simple-admin-pages.php file and calling sap_initialize_library. You'll do everything with the $sap object that is returned. |
| 113 | |
| 114 | **args** |
| 115 | An array of properties to pass to the library. |
| 116 | |
| 117 | *version* |
| 118 | (required) |
| 119 | |
| 120 | This used to ensure that plugins can play well together even if they use different versions of the library. The version will convert . to _ and append that to the class names which are loaded. If version 1.0 is passed, the library will attempt to load a class named sapAdminPage_1_0. |
| 121 | |
| 122 | *lib_url* |
| 123 | (required) |
| 124 | |
| 125 | The lib_url is used to print stylesheets or scripts attached to the library. |
| 126 | |
| 127 | ``` |
| 128 | require_once( 'path/to/simple-admin-pages/simple-admin-pages.php' ); |
| 129 | $sap = sap_initialize_library( |
| 130 | $args = array( |
| 131 | 'version' => '2.4.0', // Version of the library |
| 132 | 'lib_url' => PLUGIN_URL . '/lib/simple-admin-pages/', // URL path to sap library |
| 133 | ) |
| 134 | ); |
| 135 | ``` |
| 136 | |
| 137 | ### sapLibrary::add_page() |
| 138 | Create a new page with the library by calling the add_page() method. You can attach the page to the options (Settings) or themes (Appearance) menus or any custom menu. |
| 139 | |
| 140 | **type** |
| 141 | (required) |
| 142 | |
| 143 | What type of admin menu page to create. Accepts: |
| 144 | |
| 145 | - "options" - A subpage of the Settings menu |
| 146 | - "themes" - A subpage of the Appearance menu |
| 147 | - "submenu" - A subpage of any top-level menu item |
| 148 | |
| 149 | **args** |
| 150 | |
| 151 | An array of properties to pass to the page. |
| 152 | |
| 153 | *id* |
| 154 | (required) |
| 155 | |
| 156 | All settings attached to this page will be stored with the page ID and can be retrieved with get_options( $page_id ). |
| 157 | |
| 158 | *title* |
| 159 | (required) |
| 160 | |
| 161 | This will be displayed at the top of the page. |
| 162 | |
| 163 | *menu_title* |
| 164 | (required) |
| 165 | |
| 166 | The title to display in the menu. |
| 167 | |
| 168 | *description* |
| 169 | (optional) |
| 170 | |
| 171 | Actually, I think this one isn't used at the moment. |
| 172 | |
| 173 | *capability* |
| 174 | (required) |
| 175 | |
| 176 | The user permissions access level (capability in WP terms) required to access and edit this page. |
| 177 | |
| 178 | *default_tab* |
| 179 | (optional) |
| 180 | |
| 181 | If your page will have multiple tabs, you need to specify a default tab to display when the page is initially loaded. This must match the ID used in the add_section() method. *Leave this parameter out if you don't need any tabs.* |
| 182 | |
| 183 | ``` |
| 184 | $sap->add_page( |
| 185 | $type, |
| 186 | $args = array( |
| 187 | 'id' => 'my-settings', |
| 188 | 'title' => __( 'Page Title', 'textdomain' ), |
| 189 | 'menu_title' => __( 'menu Title', 'textdomain' ), |
| 190 | 'description' => '', |
| 191 | 'capability' => 'manage_options' |
| 192 | 'default_tab' => 'tab-one', |
| 193 | ) |
| 194 | ); |
| 195 | ``` |
| 196 | |
| 197 | ### sapLibrary::add_section() |
| 198 | Create a new section to attach it to an existing page. |
| 199 | |
| 200 | Sections can act as Tabs or as internal sections within the normal settings flow of a Tab or Page. In other words, you can define a section as a tab, attach a section to another section which is acting as a tab, or ignore tabs altogether to display all of your sections at once. The example below adds a tab and then adds a sub-section to that tab. |
| 201 | |
| 202 | **page_id** |
| 203 | |
| 204 | Page this section should be attached to. Must match the id passed in add_page(). |
| 205 | |
| 206 | **args** |
| 207 | |
| 208 | An array of properties to pass to the section. |
| 209 | |
| 210 | *id* |
| 211 | |
| 212 | (required) |
| 213 | Unique slug to which settings will be attached. |
| 214 | |
| 215 | *title* |
| 216 | (required) |
| 217 | |
| 218 | This will be displayed at the top of the settings section. |
| 219 | |
| 220 | *description* |
| 221 | (optional) |
| 222 | |
| 223 | An optional description to display below the title. |
| 224 | |
| 225 | *is_tab* |
| 226 | (optional) |
| 227 | |
| 228 | Set this to true if this section should act like a tab. |
| 229 | |
| 230 | *tab* |
| 231 | (optional) |
| 232 | |
| 233 | Use this to attach a section to an existing tab. |
| 234 | |
| 235 | #### Add a section to a page with no tabs: |
| 236 | ``` |
| 237 | $sap->add_section( |
| 238 | $page_id, |
| 239 | $args = array( |
| 240 | 'id' => 'basic-details-section', |
| 241 | 'title' => __( 'Basic Details', 'textdomain' ), |
| 242 | 'description' => __( 'This section includes some basic details for you to configure.', 'textdomain' ) |
| 243 | ) |
| 244 | ); |
| 245 | ``` |
| 246 | |
| 247 | #### Add a tab and a sub-section to a page with tabs: |
| 248 | ``` |
| 249 | /** |
| 250 | * Create a section that acts as a tab with the is_tab parameter. |
| 251 | */ |
| 252 | $sap->add_section( |
| 253 | $page_id, |
| 254 | $args = array( |
| 255 | 'id' => 'tab-one', |
| 256 | 'title' => __( 'Tab One', 'textdomain' ), |
| 257 | 'description' => __( 'This tab includes some settings for you to configure.', 'textdomain' ), |
| 258 | 'is_tab' => true, |
| 259 | ) |
| 260 | ); |
| 261 | |
| 262 | /** |
| 263 | * Create a sub-section of the tab we just created with the tab parameter. |
| 264 | */ |
| 265 | $sap->add_section( |
| 266 | $page_id, |
| 267 | $args = array( |
| 268 | 'id' => 'section-one-under-tab-one', |
| 269 | 'title' => __( 'Section One', 'textdomain' ), |
| 270 | 'description' => __( 'This section includes some settings for you to configure.', 'textdomain' ), |
| 271 | 'tab' => 'tab-one', |
| 272 | ) |
| 273 | ); |
| 274 | ``` |
| 275 | |
| 276 | ### sapLibrary::add_setting() |
| 277 | Create a new setting and attach to an existing section. |
| 278 | |
| 279 | There are several types of settings, each with their own input arguments. I'll try to document it more in the future. For now, check out the AdminPageSetting.*.class.php files in /classes/. |
| 280 | |
| 281 | **page_id** |
| 282 | (required) |
| 283 | |
| 284 | Page this setting should be attached to. Must match the id passed in add_page(). |
| 285 | |
| 286 | **section_id** |
| 287 | (required) |
| 288 | |
| 289 | Section this setting should be attached to. Must match the id passed in add_setting(). |
| 290 | |
| 291 | **type** |
| 292 | (required) |
| 293 | |
| 294 | Type of setting to add. There are currently several types supported and you can extend the library with your own. I'll try to document this further. For now, you can see all the types supported by default at sapLibrary::get_setting_classname(). |
| 295 | |
| 296 | **args** |
| 297 | |
| 298 | An array of properties to pass to the setting. |
| 299 | |
| 300 | *id* |
| 301 | (required) |
| 302 | |
| 303 | Unique slug under which the setting will be saved. You would then retrieve the setting with: |
| 304 | |
| 305 | ``` |
| 306 | $options = get_option( $page_id ); |
| 307 | $options[$setting_id]; |
| 308 | ``` |
| 309 | |
| 310 | *title* |
| 311 | (required) |
| 312 | |
| 313 | Title of the setting. Typically acts as the field label. |
| 314 | |
| 315 | *description* |
| 316 | (optional) |
| 317 | |
| 318 | An optional description to display with the setting. Useful for instructions. |
| 319 | |
| 320 | *...* |
| 321 | |
| 322 | Several setting types have additional parameters. I'll try to document them further. |
| 323 | |
| 324 | ``` |
| 325 | $sap->add_setting( |
| 326 | $page_id, |
| 327 | $section_id, |
| 328 | $type, |
| 329 | array( |
| 330 | 'id' => 'my-first-setting', |
| 331 | 'title' => __( 'My First Setting', 'textdomain' ), |
| 332 | 'description' => __( 'A demonstration of my first setting', 'textdomain' ); |
| 333 | ... |
| 334 | ) |
| 335 | ); |
| 336 | ``` |
| 337 | |
| 338 | ### sapLibrary::add_admin_menus() |
| 339 | Once everything is configured, run this method to register the pages with WordPress. |
| 340 | |
| 341 | ``` |
| 342 | // Before you run add_admin_menus, filter the whole library so that |
| 343 | // third-party addons can hook into your settings page to add new settings |
| 344 | // or adjust existing ones. |
| 345 | $sap = apply_filters( 'sap_page_setup', $sap ); |
| 346 | |
| 347 | $sap->add_admin_menus(); |
| 348 | ``` |
| 349 | |
| 350 | ### Backwards Compatibility |
| 351 | Version 2.0 introduced changes which break backwards compatibility due to the way that the library now stores data in the database. If you are upgrading the version of this library used in your plugin or theme, you must call ```$sap->port_data(2);``` **after** you have declared all of your settings but **before** you call ```$sap->add_admin_menus();```. |
| 352 | |
| 353 | *Note: to ensure all of the old options are found and ported, you shouldn't change any of the structure or ids of your settings. Just drop this method into your existing flow.* |
| 354 | |
| 355 | This changes the way that your settings are stored in the database. Previously, each setting was stored as its own option. Now all the settings on a page are stored in one row. |
| 356 | |
| 357 | You will need to update your plugin to retrieve the settings from their new location. If you previously accessed a setting this way: |
| 358 | |
| 359 | ``` |
| 360 | $my_setting = get_option( $my_setting_id ); |
| 361 | ``` |
| 362 | |
| 363 | You should now access the setting this way: |
| 364 | |
| 365 | ``` |
| 366 | $all_page_settings = get_option( $settings_page_id ); |
| 367 | $all_page_settings[ $my_setting_id ]; |
| 368 | ``` |
| 369 | |
| 370 | ## Changelog |
| 371 | |
| 372 | - 2.4.0 - 2020-12-04 |
| 373 | - Updating to make this a more global library that can be used by multiple plugins. |
| 374 | |
| 375 | - 2.3.0 - 2019-03-18 |
| 376 | - Update pickadate.js to 3.6.1 to fix regression in Chromium |
| 377 | https://github.com/amsul/pickadate.js/issues/1138 |
| 378 | |
| 379 | - 2.1.1 - 2018-09-26 |
| 380 | - Allow address geolookup field to receive a Google Maps API key |
| 381 | - Use https when requesting google maps lookup |
| 382 | |
| 383 | - 2.1 - 2017-04-21 |
| 384 | - Add an Image setting type |
| 385 | |
| 386 | - 2.0.1 - 2017-03-14 |
| 387 | - Allow settings to receive $args passed to add_settings_field |
| 388 | |
| 389 | - 2.0 - 2015-10-28 |
| 390 | - Allow page capability to be modified after the page class is instantiated |
| 391 | |
| 392 | - 2.0.a.10 - 2015-08-19 |
| 393 | - Use h1 tags for page titles, in line with WP 4.3 changes |
| 394 | - Check for has_position before calling on a setting, in case of custom third-party settings being loaded |
| 395 | - Update pickadate.js lib |
| 396 | |
| 397 | - 2.0.a.9 - 2014-11-12 |
| 398 | - SelectPost: Use WP_Query instead of get_posts() so that filters can effect the list |
| 399 | - Require translateable strings to be declared when adding the setting so the library can conform to the upcoming single textdomain best practice in the .org repos |
| 400 | |
| 401 | - 2.0.a.7 - 2014-08-20 |
| 402 | - Only enqueue assets on appropriate admin pages to prevent version conflicts and be a good citizen |
| 403 | - Enforce stored date/time formats so date format is reliable |
| 404 | |
| 405 | - 2.0.a.6 - 2014-08-12 |
| 406 | - Add Google Map Address component |
| 407 | - Custom settings loaded through the extension path should not use versions |
| 408 | |
| 409 | - 2.0.a.5 - 2014-05-15 |
| 410 | - Fix a bug with the Textarea component callback |
| 411 | |
| 412 | - 2.0.a.4 - 2014-05-15 |
| 413 | - Only load assets when component is called |
| 414 | - Revert adding version number to script handles |
| 415 | - Fix localized script handler for Scheduler |
| 416 | - Fix pickadate CSS rule specificity |
| 417 | |
| 418 | - 2.0.a.3 - 2014-05-14 |
| 419 | - Fix undefined function error in Scheduler javascript when using Firefox |
| 420 | - Add version number to style and script handles so different versions will be enqueued |
| 421 | |
| 422 | - 2.0.a.2 - 2014-05-11 |
| 423 | - Add support for top-level menus |
| 424 | - Support line breaks in textarea components |
| 425 | |
| 426 | - 2.0.a.1 - 2014-04-03 |
| 427 | - Save all data on a page as one row in wp_options |
| 428 | |
| 429 | - 1.1 - never released |
| 430 | - Support themes pages |
| 431 | - Support submenu pages for custom menu items |
| 432 | |
| 433 | - 1.0 - 2013-11-20 |
| 434 | - Initial release |
| 435 |