Blog

Adding New Fields to a Top Quark Object

Plugins built as packages on the Top Quark architecture can be customized by third-plugins in a variety of ways. Top Quark packages make use of ObjectContainers and Objects. ObjectContainers know how to talk to the MySQL database to add/delete/modify rows in your object table and Objects are simply instances of the objects stored in the containers. This post describes how to add a field to a particular Object and ObjectContainer, allowing you to store custom information without having to touch the source code of the original plugin.

This technique can be used, for example, to add a price field to the Self Hosted Plugins if you want to be able to charge for your plugins. That is the use case that I’ll walk through here. If that’s what you’re looking to do, you may be interested in ready the post about adding authentication to your Self Hosted Plugin.

5 Easy steps

Thanks to the hooks and filters within the Top Quark architecture, you can add fields to a Top Quark plugin in 5 steps. Add the following code snippets to a third-plugin (not the Top Quark Architecture plugin, and not the main plugin you’re trying to affect).

In this example, the “main” plugin is the Self Hosted Plugins. This plugin includes a class called `SelfHostedPluginContainer`, which is a Container class that knows how to retrieve/add/delete self-hosted-plugins from the MySQL database. The example adds a price field.

Step 1: Add the column to the MySQL table

If you’re adding a field, you need to add the field to the actual table. This can be done using the plugin activation hook and WordPress’ useful function `maybe_add_column`.

register_activation_hook(__FILE__,'topquark_mods_activate');
function topquark_mods_activate(){
    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
	$pathToContainer = ABSPATH . 'wp-content/plugins/self-hosted-plugins/SelfHostedPluginContainer.php';
	if(!class_exists('SelfHostedPluginContainer') and file_exists($pathToContainer)){
		require_once($pathToContainer);
	}
	if(!class_exists('SelfHostedPluginContainer')){
		return;
	}

	$Container = new SelfHostedPluginContainer();
	maybe_add_column($Container->getTableName(),'SelfHostedPluginPrice','alter table '.$Container->getTableName().' add SelfHostedPluginPrice char(5) default NULL');
}

Step 2: Add the column to the Container Class

After Step 1, the column is in the physical MySQL table, but you need to also add the column to the Container Class. This is achieved using the filter `set_{YourContainer}Container_columns`. Again, my example uses the SelfHostedPluginsContainer container class.

add_filter('set_SelfHostedPluginContainer_columns','topquark_mods_set_PluginContainer_columns');
function topquark_mods_set_PluginContainer_columns($colname){
	$colname['SelfHostedPluginPrice'] = 'SelfHostedPluginPrice';
	return $colname;
}

Step 3: Set the object parameter on update/add

Now that the object Container knows about the new field, we have to set the proper parameter for the object whenever the admin makes updates to an existing object, or adds a new one. This is achieved through the `update_{YourObject}_object` and `add_{YourObject}_object` filters.

add_filter('update_SelfHostedPlugin_object','topquark_mods_update_SelfHostedPlugin_object');
add_filter('add_SelfHostedPlugin_object','topquark_mods_update_SelfHostedPlugin_object');
function topquark_mods_update_SelfHostedPlugin_object($object){
	if (isset($_POST) and $_POST['form_submitted'] != ""){
		$object->setParameter('SelfHostedPluginPrice',$_POST['SelfHostedPluginPrice']);
	}
	return $object;
}

Step 4: Add the field to the Admin Update page

Okay, the field is in the MySQL table, the Object Container class knows about the field, and the update/add flow knows about the field. Let’s tell the admin page about the field! If you have an admin page called ‘edit’ within your Top Quark plugin, then you’ll hit the filter `{YourTopQuarkPackage}_edit_{YourObject}_items` (if your edit has a different id, then substitute that. Here’s what to do to add the Price field in this example:

add_filter('SelfHostedPlugins_edit_SelfHostedPlugin_items','topquark_mods_SelfHostedPlugin_items');
function topquark_mods_SelfHostedPlugin_items($items){
	$id = $_REQUEST['shpid']; // Make sure this is the ID used within the actual edit page
	$Container = new SelfHostedPluginContainer();
	if ($id == "" and $_POST['form_submitted'] == 'true'){
		global $topquark_last_id;  // This gets set in the function in step 5 below
		$id = $topquark_last_id;
	}
	if ($id != ""){
		// They've just added the row, let's get it.
		$Plugin = $Container->getSelfHostedPlugin($id);
	}
	else{
		$Plugin = new SelfHostedPlugin();
	}
	$items[] = HTML_Form::returnTextRow('SelfHostedPluginPrice','Plugin Price:',$Plugin->getParameter('SelfHostedPluginPrice'));
	return $items;
}

Step 5: Store the last ID Added

If we’re just adding an Object (as opposed to editing an existing one), then we need to save the object id so the function in step 4 above can use it. It access the filter `new_{YourObject}_object_id`.

/*******************************************************
* This function will store the last ID added.  Useful
* in the above functions when adding an object.
********************************************************/
add_action('new_SelfHostedPlugin_object_id','topquark_mods_new_object_id');
global $topquark_last_id;
function topquark_mods_new_object_id($id){
	global $topquark_last_id;
	$topquark_last_id = $id;
}

That’s It & Further Reading

Using the above code snippets in a newly plugin, I’ve been able to add a price field to the Self Hosted Plugins container without touching anything in the actual Self Hosted Plugins plugin. As an exercise, consider downloading the Self Hosted Plugins plugin from the WordPress repository and playing around with the example code.

0


About the Author

Top Quark is Trevor Mills is Top Quark. He is they as you are me and we are all together. He holds an Engineering degree, specializing in high energy physics, he plays bass in the Juno award winning band Digging Roots and he lovely loves his family. Top Quark’s suite of WordPress plugins are just what you’re looking for.

Add a Comment