How to create a panels style plugin

This article assumes you know about running panels, and more or less what the nomenclature is. You should know also that panels now uses ctools, which is is primarily a set of APIs and tools to improve the developer experience.

So, what we'll be doing here is actually creating a ctools plugin, to implement a new panels style. Sorry if I'm confusing you already, don't worry, it's actually quite straight forward, we want to be able to do this:

... and then this:

OK, now to the meat of it. We'll call our module ctoolsplugins.

1. Create a new module, and tell ctools about our plugins

What you need is very basic, an info file and a module file. So far, nothing new.

1.1 Declare our dependencies

So we obviously need ctools module on our site, and well, the plugin wouldn't make much sense without panels and page_manager, so:

; $Id:
name = Ctools Plugins
description = Our custom ctools plugins
core = 6.x
dependencies[] = ctools
dependencies[] = panels
dependencies[] = page_manager
package = Chaos tool suite

1.2 Implement hook_ctools_plugin_directory to tell ctools about our plugins

In our module file, of course, we'll implement this function, that will check if ctools if looking for style plugins, and lets if so, it will let it know where ours are:

<?php
/**
  * Implementation of hook_ctools_plugin_directory().
  */
function ctoolsplugins_ctools_plugin_directory($module, $plugin) {
  if ($module == 'panels' && $plugin == 'styles') {
    return 'plugins/' . $plugin;
  }
}
?>

2. Prepare our file structure for the plugins, and create our plugin file.

This image is pretty self explanatory:

We'll call our plugin 'collapsible', so we create inside ctoolsplugins/plugins/styles/ a file called collapsible.inc.

3. Implement our style plugin in collapsible.inc

3.1 Define your style goals and necessities.

OK, Here you should think about what you are going to do with the plugin.

• Is it just for markup?
• Will you be offering different options?
• Will you be implementing javascript on it?

In our case, we'll take the opportunity, to teach you another thing that ctools has, the collapsible div utility. So our style will basically convert any panels pane, into a collapsible panels pane:

And because we are friendly developers (or like not to be ever bothered after developing it), we'll give the user a chance to configure if they want the pane to start opened or closed. That means an extra settings form, so we can have this:

3.2 Imlement hook_panels_style_info

The naming is very important here, it should be modulename_stylename_panels_style. You basically return an array, defining your style:

'title' and 'description' are pretty self explanatory.
'render pane' specifies the theme function we'll be providing for rendering the pane. Watch the naming convention.
'pane settings form' specifies the callback function which provides the extra settings form, that we'll be using for our start up options. Watch the naming convention.

3.3 Define the settings form callback.

The name of the function will be what you specified in 'pane settings form' earlier. Just provide a new array inside $form, for each configuration you want the user to specify. See the FAPI documentation for reference.

This is pretty straight forward, in our case we provide two options, one to start opened and one to start collapsed. If collapsed is chosen, the value will be 1.

3.4 Define the render callback function.

The name of the function will be what you previously specified in 'render pane'. This is just a theme function, and where you have the chance of altering what will be shown to the user when viewing the page.

Important to note here, is that our user's specified settings are inside $pane->style['settings']. In this example we check if there's a title available, and if so we implement the ctools_collapsible theme function to get our collapsible panes. Other wise we don't have a handle, and we just return the content as normal.

And that is it. Hope you found the article useful, and if you'd like me to write up some more articles about writing plugins for panels/ctools, drop a comment with your question/suggestion!

UPDATE:You can also provide a style plugin in your theme, as shown in this fine tutorial.

Attachment	Size
ctoolsplugins.tar.gz	1.3 KB