Calling a system page handler from code (CTools / Panels 3)

This is a quick and dirty tutorial for calling a CTools/Panels 3 custom handler from code. It works for handlers for the system pages, such as the user page override. Calling custom/panels pages from code is different. Make sure you replace all instances of MODULE_NAME with your module's name.

Step 1: Create a file named MODULE_NAME.delegator_default.inc and put it somewhere in your module's directory.

Step 2: Paste in the following code.

/**
* Implementation of hook_default_delegator_handlers()
*/
function MODULE_NAME_default_delegator_handlers() {
// BEGIN HANDLER EXPORT ******************************************************/
// PASTE YOUR HANDLER EXPORT IN HERE
// END HANDLER EXPORT ******************************************************/

$handlers[$handler->name] = $handler;
return $handlers;
}
?>

If you have multiple handlers to export, make sure each one ends with $handlers[$handler->name] = $handler; to put it in the array, and return the full array at the end.

Step 3: On the task handler list page, click on "operation" and then choose "export" from the drop down. Copy the contents where it says // PASTE YOUR HANDLER EXPORT IN HERE in the code above.

Step 4: Add the following code to your .module.

function MODULE_NAME_ctools_plugin_api($module, $api) {
if ($module == 'delegator' && $api == 'delegator_default') {
$module_path = drupal_get_path('module', 'MODULE_NAME');
return array('version' => 1, 'path' => $module_path . '/path/to/include/file');
}
}
?>

Change "/path/to/include/file" to the actual path from your module root to MODULE_NAME.delegator_default.inc. You can leave out the 'path' if it's in the module's root.

Step 5: Clear your cache.

At this point, if everything worked, you should see the "Type" change from "Normal" to "Overridden" which means it sees the handler in code but is still using the one in the database.

Bonus step: If you don't like the name MODULE_NAME.delegator_default.inc, you can call it something else by adding 'file' => 'filename' to the array in MODULE_NAME_ctools_plugin_api.

Thanks again to merlinofchaos for patiently getting me through doing this for APK's user page and for adding a couple suggestions to this article. :)