Creating a content type with CTools for Panels 3

Update: Feb 17, 2010 This article was written nearly a year ago when CTools was still in alpha. I don't know how much of it applies anymore but I've been told there's an up to date plugin example that ships with CTools now so you'll want to look to that as an example.

Note: This article requires the current Panels 3 / CTools development snapshots (or the beta when it comes out) as the alphas do not contain the recent changes to content types.

When you open the dialog to add content to your panel, there are many items already in there which come from core and contributed modules you have installed. But what if you want to add something new? There are a couple of options.

The simple way is to do it right through the UI with the option to add "New custom content" but this is only recommended if you just need to add a few lines of text or want to test something out. For dynamic content, you'll want to make your own content type. A content type is one of several types of CTools plugins along with "relationships", "layouts", and more. It is a discrete bit of content, defined in code, that can be added as a pane to your panel. You define the content type in a module and then it is available to the Panels UI. This article will walk you through creating a content type using my Author Pane as an example. You can also look at ctools/plugins/content_types for examples that come with CTools.

Note that you need to create content types inside of a module. If you have a site module for customizations you can use that or you can create a module just for this.

Step 1: Name your content type

Each content type needs a distinct name that will not conflict with any other content type name, including those coming from other contributed modules. Because of this, it's best to include your module's name in the content type name. If your module is only providing one content type, you can simply use your module name for the content type name. In Author Pane, I only create one content type so I named it simply "author_pane".

Step 2: Create the file and tell CTools where to find it

Your content type needs to live in an include file of the same name. In my case, author_pane.inc. You should put this in a directory that only contains content types. The recommended directory structure is: moduledir/plugins/content_types. For Author Pane, the complete path with file is author_pane/plugins/content_types/author_pane.inc

Once you have the file and directories set up, you need to tell CTools where your plugins are. If you followed the recommended directory structure, you can simply drop this code into your module (be sure to change MODULE_NAME to your module's name.):

/**
* Implementation of hook_ctools_plugin_directory().
*/
function MODULE_NAME_ctools_plugin_directory($module, $plugin) {
if ($module == 'ctools') {
return 'plugins/' . $plugin;
}
}
?>

This code will look for content types in plugins/content_types, relationships in plugins/relationships, and so on for all the various plugins. Don't worry about creating the other directories if your module doesn't make any other plugin types.

Step 3: Create the content type

The rest of this will walk you through the Author Pane content type, explaining what each bit does, and how you should change it for your own content type. All of these functions go in the ct_name.inc file you created in the last step.

Tell CTools about your content type:

/**
* Callback function to supply a list of content types.
*/
function author_pane_author_pane_ctools_content_types() {
return array(
'single' => TRUE,
'title' => t('Author Pane'),
'icon' => 'icon_user.png',
'description' => t('Author related variables gathered from helper modules.'),
'required context' => new ctools_context_required(t('User'), 'user'),
'category' => t('Advanced Profile Kit'),
'defaults' => array('image_path' => '', 'template_file' => 'author-pane'),
);
}
?>

Here's what each bit in that code means:

• The function name is MODULE_NAME_CT_NAME_ctools_content_types. Because our module name and content type name are the same, we have "author_pane" twice. This looks a little funny but doesn't hurt anything.
• We are only creating one content type so we set 'single' to true.
• The title is the name that shows up in the add content dialog.
• The icon is the icon that shows next to the name that shows up in the add content dialog. Since this is user related, we are using the user icon. This icon is in CTools and you will either need to copy it to your plugin directory or put the full path to it (or make your own icon). If you don't provide an icon, CTools will provide a default.
• The description shows up when you hover over the item in the add content dialog.
• Required context is what context this content type needs to work. In this case, we need the user object so we make use of the user context. If the Panel does not have a user context on it, our content type will not show up as an option to add.
• The category defines where our content type shows up in the add content dialog. For a user related item, you could use simply "User". In this case, I wanted it to be grouped with other items provided by Advanced Profile Kit as that is where it will most commonly be used. If you are creating this content type for your own site, you can use whatever category you like. If you are creating it for others to use, be careful what you choose here to avoid cluttering the add content dialog.
• Defaults is an array that contains the default values, if any, for the items on your add/edit form.

Tell CTools how to display your content type:

/**
* Output function for the 'author pane' content type.
*/
// The function name is MODULE_NAME_CT_NAME_content_type_render
function author_pane_author_pane_content_type_render($subtype, $conf, $panel_args, $context) {
// $context in this case is a user context, so we can get the user object
// from it and put it into $account.
$account = isset($context->data) ? drupal_clone($context->data) : NULL;

// Make a new empty "block" which will be a Pane you can add to your Panel.
$block = new stdClass();

if ($account) {
// Set the title of the block to the name of the user. It can be overridden
// through the UI as well.
$block->title = check_plain($account->name);

// Call the function that makes the author pane and use that for the block
// content. In our case, this is just one line but you can have whatever
// code you need to assemble the content and then assign it to the
// $block->content variable.
$block->content = theme('author_pane', $account, $conf['image_path'], $conf['template_file']);
}
else {
// If somehow the user context is empty, this is a fallback message but
// that should never happen.
$block->content = "User information not available";
}

return $block;
}
?>

Define the settings form for the pane:

/**
* Returns an edit form for the custom type.
*/
// The function name is MODULE_NAME_CT_NAME_content_type_edit_form
function author_pane_author_pane_content_type_edit_form(&$form, &$form_state) {
// The current configuration
$conf = $form_state['conf'];

// This and the next one are normal FAPI form making.
$form['image_path'] = array(
'#type' => 'textfield',
'#title' => t('Image directory'),
'#size' => 50,
'#description' => t('Full path to image directory, not including leading or trailing slashes. Use [theme_path] to substitute the active theme\'s path. If left blank the images in the module directory will be used.'),
'#default_value' => $conf['image_path'],
'#prefix' => '

',
);

$form['template_file'] = array(
'#type' => 'textfield',
'#title' => t('Template file'),
'#size' => 50,
'#description' => t('Template file to use for the author pane.'),
'#default_value' => $conf['template_file'],
'#prefix' => '

',
);
}
?>

Prepare the settings form for submission.

function author_pane_author_pane_content_type_edit_form_submit(&$form, &$form_state) {
// For each part of the form defined in the 'defaults' array set when you
// defined the content type, copy the value from the form into the array
// of items to be saved. We don't ever want to use
// $form_state['conf'] = $form_state['values'] because values contains
// buttons, form id and other items we don't want stored. CTools will handle
// the actual form submission.
foreach (array_keys($form_state['plugin']['defaults']) as $key) {
$form_state['conf'][$key] = $form_state['values'][$key];
}
}
?>

Define the title displayed on the layout page of the panel:

This is the title you see when you are editing the Panel. It is not the same as the title
of the pane when you are viewing the panel, which is defined in the render function.
function author_pane_author_pane_content_type_admin_title($subtype, $conf, $context) {
return t('"@s" author pane', array('@s' => $context->identifier));
}
?>

Explore the possibilities

This example has shown the most common bits you will need to create a content type. With it, you can make use of the panel's context as well as settings on the pane and your own code to come up with your own dynamic, custom content. This lives in a file that can be checked into version control rather than just being set in the database. You can also include it with a module for distribution to share with others. From here, there are more complicated things you can do such as multi-page settings and more.

If you maintain a contributed module, consider what parts of it could be encapsulated into content types to make it easier for your users to add them to their own panels. While Panels will make use of blocks you provide, that is only part of the story. Making it a true content type gives you more options for integration such as showing content for a particular user based on the user context or a node based on the node context.

The possibilities are endless.

Much credit goes to merlinofchaos who helped me quite a bit in writing this as well as converting my content types from Panels 2