options panel

My Options Panel

   

Background

About a year ago i asked a question at WPSE and I'll Quote:

I found that the longest part of a plugin or theme development is creating the options panel, at least in my case. So i like to know what's your take on that. Do you use a ready made framework or class? And if so witch one? Or do you write it up from scratch? Use the settings API or plain options?

That Question has had a few good answers and i myself added a few i found over time, Not to mention that there are over a million of tutorials which out of them a few are actually good on how to add options panel to your theme or plugin, So whats the problem?

   

Problem

Well the Problem is that none of the tutorials and scripts out there let you hold all options as a single row in the database, meaning that if my theme or plugin have 217 options then i would need to create 217 rows in the database and even worse i would need to create 217 queries to get that data.

   

Solution

Very simple i took My Meta Box Class and changed it a bit to work as an admin panel class which stores all of the values in a single array in the options table of the database, added a bit of style and js code and i proudly present My Admin Page Class

   

ScreenShoots

Panel layout Simple fields Simple Fields
Image Upload and date Picker fields Time field Color Picker field
WYSIWYG editor fields Syntax code field Repeater Block field
WordPress Ready fields WordPress Ready fields Typography
Drag and drop sortable

   

Video Overview:

   

Features

  • Works with plugins as well as themes
  • Easily brand-able (via hooks).
  • Import Export features.
  • Available fields are:
    • Input
    • Textarea
    • Radio button
    • Checkbox
    • Select Dropdown
    • File Upload
    • Image Upload
    • WYSIWYG editor
    • Date Picker
    • Time Picker
    • Color Picker
    • Taxonomy List Dropdwon or checkboxes
    • Post list Dropdown or checkboxes
    • WordPress User Roles Dropdown or checkboxes
    • Syntax Highlighted Code Editor (PHP, CSS, HTML, JAVASCRIPT)
    • Typography Field (set of size, color, face, family fields)
    • Sortable Drag & Drop
    • Repeater Field which can be set as sortable
  • OOP Code all the way (which means easy to extend and modify).

   

Usage:

First thing you need to do is include the class

//include the main class file
require_once("admin-page-class/admin-page-class.php");

Then setup your Page configuration:

/**
* configure your admin page
*/
$config = array(
	'menu'=> 'settings', 				//sub page to settings page
	'page_title' => 'Demo Admin Page', 	//The name of this page
	'capability' => 'edit_themes', 		// The capability needed to view the page
	'option_group' => 'demo_options',	//the name of the option to create in the database
	'id' => 'admin_page', 				// Page id, unique per page
	'fields' => array(), 				// list of fields (can be added by field arrays)
	'local_images' => false, 			// Use local or hosted images (meta box images for add/remove)
	'use_with_theme' => false 			//change path if used with theme set to true, false for a plugin or anything else for a custom path(default false).
); 

Lets go over this quickly

  • menu - (string) the parent page to add this as sub page to, accepts:
    • 'dashboard' -> Dashboard menu
    • 'posts' -> Posts menu
    • 'media' -> Media menu
    • 'links' -> Links menu
    • 'pages' -> Pages menu
    • 'comments' -> Comments menu
    • 'theme' -> Appearance menu
    • 'plugins' -> Plugins menu
    • 'users' -> Users menu
    • 'tools' -> Tools menu
    • 'settings' -> Settings menu
    • 'CUSTOM' -> CUSTOM post type menu (replace CUSTOM with the name of the custom post type)
    • 'TOP' -> TOP menu slug (replace TOP with the slug of the top menu you want)

    Or if you want to add a new top level menu then set 'menu' as array with top set ex:

    'menu'=> array('top' => 'my_slug'),
    
  • page_title - (string) The name of the page and menu link text
  • capability - (string) The capability needed to view the page (read more at http://goo.gl/O49cW)
  • option_group - (string) the name of the option to create in the database.
  • id - (string) unique page id (must for top level pate)
  • fields - (array) list of fields to add (can be added by field arrays if you don't like the oop way then just add your fields here).
  • local_images - (boolean), Use local or hosted images (admin pages images for add/remove).
  • use_with_theme - (mixed|boolean|string), change path if used with theme set to true, false for a plugin or anything else for a custom path(default false).
  • icon_url - (string) (optional) - URL to the icon, decorating the Top-Level-Menu (Top level Only)
  • position - (string) (optional) - The position of the Menu in the admin menu(Top level Only)

I know it looks like a lot but most of the options are optional and you can see in the example i've used a selected few.

Next you need to initiate your admin Page:

/**
 * Initiate your admin page
 */
$options_panel = new BF_Admin_Page_Class($config);

Next define your tabs:

/**
 * define your admin page tabs listing
 */
$options_panel->OpenTabs_container('');
$options_panel->TabsListing(array(
   'links' => array(
   'options_1' =>  __('Simple Options'),
   'options_2' =>  __('Fancy Options'),
   'options_3' => __('Editor Options'),
   'options_4' => __('WordPress Options'),
   'options_5' =>  __('Repeater')
   )
));

lets go over it TabsListing function, it takes an array of links which are defined as 'id' => 'label' manner and you can see in the above example that i have defined 5 tabs.
   

Adding Fields

Moving on lets at fields to are tabs, first we open the tab:

// Open admin page first tab with the id options_1
$options_panel->OpenTab('options_1');

Then we add the fields to that tab:

/**
* Add fields to your admin page first tab
*
* Simple options:
* input text, checbox, select, radio
* textarea
*/
//title
$options_panel->Title("Simple Options");
//An optional description paragraph
$options_panel->addParagraph("This is a simple paragraph");
//text field
$options_panel->addText('text_field_id',array('name'=> 'My Text '));
//textarea field
$options_panel->addTextarea('textarea_field_id',array('name'=> 'My Textarea '));
//checkbox field
$options_panel->addCheckbox('checkbox_field_id',array('name'=> 'My Checkbox '));
//select field
$options_panel->addSelect('select_field_id',array('selectkey1'=>'Select Value1','selectkey2'=>'Select Value2'),array('name'=> 'My select ', 'std'=> array('selectkey2')));
//radio field
$options_panel->addRadio('radio_field_id',array('radiokey1'=>'Radio Value1','radiokey2'=>'Radio Value2'),array('name'=> 'My Radio Filed', 'std'=> array('radionkey2')));
// Close first tab
$options_panel->CloseTab();

You can see that i added a title, paragraph and a few other fields and the i closed the tab, lets add another one:

// Open admin page Second tab
$options_panel->OpenTab('options_2');
/**
* Add fields to your admin page 2nd tab
*
* Fancy options:
* image uploader
* date picker
* time picker
* color picker
*/
//title
$options_panel->Title("Fancy Options");
//Image field
$options_panel->addImage('image_field_id',array('name'=> 'My Image '));
//date field
$options_panel->addDate('date_field_id',array('name'=> 'My Date '));
//Time field
$options_panel->addTime('time_field_id',array('name'=> 'My Time '));
//Color field
$options_panel->addColor('color_field_id',array('name'=> 'My Color '));
// Close second tab
$options_panel->CloseTab();

once again very simple open a tab, add fields and close it, You get the point but k=just to complete the example I'll quickly add a few more:

// Open admin page 3rd tab
$options_panel->OpenTab('options_3');
/**
* Add fields to your admin page 3rd tab
*
* Editor options:
* WYSIWYG (tinyMCE editor)
* Syntax code editor (css,html,js,php)
*/
//title
$options_panel->Title("Editor Options");
//wysiwyg field
$options_panel->addWysiwyg('wysiwyg_field_id',array('name'=> 'My wysiwyg Editor '));
//code editor field
$options_panel->addCode('code_field_id',array('name'=> 'Code Editor ','syntax' => 'php'));
// Close 3rd tab
$options_panel->CloseTab();

// Open admin page 4th tab
$options_panel->OpenTab('options_4');
/**
* Add fields to your admin page 4th tab
*
* WordPress Options:
* Taxonomies dropdown
* posts dropdown
* Taxonomies checkboxes list
* posts checkboxes list
*
*/
//title
$options_panel->Title("WordPress Options");
//taxonomy select field
$options_panel->addTaxonomy('taxonomy_field_id',array('taxonomy' => 'category'),array('name'=> 'My Taxonomy Select'));
//posts select field
$options_panel->addPosts('posts_field_id',array('post_type' => 'post'),array('name'=> 'My Posts Select'));
//Roles select field
$options_panel->addRoles('roles_field_id',array(),array('name'=> 'My Roles Select'));
//taxonomy checkbox field
$options_panel->addTaxonomy('taxonomy2_field_id',array('taxonomy' => 'category','type' => 'checkbox_list'),array('name'=> 'My Taxonomy Checkboxes'));
//posts checkbox field
$options_panel->addPosts('posts2_field_id',array('post_type' => 'post','type' => 'checkbox_list'),array('name'=> 'My Posts Checkboxes'));
//Roles checkbox field
$options_panel->addRoles('roles2_field_id',array('type' => 'checkbox_list'),array('name'=> 'My Roles Checkboxes'));
// Close 4th tab
$options_panel->CloseTab();

// Open admin page 5th tab
$options_panel->OpenTab('options_5');
/*
* To Create a reapeater Block first create an array of fields
* use the same functions as above but add true as a last param
*/
$repeater_fields[] = $options_panel->addText('re_text_field_id',array('name'=> 'My Text '),true);
$repeater_fields[] = $options_panel->addTextarea('re_textarea_field_id',array('name'=> 'My Textarea '),true);
$repeater_fields[] = $options_panel->addCheckbox('re_checkbox_field_id',array('name'=> 'My Checkbox '),true);
$repeater_fields[] = $options_panel->addImage('image_field_id',array('name'=> 'My Image '),true);
// Then just add the fields to the repeater block
//repeater block
$options_panel->addRepeaterBlock('re_',array('inline' => false, 'name' => 'This is a Repeater Block','fields' => $repeater_fields));
//Close 5th tab
$options_panel->CloseTab();

and that is it you have a full functional admin options panel just like in the demo plugin which is included.

   

Getting Saved data

Once again to keep things easy and simple just use WordPress built-in functions to get the data but remember that its all save as one array which means all you need to do is call the data once with the name of the option_group you set the the beginning ex:

//get the data to an array
$data = get_option('demo_options');
//access each field by its id
echo $data['text_field_id'];

   

Download:

   

Documentation

Proper documentation will be added soon to the GitHub Wiki.

   

License

This Class is licensed under GNU version 3 which basically means you can do any thing you want.

Issues and bugs
If you have any issues or bugs please use the Issue Tracker and not the comments bellow!

Ohad Raz

WordPress Consultant, a WordPress Developer and a WordPress Freelancer With over 10 years experience in architecting web sites and applications. WordPress Development moderator and somethimes Plugin Developer.