Yet another WordPress Settings API wrapper. Why?
This library provides a simplified way to interact with the overly verbose WordPress settings API via an array.
This will handle;
- Form submission.
- Admin notices.
- Display settings as a single page or tab interface.
- Sanitizing.
- Tabbed based settings, or single page based settings.
Quilt allows you to easily create the following WordPress admin settings field types.
- button
- canadaStateSelect
- checkbox
- checkboxes
- fancyText
- fancySelect
- fieldset
- hidden
- html
- license
- multiselect
- mexicoStateSelect
- number
- radio
- roleToPage
- section
- select
- text
- textDisabled
- textarea
- css
- emails
- ips
- thickbox
- touchtime
- url
- upload
- usStateSelect
Each field is sanitized accordingly using the WordPress settings API with custom sanitize callbacks.
Full working example
- Download the zip file from the Quilt Sample Plugin repository.
- Install the plugin.
- Under "Settings" see the sub-menu link named "Quilt Plugin", click that.
A single form field entry can consists of:
$field = array(
'id' => HTML ID
'title' => HTML Label
'type' => HTML field type
'value' => Value to set
'std' => The default value
'placeholder' => HTML Placeholder
'options' => An array of options
)
At minimum an entry only needs type, and title.
array(
'title' => HTML Label
'type' => HTML field type
)
- Require the two classes
- Call the class
- Assign your settings
This is a full working example.
- Create a folder in your
wp-content/plugins/directory - Create a PHP file.
- Copy/paste the below code into that file
- Verify that you have the correct path for the additional files
- Activate the plugin
- Under "Settings" see the sub-menu link named "Quilt Plugin", click that.
/**
* You can obtain the classes here:
* https://github.com/zanematthew/lumber
* https://github.com/zanematthew/quilt
*/
require plugin_dir_path( __FILE__ ) . 'lib/lumber/lumber.php';
require plugin_dir_path( __FILE__ ) . 'lib/quilt/quilt.php';
/**
* This is best set as a constant. We will use it later.
* Filters are derived from this.
*/
define( 'MY_SAMPLE_NAMESPACE', 'quilt_plugin' );
/**
* This function shows an example of settings as a single page (not tabbed).
* The settings are defined in the $settings array.
*/
function quilt_plugin_init(){
// You define settings here. Refer to above for each field "type".
$settings = array(
'default_field_types' => array(
'title' => 'Default Fields Types',
'fields' => array(
array(
'title' => 'Sample Text',
'type' => 'text'
),
array(
'title' => 'Sample FancyText',
'type' => 'fancyText',
'desc' => 'Any "fancy" field type has a description with it.'
),
array(
'title' => 'Sample Email',
'type' => 'email',
'desc' => 'Only allow a single email.',
'std' => get_option( 'admin_email' )
),
array(
'title' => 'Sample Number',
'type' => 'number',
'desc' => 'Only allow a single number, also shows usage of placeholder.',
'placeholder' => 'Enter a number'
),
array(
'title' => 'Sample Hidden',
'type' => 'hidden',
'desc' => 'Yes, its hidden, sometimes this is good for passing values between JS.'
),
array(
'title' => 'Sample URL',
'type' => 'url',
'desc' => 'Only a valid URL.'
),
array(
'title' => 'Sample Button',
'type' => 'button',
'desc' => 'A button.',
'std' => 'Button'
),
array(
'title' => 'Sample TextDisabled',
'type' => 'textDisabled',
'desc' => 'This text is disabled.',
'std' => 'You cannot edit this.'
),
array(
'title' => 'Sample Checkbox',
'type' => 'checkbox',
'desc' => ''
),
array(
'title' => 'Sample Group of Checkboxes',
'type' => 'checkboxes',
'desc' => 'Choose a transportation type.',
'options' => array(
'car' => 'Car',
'bike' => 'Bike'
)
),
array(
'title' => 'Sample Radio',
'type' => 'radio',
'desc' => 'Yes, or no.',
'options' => array(
'yes' => 'Yes',
'no' => 'No'
)
),
array(
'title' => 'Sample Select',
'type' => 'select',
'options' => array(
'maybe' => 'Maybe',
'yes' => 'Yes',
'no' => 'No'
)
),
array(
'title' => 'Sample FancySelect',
'type' => 'fancySelect',
'desc' => 'Which one?',
'options' => array(
'maybe' => 'Maybe',
'yes' => 'Yes',
'no' => 'No'
)
),
array(
'title' => 'Sample Multiselect',
'type' => 'multiselect',
'desc' => 'A multi-select',
'options' => array(
'maybe' => 'Maybe',
'yes' => 'Yes',
'no' => 'No'
)
),
array(
'title' => 'Sample UsStateSelect',
'type' => 'usStateSelect',
'desc' => 'No options are needed.'
),
array(
'title' => 'Sample MexicoStateSelect',
'type' => 'mexicoStateSelect',
'desc' => 'No options are needed.'
),
array(
'title' => 'Sample CanadaStateSelect',
'type' => 'canadaStateSelect',
'desc' => 'No options are needed.'
),
array(
'title' => 'Sample Textarea',
'type' => 'textarea'
),
array(
'title' => 'Sample CSS',
'type' => 'css',
'desc' => 'Allow for only CSS (sanitized with wp_kses).'
),
array(
'title' => 'Sample Emails',
'type' => 'emails',
'desc' => 'Allow for only emails. Enter each email on a new line.',
'placeholder' => 'Enter each email on a new line.'
),
array(
'title' => 'Sample Ips',
'type' => 'ips',
'desc' => 'Allow for only emails. Enter each email on a new line.',
'placeholder' => 'Enter each email on a new line.'
),
array(
'title' => 'Sample Upload',
'type' => 'upload',
'desc' => 'A WordPress upload field'
),
array(
'title' => 'Sample HTML',
'type' => 'html',
'desc' => 'Any HTML you want',
'std' => '<div>This is my <strong>custom</strong> HTML.</div>'
),
array(
'title' => 'Sample Thickbox',
'type' => 'thickbox',
'desc' => 'Yes, a thickbox. Via WordPress native Thickbox. Currently ONLY supports iFrame.',
'std' => 'http://zanematthew.com/',
'placeholder' => 'View Entries'
),
array(
'title' => 'Sample Touchtime',
'type' => 'touchtime',
'desc' => 'Another built in WordPress type.'
),
array(
'title' => 'Sample RoleToPage',
'type' => 'roleToPage',
'desc' => '',
'options' => array(
'administrator' => 'Administrator',
'editor' => 'Editor',
'author' => 'Author',
'contributor' => 'Contributor',
'subscriber' => 'Subscriber'
)
)
)
)
);
// Instantiate the class
$quilt_plugin = new Quilt(
MY_SAMPLE_NAMESPACE,
$settings,
'plugin'
);
// Set our global used to retrieve settings
global $quilt_plugin_settings;
// Assign the option. This allows us to use the standard option
// values WITHOUT having to set any options in the database.
$quilt_plugin_settings = $quilt_plugin->getSaneOptions();
}
add_action( 'init', 'quilt_plugin_init' );
You can retrieve your settings via the get_options() method, and assign this to a global variable.
$my_settigns_obj = Quilt();
global $my_settings;
echo $my_settings_obj->get_options( 'some_text_field' );
Do it the WordPress way.
All filters and actions are dynamically create via your namespace using the following format. Filters are listed below.
apply_filters( 'quilt_{$my_namespace}_settings' );
apply_filters( 'quilt_{$my_namespace}_admin_menu' );
apply_filters( 'quilt_{$my_namespace}_below_tabs' );
apply_filters( 'quilt_{$my_namespace}_below_title' );
apply_filters( 'quilt_{$my_namespace}_footer' );
apply_filters( 'quilt_{$my_namespace}_all_default_options' );
apply_filters( 'quilt_{$my_namespace}_get_option' );
apply_filters( 'quilt_{$my_namespace}_get_setting_{$key}' );
apply_filters( 'quilt_{$my_namespace}_sanitize_{$type}' );
apply_filters( 'quilt_{$my_namespace}_sanitize_{$key}' );
apply_filters( 'quilt_{$my_namespace}_sanitize_{$field_id}' );
apply_filters( 'quilt_{$my_namespace}_admin_styles' );
apply_filters( 'quilt_{$my_namespace}_admin_style' );
apply_filters( 'quilt_{$my_namespace}_admin_script' );
apply_filters( 'quilt_{$my_namespace}_default_tab' );
apply_filters( 'quilt_{$my_namespace}_page_title' );
apply_filters( 'quilt_{$my_namespace}_menu_title' );
do_action( 'quilt_{$my_namespace}_above_form' );
do_action( 'quilt_{$my_namespace}_after_left_buttons' );
Sample Filter usage
// Note 'my_plugin' matches the namespace passed into the Quilt class.
function my_plugin_change_footer( $text ){
return 'My custom footer';
}
add_filter( 'quilt_my_plugin_footer', 'my_plugin_change_footer' );
At its core Quilt handles interacting with the WordPress settings API; assigning the sections, registering settings, setting sane options, and sanitizing. It actually does not create form fields. Lumber does that.