A simplification of the core WordPress settings API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.gitignore
README.mdown
composer.json
display-callbacks.php
package.json
sanitize-callbacks.php
voce-settings-api.php

README.mdown

Voce Settings API

Contributors: prettyboymp, kevinlangleyjr, banderon, voceplatforms
Tags: settings, api
Requires at least: 3.3
Tested up to: 4.2.2
Stable tag: 0.5.3
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Description

A simplification of the core WordPress settings API

Installation

As theme or plugin dependency:

After dropping the plugin into the containing theme or plugin, add the following:

<?php
if( ! class_exists( 'Voce_Settings_API' ) ) {
	require_once( $path_to_voce_settings_api . '/voce-settings-api.php' );
}
?>

Usage

The Voce_Settings_API is used as a singleton so you can add settings to pages that are created elsewhere just by using the same page_key. The singleton instance can be retreived by using Voce_Settings_API::GetInstance() and most methods can be chained to easily create multiple groups and setting fields per page.

Registering a Settings Page

Pages are registered through the add_page() method of the Voce_Settings_API, which is accessed through the singleton instance of itself.

Parameters

  • $page_title (string) - A string used at the top of the settings page
  • $menu_title (string) - A string used as the title of the page either in the admin menu or if specified, an admin submenu
  • $page_key (string) - A unique string used as the page key for the settings page
  • $capability (string) - The capability level for users to be able to see and edit settings on the page
  • $description (string) - Short description of the page
  • $parent_page (string) - Slug for parent page, leave empty to create new menu item

Registering a Settings Group

Groups are registered through the add_group() method of the Voce_Settings_Page class.

Parameters

  • $title (string) - A string used at the top of the settings group
  • $group_key (string) - A unique string used as the group key for the settings
  • $capability (string) - The capability level for users to be able to see and edit settings within the group
  • $description (string) - Short description of the group

Registering a Setting Field

Setting fields are registered through the add_setting() method of the Voce_Settings_Group class.

Parameters

  • $title (string) - A string used within the label for the setting field
  • $setting_key (string) - A unique string used as the setting key
  • $args (array) - Array of arugments for the setting
<?php
Voce_Settings_API::GetInstance()->add_page( 'Site Settings', 'Site Settings', 'site-settings', 'manage_options', 'General settings for site', 'options-general.php' )
	->add_group( 'Social Settings', 'social-settings' )
		->add_setting( 'Station Facebook Page URL', 'facebook_page_url', array(
			'sanitize_callbacks' => array( 'vs_sanitize_url' )
		))->group
		->add_setting( 'Google+ Profile', 'google_plus_profile', array(
			'sanitize_callbacks' => array( 'vs_sanitize_url' )
		))->group->page
	->add_group( 'Analytic Settings', 'analytic-settings' )
		->add_setting( 'Google Analytics Tracking ID', 'ga_id', array(
			'display_callback' => function( $value, $setting, $args ){
				// write your own display method or use one of the built in options listed below.
				return false;
			},
			'sanitize_callbacks' => array( function( $value, $setting, $args ){
				// write your own sanitization methods or use one of the built in which are listed below.
				return $value;
		} ) ) );
?>

Getting a setting value

Using the get_settting() method of the Voce_Settings_API, you can retreive the value of a setting by passing in the setting key, group key, and optionally the default value to return if no value has been set yet.

<?php
	$value = Voce_Settings_API::GetInstance()->get_setting($setting_key, $group_key, $default_value);
?>

Display Methods

  • vs_display_text_field Default
  • vs_display_dropdown
  • vs_display_textarea
  • vs_display_checkbox

Sanitization Methods

  • vs_sanitize_text Default
  • vs_sanitize_checkbox
  • vs_sanitize_url
  • vs_sanitize_email
  • vs_sanitize_dropdown

To enqueuing JS and/or CSS on settings pages

<?php
add_action( 'vs_admin_enqueue_scripts', function( $vs_page ){
	foreach( $vs_page->groups as $group ){
		foreach( $group->settings as $setting ){
			if( $setting->args['display_callback'] == 'display_callback_of_custom_setting_field' ){
				wp_enqueue_script('custom-setting-field-js', plugins_url( 'js/custom-setting-field-js.js', __FILE__ ), array( 'jquery' ) );
				wp_enqueue_style( 'custom-setting-field-css', plugins_url( 'css/custom-setting-field-css.css', __FILE__ ) );
				break 2;
			}
		}
	}
} );
?>

Changelog

Please refer to full changelog at https://github.com/voceconnect/voce-settings-api/releases.