Automattic's updates and new actions and method

README.txt → README.md

@@ -1,28 +1,44 @@
-//
-// CheezCap - Cheezburger Custom Administration Panel
-// (c) 2008 - 2011 Cheezburger Network (Pet Holdings, Inc.)
-// LOL: http://cheezburger.com
-// Source: http://github.com/cheezburger/cheezcap/
-// Authors: Kyall Barrows, Toby McKes, Stefan Rusek, Scott Porad
-// License: GNU General Public License, version 2 (GPL), http://www.gnu.org/licenses/gpl-2.0.html
-//
+CheezCap - Cheezburger Custom Administration Panel
+================
+* CheezCap - Cheezburger Custom Administration Panel
+* (c) 2008 - 2011 Cheezburger Network (Pet Holdings, Inc.)
+* LOL: http://cheezburger.com
+* Source: http://github.com/cheezburger/cheezcap/
+* Authors: Kyall Barrows, Toby McKes, Stefan Rusek, Scott Porad
+* UnLOLs by Mo Jangda ([email protected])
+* License: GNU General Public License, version 2 (GPL), http://www.gnu.org/licenses/gpl-2.0.html
+
+
+This is a fork of the original CheezCap developed by the fine Cheez-loving Cats over at ICHC. In has various bits of cleanup, the biggest being that it can be shared across multiple themes.
+
+The fork lives at https://github.com/mjangda/cheezcap
+
+"I'm In Yur Dashburd Tweakin' Yur Settings."
 
 ##
 ## Quick Start
 ##
 
-1.  Copy the CheezCap folder into your theme directory
-2.  Add the follwowing line to functions.php (if you don't have a functions.php, create one in your theme directory)
-
-      require_once('cheezcap/cheezcap.php'); 
-
-3.  Edit cheezcap/config.php
+1.  Copy the cheezcap folder into an appropriate location (maybe where you store your other shared plugins).
+2.  Add the following line to functions.php (if you don't have a functions.php, create one in your theme directory). Adjust the path as needed.
+<br/><br/><pre><code>
+	require_once( WP_PLUGINS_DIR . '/cheezcap/cheezcap.php');
+</code></pre><br/>
+3.  Use the included config-sample.php as a starting point to set up your options. Copy the modified version into your theme and include it.
+<br/><br/><pre><code>
+	require_once( dirname( __FILE__ ) . '/cheezcap-config.php');
+</code></pre><br/>
 4.  Sprinkle theme options around your code, like this:
-
+<br/><br/><pre><code>
+	global $cap;
 	if ($cap->my_boolean_option) {
 		// do stuff	
 	}
-
+</code></pre><br/>
+4b.  Or use the helper function
+<br/><br/><pre><code>
+	cheezcap_get_option( 'my_boolean_option', true, 'esc_html' );
+</code></pre><br/>
 5.  Enjoy!
 
 
@@ -31,7 +47,7 @@
 ## Background
 ##
 
-In order to use the same Wordpress theme for many different Wordpress sites, one of the things we've 
+In order to use the same WordPress theme for many different Wordpress sites, one of the things we've 
 done at Cheezburger is create themes with lots and lots of theme options.  CheezCap is a simple library 
 we've made for creating custom wp-admin panels really, really easily.
 
@@ -43,13 +59,10 @@ It's just that easy!
 ## 
 ## Installation
 ##
-Installation is a two step process.  First, copy the CheezCap folder into your theme directory.  Next,
-add the following line to functions.php in your theme (if you don't have a functions.php, create one
-in the root of your theme directory).
 
-    require_once('cheezcap/cheezcap.php'); 
+Follow the "Quick Start" instructions above.
 
-Finally, to verify that CheezCap has installed correctly, simply open wp-admin and look for the 
+Finally, to verify that CheezCap has installed correctly, simply open /wp-admin and look for the 
 "CheezCap Settings" link on the left navigation panel toward the bottom.
 
 ##
@@ -77,6 +90,7 @@ are three types of Options available to create:
  1. Boolean Option
  2. Text Option
  3. Dropdown Option
+ 4. Multiple Checkboxes Option
 
 ## 1. Boolean Option
 The simplest form of option...creates a true or false dropdown that can be used to turn features on or off.
@@ -91,49 +105,70 @@ The simplest form of option...creates a true or false dropdown that can be used
 ## 2. Text Option 
 A simple text field that can be used for configurable text, etc.
 
-   new TextOption(Name, Description, OptionID, Default, UseTextArea)
+   new TextOption(Name, Description, OptionID, Default, UseTextArea, ValidationCallback)
 
    Name = a human readable name for the option.
    Description = a human readable description for the option. 
    OptionID = a machine readable option identifier, cannot have spaces and must be unique
    Default = a string as the default value for the option; if not specified, the default is ""
    UseTextArea = a boolean describing if the text option should be written as a text area; if not specified, the 
                  default is false;
+   ValidationCallback = optional custom validation callback (see example)			 
 
 ## 3. Dropdown Option
 Allows you to create a dropdown with custom values by passing the constructor an array of options
 
-   new DropdownOption(Name, Description, OptionID, OptionsArray, DefaultIndex)
+   new DropdownOption(Name, Description, OptionID, OptionsArray, DefaultIndex, OptionsLabelsArray, ValidationCallback)
 
    Name = a human readable name for the option.
    Description = a human readable description for the option. 
    OptionID = a machine readable option identifier, cannot have spaces and must be unique
    OptionsArray = an array containing the values for the dropdown menu
    DefaultIndex = an integer identifying the item in the array that is the default value; if not specified,
                   the default is 0.
+   OptionsLabelsArray = if you want to seperate the labels from values, pass in an array with the labels matching indexes in the
+   						OptionsArray
+   ValidationCallback = optional custom validation callback (see example)					
+
+## 4. Multiple Checkboxes Option
+Allows you to create a multiple checkboxes option with custom values by passing the constructor an array of options
+   new MultipleCheezcapOption( Name, Description, OptionID, OptionsValues, OptionsLabels, OptionsChecked, ValidationCallback )
+
+   Name = a human readable name for the option.
+   Description = a human readable description for the option. 
+   OptionID = a machine readable option identifier, cannot have spaces and must be unique
+   OptionsValues = an array containing the values for the dropdown menu
+   OptionsLabels = an array of labels correponding to OptionValues
+   OptionsChecked = an array of keys in OptionsValues that should be checked (selected)
+   ValidationCallback = optional custom validation callback (see example)
 
 ##
 ## Usage
 ##
-CheezCap makes it easy to access the values that are set in your custom admin pages is easy.  A global 
-variable $cap exists to allow you to access any variable by OptionID.  (Hence, the need for OptionID 
-to be unique.)
 
-For example, if you have created a DropdownOption with the OptionID "my_first_dropdown" then you
-would access the value of that option like so:
+CheezCap makes it easy to access the values that are set in your custom admin pages is easy.
+You can use the built-in helper function:
+
+	cheezcap_get_option( $option, $echo = false, $sanitize_callback = '' )
+
+##
+## Actions
+##
 
-   $cap->my_first_dropdown
+Below are all of the actions you can hook in to:
 
-For example, you might want to write that value to the screen:
+* cheezcap_update
+* cheezcap_reset
+* cheezcap_export
+* cheezcap_import
 
-   echo($cap->my_first_dropdown);
+##
+## Methods
+##
 
-And, in many cases, you will be accessing $cap from inside a function, so you will need to call
-the global variable declaration in order to access $cap, like so:
+Calling the get_data method returns all of the input.
 
-   function some_function() {
-      global $cap;
-      echo($cap->my_first_dropdown);
-   }
+```
+	$data_arr = $cap->get_data();
+```
 
-*/