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.

Features

Currently you can use this plugin for these types of settings:

• Plugin/theme settings
• Post metadata (custom fields)
• Term metadata
• User metadata

For plugin/theme setting pages, you have the option to choose between 'plain' and 'metaboxes' display types. For post metaboxes/custom fields and plugin/theme setting pages with display time set to metaboxes, you can freely set the metaboxes positions/contexts and priorities.

Supported input types:

• Single line text (text)
• Multiple lines text (textarea)
• File (file)
• Date (date)
• Color (color)
• Checkboxes (checkbox)
• Radio (radio)
• Dropdown select (select)
• Multiple select (multiselect)
• Multiple text input (multiinput)
• Custom function (special)

If you think there are other input types that need to be added, don't hesitate to contact me!

Installation

Just install it like any other WordPress plugins :)

The options

You can either create the settings using the Builder by going to Settings » KC Settings, or create them manually.

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 );

• Default values

  If you have set a default value for your field, you can get it like this:

  $var = kc_get_default( $type, $prefix, $section_id, $field_id );

  Note:
  For now, this only works for plugin/theme settings, so the $type argument should always be set to 'plugin'. $section_id and $field_id are optionals

Return values

• Single line text (string)
• Multiple lines text (string)
• File (array)
• Date (string)
• Color (string)
• Checkboxes (array)
• Radio (string)
• Dropdown select (string)
• Multiple select (array)
• Multiple text input (array)
• Custom function (mixed)

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 );

Helpers

Since version 2.6, KC Settings comes with options helpers to make your life easier ;)

Variables

There are a few variables you can use to pass as field options:

• kcSettings_options::$nav_menus
• kcSettings_options::$image_sizes
• kcSettings_options::$image_sizes_default
• kcSettings_options::$image_sizes_custom
• kcSettings_options::$post_types (public post types)
• kcSettings_options::$post_types_all
• kcSettings_options::$taxonomies (public taxonomies)
• kcSettings_options::$taxonomies_all
• kcSettings_options::$post_statuses
• kcSettings_options::$roles
• kcSettings_options::$yesno

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.