KC Settings WordPress Plugin

Easily create plugin/theme settings page, custom fields metaboxes and term meta, and user meta settings.

About

This plugin is my attempt to simplify the process of adding a setting page for the WordPress themes I was working on. It was originally inspired by the Hybrid theme. I then re-wrote it to utilize the amazing WordPress' Settings API after reading Otto's article.

Installation

As a dependency

In this mode, KC Settings will act as a dependency for you plugin/theme. You should have it installed and activated all the time.

1. Install the plugin either by using WordPress plugin installer or manually copying it to WordPress' plugins directory.
2. Activate the plugin.

Must Use Plugin

To have KC Settings active all the time, you need to install it inside the mu-plugins directory. To do that, follow these steps:

1. Download the plugin and unpack it.
2. Using your favorite FTP client, go to your site's wp-content directory.
3. Create mu-plugins directory if it doesn't exist inside wp-content yet.
4. Upload kc-settings.php file and kc-settings-inc directory into the mu-plugins directory.
5. You're done. KC Settings should be active all the time.

Builtin

If you think you'd rather have the KC Setting's functionality builtin with your plugin/theme (so user won't have to install it), follow this steps:

1. Copy the kc-settings directory into your plugin/theme directory.
2. Include the main plugin file, eg: require_once(dirname(__FILE__) . '/kc-settings/kc-settings.php');

The only drawback of using this method is that you will have to overwrite the plugin's files each time it has an update. Your options arrays should be safe as long as you keep them outside the plugin's directory and use different names than the originals.

The options

There are a few sample options files included in the sample directory. Copy (examine and modify) the sample options files included in the sample directory to your plugin/theme directory and then include them from your theme/plugin, eg. require_once( TEMPLATEPATH . '/__theme_options.php');

Getting the data

Theme/plugin settings

• All data

  $var = kc_get_option( 'prefix' );

  Or, you can also use WordPress' builtin function:

  $var = get_option( 'prefix_settings' );

• Section

  $var = kc_get_option( 'prefix', 'section_id' );

• Field

  $var = kc_get_option( 'prefix', 'section_id', 'field_id' );

Custom field / Post metadata

Just use standard WordPress function, but prefix the meta key with an underscore, for example:

$var = get_post_meta( 'post_id', '_field_id', true );
or:
$var = get_metadata( 'post', 'post_id', '_field_id', true );

Term Metadata

You can use standard WordPress function, for example:

$var = get_metadata( 'term', 'term_id', 'field_id', true );

User Metadata

You can use standard WordPress function, for example:

$var = get_user_meta( 'user_id', 'field_id', true );
or:
$var = get_metadata( 'user', 'user_id', 'field_id', true );

Validation/sanitation

All options are filtered before added to the database. You can add your own filter(s) by using one ore more of these filters:

Theme/plugin settings

• By prefix:

  Filter name:

  kcv_setting_prefix

  Example:

  add_filter( 'kcv_setting_myPrefix', 'my_filter_function' );

  function my_filter_function( $data ) {
  	// .... do something with the POST data
  	return $data;
  }
  							

• By prefix & section ID:

  Filter name:

  kcv_setting_prefix_sectionID

  Example:

  add_filter( 'kcv_setting_myPrefix_mySectionID', 'my_filter_function' );

  function my_filter_function( $section_data ) {
  	// .... do something with the POST data
  	return $section_data;
  }
  							

• By prefix & field type:

  Filter name:

  kcv_setting_prefix_fieldType

  Example:

  add_filter( 'kcv_setting_myPrefix_textarea', 'my_filter_function' );

  function my_filter_function( $field_data ) {
  	// .... do something with the POST data
  	return $field_data;
  }
  							

• By prefix, section ID & field ID:

  Filter name:

  kcv_setting_prefix_sectionID_fieldID

  Example:

  add_filter( 'kcv_setting_myPrefix_mySectionID_myFieldID', 'my_filter_function' );

  function my_filter_function( $field_data ) {
  	// .... do something with the POST data
  	return $field_data;
  }
  							

Metadata

You can also filter your metadata values using the filters below. Note that there are three arguments passed to these filters, and they're valid for the three metadata types (post, term and user):

1. $nu_val: The new metadata value from the user
2. $section: The section array
3. $field: The field array

Example validation/sanitation function for metadata:

function my_filter_function( $nu_val, $section, $field ) {
	//... do someting with the data
	return $nu_val;
}
			

Custom Fields / Post Meta

• By post type:

  Filter name:

  kcv_postmeta_postType

  Example:

  add_filter( 'kcv_postmeta_post', 'my_filter_function', 10, 3 );

• By post type & field type:

  Filter name:

  kcv_postmeta_postType_fieldType

  Example:

  add_filter( 'kcv_postmeta_post_textarea', 'my_filter_function', 10, 3 );

• By post type & section ID:

  Filter name:

  kcv_postmeta_postType_sectionID

  Example:

  add_filter( 'kcv_postmeta_post_mySectionID', 'my_filter_function', 10, 3 );

• By post type, section ID & field ID:

  Filter name:

  kcv_postmeta_postType_sectionID_fieldID

  Example:

  add_filter( 'kcv_postmeta_post_mySectionID_fieldID', 'my_filter_function', 10, 3 );

Term meta

The filters used for validating term meta values are very similiar with custom fields' filters. The only difference is that you'd use taxonomy name instead of post type name. Also the filters are prefixed with kcv_termmeta_ instead of kcv_postmeta_. Here are the filters used:

And here are the filters:

• By taxonomy:

  Filter name:

  kcv_termmeta_taxonomy

  Example:

  add_filter( 'kcv_termmeta_category', 'my_filter_function', 10, 3 );

• By taxonomy & field type:

  Filter name:

  kcv_termmeta_taxonomy_fieldType

  Example:

  add_filter( 'kcv_termmeta_category_textarea', 'my_filter_function', 10, 3 );

• By taxonomy & section ID:

  Filter name:

  kcv_termmeta_taxonomy_sectionID

  Example:

  add_filter( 'kcv_termmeta_category_mySectionID', 'my_filter_function', 10, 3 );

• By taxonomy, section ID & field ID:

  Filter name:

  kcv_termmeta_taxonomy_sectionID_fieldID

  Example:

  add_filter( 'kcv_termmeta_category_mySectionID_fieldID', 'my_filter_function', 10, 3 );

User meta

Validation/sanitation filters for user meta are very similiar with post and term meta. However, with user meta, you'll get fewer filters:

• Filter everything:

  Filter name:

  kcv_usermeta

  Example:

  add_filter( 'kcv_usermeta', 'my_filter_function', 10, 3 );

• By field type:

  Filter name:

  kcv_usermeta_fieldType

  Example:

  add_filter( 'kcv_usermeta_textarea', 'my_filter_function', 10, 3 );

• By section ID:

  Filter name:

  kcv_usermeta_sectionID

  Example:

  add_filter( 'kcv_usermeta_mySectionID', 'my_filter_function', 10, 3 );

• By section ID & field ID:

  Filter name:

  kcv_usermeta_sectionID_fieldID

  Example:

  add_filter( 'kcv_usermeta_mySectionID_fieldID', 'my_filter_function', 10, 3 );

TODO

• Add 'component' field type
• Add 'multiple' field type

Support

If you think you found a bug, need some features added, have questions or just want to say hi, please feel free to contact me.