scbForms Reference

scbForms is a class that simplifies form generation.

input($args, $formdata = array())

This is the main method, with which you can generate one or more form elements of the same type, including <select>s and <textarea>s.

$args is an associative array of arguments that define what form element should be generated.

General args:

• type – string (mandatory)
• name – string | array (mandatory)
• value – string | array
• desc – string | array | bool
• desc_pos – ‘before’ | ‘after’ | ‘foo %input% bar’ (default: after)
• extra – string | array Extra HTML attributes like class, style etc.

‘checkbox’ and ‘radio’ specific arguments:

• checked => bool | string Force the radio button to be checked or not

‘select’ specific arguments:

• text – bool | string By default, an empty option is generated. This can be disabled by setting the text argument to false
• selected – string Force a certain option to be selected
• numeric – bool (default: false) If set to false, the method will attempt to convert a numeric array to an associative one

$formdata is also an associative array with the formdata with which to pre-fill the elements.

Examples

Simple text input:

scbForms::input(array(
	'type' => 'text',
	'name' => 'title',
	'value' => 'Insert title here',
));

The input will be prefilled with the text ‘Insert title here’.

Multiple radio buttons:

$data = array( 'size' => 'medium' );
 
scbForms::input(array(
	'type' => 'radio',
	'name' => 'size',
	'values' => array('small', 'medium', 'large')
), $data);

This will generate three radio buttons, with the middle one selected.

A dropdown element:

$data = array( 'language' => 'en' );
 
scbForms::input(array(
	'type' => 'select',
	'name' => 'language',
	'values' => array( 'en' => 'English', 'fr' => 'French', 'de' => 'German' )
), $data);

This will generate a <select> element with 3 options. The selected one will be ‘en’.

Version 1.6

If you want to develop a plugin using scbFramework, just download it, open plugin.php and start hacking. This is all it contains:

<?php
/*
Plugin Name: scbFramework
Version: 1.6
Description: Useful classes for plugin developers
Author: scribu
Author URI: http://scribu.net
Plugin URI: http://scribu.net/wordpress/scb-framework
*/
 
require dirname(__FILE__) . '/scb/load.php';
 
// The rest of your plugin code goes here

If you don’t want to bundle scbFramework with your plugin, you can use the updated scb-check.php file instead.

Debugging

I’ve moved the debug() function and related code to a separate file to avoid errors with the Magpie RSS library. If you release your plugin, you should leave out the scb/Debug.php file.

Version 1.5

I’ve recently learned that register_uninstall_hook() allows a single callback per plugin. This meant that if you were using both scbOptions and scbTable, for example, when a user uninstalled that plugin, either the option wasn’t deleted or the table wasn’t dropped.

This is now fixed by using a new method, scbUtil::add_uninstall_hook(). It also prevents multiple UPDATE queries to execute on each page load.

This also means that scbOptions, scbTable and scbBoxesPage now require scbUtil to work.

Other improvements:

• new methods for scbOptions: get_defaults(); cleanup(); __isset();
• new method for scbAdminPage: page_help();
• scbAdminPage::submit_button() accepts an array of arguments
• scbAdminPage can create top level menus
• scbBoxesPage can assign the same handler to multiple boxes, with different arguments
• debug() outputs at the end of the page, only for administrators

Here is the full changeset.

Version 1.4

The plugin toolkit has been getting a lot of useful classes recently, so I though a version bump was in order.

scbUtil

scbUtil is a collection of useful little functions that I was using in a lot of my plugins. My favourite is the debug() function. Then there’s html() and html_link() for HTML generation. There are several other useful bits in there, but you’ll have to discover them yourself.

scbRewrite

One of the areas I wasn’t comfortable working with was the Rewrite API. The scbRewrite class was distilled from a discussion on wp-hackers. It’s only job is to take the rewrite rules you specify and hook them in all the right places.

If you would like to “try before you buy”, you can browse the source here.

Version 1.3

Here are the changes from the earlier version:

Admin pages generated with AdminPage or BoxesPage will be slightly faster because data is sent through AJAX.

The scbCron class has two new methods:

• do_now() – executes the callback immediately
• do_once() – executes the callback once, using wp_cron (with optional delay)

The scbOptions class has a new method set() that replaces update_part(). It also has a new documentation page.

Finally, version 1.3 of scbFramework only works with WordPress 2.8 or older.

Here is the list of changes.

scbOptions Reference

Every plugin that’s more than 100 lines of code has at least one setting stored in the database. The functions that come with WordPress for managing options are ok, but they can be used better.

Here’s how the scbOptions class makes your life easier as a plugin developer:

Advantages

All in one place

scbOptions stores all fields in a single database row. Ask any WP plugin author worth his salt and he will agree that that’s the way to go.

Clean up on your way out

When the plugin is uninstalled, the options will also be deleted to keep the database clean.

Read on…

Version 1.2

When you need to create a new database table, all you should be thinking about are the table columns, right? Well, with the new scbTable class added in version 1.2, you can.

Creating a table is as easy as:

new scbTable('my_table', __FILE__, "
	id bigint(20) unsigned NOT NULL default 0,
	foobar varchar(100) NOT NULL,
	PRIMARY KEY  (id),
");

The class takes care of creating or updating the table structure, as necessary.

Also, you can access it with $wpdb->my_table, just like you would any other WordPress table.

Version 1.1

The first update for scbFramework has an important bugfix in the scbOptions class.

The scbBoxesPage now creates perfect WP 2.8 style dashboard-like admin pages.

Also, several methods have been added and revised in scbAdminPage. Because of this, version 1.1 is not fully backwards compatible.

You can see all the changes from version 1.0.1 here.

How to use scbFramework in your plugins

Before making this framework public, I used to include the files with each plugin. As the number of plugins increased, I had to update each one every time I modified the framework.

After a while, I found a way to make all plugins on an instalation use the most recent framework version installed. This didn’t help much.

Finally, I made it a standalone plugin which you only need to install once.

So, currently, there are two possibilities:

Standalone plugin

As long as the scbFramework plugin is activated, your plugin will work perfectly. If you want to spare users from ugly error messages, you can include a small file, called scb-check.php. It will check that scbFramework is installed and if not, it will deactivate your plugin and display a friendly notice with an install link.

Including class files

If you don’t want to require users to install the standalone plugin, you can include all the class files with your plugin. You will also want to include another file, called load.php that takes care of autoloading classes as needed. (It will have to be placed in the same directory as the class files)

You can see a usage example by looking at the Front-end Editor plugin.

Introducing scbFramework

While developing plugins for WordPress, I found that one of the most time-consuming and error prone tasks was creating user-friendly settings pages.

That is how this framework was born. It’s basically a set of extensible classes that make plugin development faster. I already use it in most of my plugins.

It requires PHP5 and WordPress 2.5 or newer.

scbForms

This by far the most useful class. With it, you can create any type of form element without writing a single line of HTML.

scbOptions

This is a class that handles storing and updating plugin settings in a single field in the wp_options table.

scbAdminPage

This class extends scbForms to provide an easy way to create custom admin pages.

scbBoxesPage

This is an extension to the scbOptionsPage class that lets you easily create dashboard-like pages with collapsible boxes.

scbCron

This is a class that lets you create wp-cron schedules easier.

scbWidget

This class makes scbForms work with the new WP_widget class in WP 2.8.