https://github.com/iconicwp/WordPress-Settings-Framework

A settings framework for the WordPress settings API
https://github.com/iconicwp/WordPress-Settings-Framework

Last synced: 3 months ago
JSON representation

A settings framework for the WordPress settings API

• Host: GitHub
• URL: https://github.com/iconicwp/WordPress-Settings-Framework
• Owner: iconicwp
• License: mit
• Created: 2012-08-27T13:50:34.000Z (about 12 years ago)
• Default Branch: master
• Last Pushed: 2024-07-26T07:29:14.000Z (4 months ago)
• Last Synced: 2024-07-29T04:11:32.277Z (3 months ago)
• Language: PHP
• Size: 2.07 MB
• Stars: 333
• Watchers: 27
• Forks: 66
• Open Issues: 21
• Metadata Files:
  • Readme: README.md
  • Changelog: changelog.txt
  • License: LICENSE

Awesome Lists containing this project

• awesome-wordpress - WordPress Settings Framework

README

        
WordPress Settings Framework

============================

The WordPress Settings Framework aims to take the pain out of creating settings pages for your WordPress plugins

by effectively creating a wrapper around the WordPress settings API and making it super simple to create and maintain

settings pages.

This repo is actually a working plugin which demonstrates how to implement WPSF in your plugins. See `wpsf-test.php`

for details.

Setting Up Your Plugin

----------------------

1. Create a folder "wp-settings-framework" in the root of your plugin folder, containing `wp-settings-framework.php` and the "assets" folder.

2. Create a "settings" folder in your plugin root.

3. Create a settings file in your new "settings" folder (e.g. `settings-general.php`)

Now you can set up your plugin like:

```php

class WPSFTest {

	/**

	 * @var string

	 */

	private $plugin_path;

	/**

	 * @var WordPressSettingsFramework

	 */

	private $wpsf;

	/**

	 * WPSFTest constructor.

	 */

	function __construct() {

		$this->plugin_path = plugin_dir_path( __FILE__ );

		// Include and create a new WordPressSettingsFramework

		require_once( $this->plugin_path . 'wp-settings-framework/wp-settings-framework.php' );

		$this->wpsf = new WordPressSettingsFramework( $this->plugin_path . 'settings/settings-general.php', 'prefix_settings_general' );

		// Add admin menu

		add_action( 'admin_menu', array( $this, 'add_settings_page' ), 20 );

		

		// Add an optional settings validation filter (recommended)

		add_filter( $this->wpsf->get_option_group() . '_settings_validate', array( &$this, 'validate_settings' ) );

	}

	/**

	 * Add settings page.

	 */

	function add_settings_page() {

		$this->wpsf->add_settings_page( array(

			'parent_slug' => 'woocommerce',

			'page_title'  => __( 'Page Title', 'text-domain' ),

			'menu_title'  => __( 'menu Title', 'text-domain' ),

			'capability'  => 'manage_woocommerce',

		) );

	}

	/**

	 * Validate settings.

	 * 

	 * @param $input

	 *

	 * @return mixed

	 */

	function validate_settings( $input ) {

		// Do your settings validation here

		// Same as $sanitize_callback from http://codex.wordpress.org/Function_Reference/register_setting

		return $input;

	}

	// ...

}

```

Your settings values can be accessed like so:

```php

// Get settings

$this->wpsf->get_settings();

```

This will get either the saved setting values, or the default values that you set in your settings file.

Or by getting individual settings:

```php

// Get individual setting

$setting = wpsf_get_setting( 'prefix_settings_general', 'general', 'text' );

```

The Settings Files

------------------

The settings files work by filling the global `$wpsf_settings` array with data in the following format:

```php

$wpsf_settings[] = array(

    'section_id' => 'general', // The section ID (required)

    'section_title' => 'General Settings', // The section title (required)

    'section_description' => 'Some intro description about this section.', // The section description (optional)

    'section_order' => 5, // The order of the section (required)

    'fields' => array(

        array(

            'id' => 'text',

            'title' => 'Text',

            'desc' => 'This is a description.',

            'placeholder' => 'This is a placeholder.',

            'type' => 'text',

            'default' => 'This is the default value'

        ),

        array(

            'id' => 'select',

            'title' => 'Select',

            'desc' => 'This is a description.',

            'type' => 'select',

            'default' => 'green',

            'choices' => array(

                'red' => 'Red',

                'green' => 'Green',

                'blue' => 'Blue'

            )

        ),

        // add as many fields as you need...

    )

);

```

Valid `fields` values are:

* `id` - Field ID

* `title` - Field title

* `desc` - Field description

* `conditional_desc` - Array of conditional field value descriptions (for select)

* `placeholder` - Field placeholder

* `type` - Field type (text/password/textarea/select/radio/checkbox/checkboxes/color/file/editor/code_editor)

* `default` - Default value (or selected option)

* `choices` - Array of options (for select/radio/checkboxes)

* `mimetype` - Any valid mime type accepted by Code Mirror for syntax highlighting (for code_editor)

See `settings/example-settings.php` for an example of possible values.

API Details

-----------

    new WordPressSettingsFramework( string $settings_file [, string $option_group = ''] )

Creates a new settings [option_group](http://codex.wordpress.org/Function_Reference/register_setting) based on a setttings file.

* `$settings_file` - path to the settings file

* `$option_group` - optional "option_group" override (by default this will be set to the basename of the settings file)

wpsf_get_setting( $option_group, $section_id, $field_id )


Get a setting from an option group

* `$option_group` - option group id.

* `$section_id` - section id (change to `[{$tab_id}_{$section_id}]` when using tabs.

* `$field_id` - field id.

wpsf_delete_settings( $option_group )


Delete all the saved settings from a option group

* `$option_group` - option group id

Actions & Filters

---------------

**Filters**

* `wpsf_register_settings_[option_group]` - The filter used to register your settings. See `settings/example-settings.php` for an example.

* `[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.

* `wpsf_defaults_[option_group]` - Default args for a settings field

**Actions**

* `wpsf_before_field_[option_group]` - Before a field HTML is output

* `wpsf_before_field_[option_group]_[field_id]` - Before a field HTML is output

* `wpsf_after_field_[option_group]` - After a field HTML is output

* `wpsf_after_field_[option_group]_[field_id]` - After a field HTML is output

* `wpsf_before_settings_[option_group]` - Before settings form HTML is output

* `wpsf_after_settings_[option_group]` - After settings form HTML is output

* `wpsf_before_settings_fields_[option_group]` - Before settings form fields HTML is output (inside the ``)

* `wpsf_do_settings_sections_[option_group]` - Settings form fields HTMLoutput (inside the ``)

* `wpsf_do_settings_sections_[option_group]` - Settings form fields HTMLoutput (inside the ``)

* `wpsf_before_tab_links_[option_group]` - Before tabs HTML is output

* `wpsf_after_tab_links_[option_group]` - After tabs HTML is output

Credits

-------

The WordPress Settings Framework was created by [Gilbert Pellegrom](http://gilbert.pellegrom.me) from [Dev7studios](http://dev7studios.com) and maintained by [James Kemp](https://jckemp.com) from [Iconic](https://iconicwp.com)

Please contribute by [reporting bugs](https://github.com/jamesckemp/WordPress-Settings-Framework/issues) and submitting [pull requests](https://github.com/jamesckemp/WordPress-Settings-Framework/pulls).

Want to say thanks? [Consider tipping me](https://www.paypal.me/jamesckemp).