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
• Theme customizer (since version 2.7.4, detachable since version 2.7.6)
• Post metadata (custom fields)
• Term metadata
• User metadata
• Nav menu item metadata (since version 2.7.8)
• Nav menu metadata (since version 2.7.9)

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
• Email: email
• Color: color
• Date: date (not supported in theme customizer and menu item metadata)
• Month: month (not supported in theme customizer and menu item metadata)
• Time: time (no polyfill yet, not supported in theme customizer and menu item metadata)
• Datetime: datetime (no polyfill yet, not supported in theme customizer and menu item metadata)
• Local Datetime: datetime-local (no polyfill yet, not supported in theme customizer and menu item metadata)
• Week: week (no polyfill yet, not supported in theme customizer and menu item metadata)
• Radio: radio
• Checkboxes: checkbox (not supported in theme customizer)
• Dropdown select: select
• Multiple select: multiselect (not supported in theme customizer)
• Number: number
• Password: password
• Telephone: tel
• File: file (not supported in theme customizer and menu item metadata)
• Repeatable fields: multiinput (not supported in theme customizer, menu and menu item metadata)
• WordPress Editor: editor (not supported in theme customizer, menu and menu item metadata)
• Custom: special (not supported in theme customizer)

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

Installation

Normal

Just install it like any other WordPress plugins :)

As a must-use plugin

Copy kc-settings.php and kc-settings-inc to your wp-content/mu-plugins directory (don't just copy the kc-settings directory).

Bundle with plugin/theme

If you want to bundle KC Settings with your theme/plugin, follow these steps:

1. Copy kc-settings.php and kc-settings-inc to your theme/plugin directory (don't just copy the kc-settings directory).
2. Add this block of code to your theme's function.php file:

   function mytheme_load_kc_settings() {
   	// Load the settings array
   	require_once get_template_directory() . '/my-settings.php';
   
   	if ( class_exists('kcSettings') )
   		return;
   
   	// This is to avoid the conflict when KC Settings is bundled in your theme/plugin and installed as plugin
   	if ( is_admin() ) {
   		global $pagenow;
   		if (
   			$pagenow === 'plugins.php'
   			&& (
   				// Single plugin activation
   				( isset($_REQUEST['action']) && $_REQUEST['action'] === 'activate' && isset($_REQUEST['plugin']) && $_REQUEST['plugin'] === 'kc-settings/kc-settings.php' )
   				|| (
   					// Bulk activation
   					!empty($_POST)
   					&& ( ( isset($_POST['action']) && $_POST['action'] === 'activate-selected' ) || ( isset($_POST['action2']) && $_POST['action2'] === 'activate-selected' ) )
   					&& ( isset($_POST['checked']) && is_array($_POST['checked']) && in_array('kc-settings/kc-settings.php', $_POST['checked']) )
   				)
   			)
   		)
   			return;
   	}
   
   	// Use get_stylesheet_directory() if you're doing this in a child theme
   	require_once get_template_directory() . '/kc-settings.php';
   	kcSettings::setup();
   }
   
   add_action( 'after_setup_theme', 'mytheme_load_kc_settings' );
   

   Note: The action hook should always be after_setup_theme even if you're bundling KC Settings in a plugin.

Bundle theme customizer only

If you only need the theme customizer module, copy the theme.php file from the kc-settings/kc-settings-inc/ to your theme's directory then add this block of code to your theme's function.php file:

function mytheme_load_kc_customizer() {
	// Load the settings array
	require_once get_template_directory() . '/mytheme-settings.php';

	if ( class_exists('kcSettings') )
		return;

	// Use get_stylesheet_directory() if you're doing this in a child theme
	require_once get_template_directory() . '/theme.php';
}
add_action( 'after_setup_theme', 'mytheme_load_kc_customizer', 99 );

Note: You need to make sure that your options array is valid, because the module won't do any validation. Also, I strongly suggest to rename the theme.php file to something else to avoid confusion :)

The options

You can either create the settings using the Builder by going to Settings » KC Settings, or create them manually. Note that theme customizer is not available in the Builder.

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 get_template_directory() . '/theme_options.php';

Getting the data

Theme/plugin settings

• All data

  $prefix = 'myPrefix';
  $var = kc_get_option( $prefix );
  // Or, you can also use WordPress' builtin function:
  $var = get_option( "{$prefix}_settings" );
  

• Section

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

• Field

  $prefix = 'myPrefix';
  $section_id = 'section_one';
  $field_id = 'field_one';
  $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:

  $prefix = 'myPrefix';
  $section_id = 'section_one';
  $field_id = 'field_one';
  $var = kc_get_default( 'plugin', $prefix, $section_id, $field_id );
  

Theme customization

Just use standard WordPress function, but using the prefix, section ID, and field ID as the first argument, for example:

$prefix = 'myPrefix';
$section_id = 'section_one';
$field_id = 'field_one';
$var = get_theme_mod( "{$prefix}_{$section_id}_{$field_id}" );  // Notice the underscores

If you have set a default value for the field and want to get it when the setting hasn't been changed:

$var = get_theme_mod( "{$prefix}_{$section_id}_{$field_id}", kc_get_default('theme', $prefix, $section_id, $field_id) );

Custom field / Post metadata & Nav menu item metadata

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

$post_id = 1;
$field_id = 'field_one';
$var = get_post_meta( $post_id, "_{$field_id}", true );  // Notice the underscore

Term Metadata & Nav Menu Metadata

You can use standard WordPress function, for example:

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

User Metadata

You can use standard WordPress function, for example:

$user_id = 1;
$field_id = 'field_one';
$var = get_user_meta( $user_id, $field_id, true );

Return values

• Single line text and most HTML5 inputs: string
• Multiple lines text: string
• File (single): string
• File (multiple): array
• Date: string
• Color: string
• Checkboxes: array
• Radio: string
• Dropdown select: string
• Multiple select: array
• Repeatable fields: array
• Custom function: mixed

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 metadata & Nav menu item metadata

• By post type:

  Filter name:

  kcv_postmeta_postType

  Example:

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

  Note: For menu item metadata, use nav_menu_item as the post type.

• 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 & Nav menu metadata

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

  Note: For nav menu, use nav_menu as the taxonomy name.

• 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

As of version 2.7.3, you can also use a callback as the options.

Links

• Support / bug report
• Feature request
• Donate / Contact