Building custom content panes (aka ctools content types) in panels 3, and Drupal 7

Custom panes > blocks

Posted by on

Often on Drupal sites you need the ability to create re-usable panel panes for use on the site. Each panel pane would need custom configuration, and could even be context aware (aware of were they are placed on the site).

This is where ctools content types comes in. Ctools content types are one type of plugin that the ctools module provides. Out of the box, the ctools module provides a few content types to support core modules. These can be found in the git repository.

Advantages of ctools content types versus blocks

  • You do not need administer blocks permission (which is very risky for content authors to have)
  • Tight integration with panels and other panelizer. Using panelizer affords you the option of not giving away the 'administer panels' permission
  • Custom configuration edit forms to allow the panes to be re-usable and to make sense for your content authors
  • Developers can abstract away any complexity in code, leaving the content authors with only the job of adding the pane and configuring it

Unfortunately there is not a lot of documentation around content types, so I will go through a simple example with you.

Example implementation of ctools content type plugin

In this example I will go through creating a custom twitter timeline widget that can be configured to pull through a selected user's tweets, and with an option for limiting the number displayed.

Step 1: Create a new custom module with this in the .module file:

 1 <?php
 2 /**
 3  * Implements hook_ctools_plugin_directory().
 4  */
 5 function examplemodule_ctools_plugin_directory($owner, $plugin_type) {
 6   if ($owner == 'ctools' && $plugin_type == 'content_types') {
 7     return 'plugins/' . $plugin_type;
 8   }
 9 }
10 ?>

Where the name of my custom module is 'examplemodule'.

This lets ctools know that any file in the folder 'plugins/content_types/' should be parsed for content type plugins. This also keeps your code really nice.

Step 2: Create the include file for the plugin

mkdir -p plugins/content_types
cd plugins/content_types
vim twitter_timeline.inc

Notice the directory structure matches what was declared in the .module file.

Step 3: Declare the plugin to ctools

 1 <?php
 2 $plugin = array(
 3   'single' => TRUE,
 4   'title' => t('Twitter timeline'),
 5   'description' => t('Shows a twitter timeline with basic configuration options.'),
 6   'category' => t('Social media'),
 7   'edit form' => 'examplemodule_twitter_timeline_edit_form',
 8   'render callback' => 'examplemodule_twitter_timeline_render',
 9   'admin info' => 'examplemodule_twitter_timeline_admin_info',
10   'defaults' => array(
11     'username' => 'wiifm',
12     'tweets_to_show' => 5,
13   )
14 );
15 ?>

This piece of code lets ctools know what functions to call, what argument defaults there are and so fourth. It should be largely self explanatory. It also means that your pane will show up in panels now, as we can see from this picture:

Step 4: Implementing admin_info

Admin information is an optional function to implement that helps describe the pane when it is included on a panel. I would recomment always implementing it so your content authors can always see at a glance what configuration a particular pane has.

 1 <?php
 2 /**
 3  * 'admin info' callback for panel pane.
 4  */
 5 function examplemodule_twitter_timeline_admin_info($subtype, $conf, $contexts) {
 6   if (!empty($conf)) {
 7     $block = new stdClass;
 8     $block->title = $conf['override_title'] ? $conf['override_title_text'] : '';
 9     $block->content = t('Showing @tweets_to_show tweets from <em>@@username</em>.', array(
10       '@tweets_to_show' => $conf['tweets_to_show'],
11       '@username' => $conf['username'],
12     ));
13     return $block;
14   }
15 }
16 ?>

This is what the pane will look like after being configured

Step 5: Implementing the edit form

The heart of ctools content types is the ability to create simple configuration forms for your content authors so they can easily create and edit panes. Edit forms use standard form API, so they are really easy to make

 1 <?php
 2 /**
 3  * 'Edit form' callback for the content type.
 4  */
 5 function examplemodule_twitter_timeline_edit_form($form, &$form_state) {
 6   $conf = $form_state['conf'];
 7 
 8   $form['username'] = array(
 9     '#title' => t('Twitter username'),
10     '#description' => t('The username of the twitter account in which to pull the tweets from.'),
11     '#type' => 'textfield',
12     '#default_value' => $conf['username'],
13     '#required' => TRUE,
14   );
15 
16   $form['tweets_to_show'] = array(
17     '#title' => t('Number of tweets to show'),
18     '#description' => t('Used to control the number of tweets shown on the page initially. Defaults to 5.'),
19     '#type' => 'select',
20     '#options' => drupal_map_assoc(range(3, 12)),
21     '#default_value' => $conf['tweets_to_show'],
22     '#required' => TRUE,
23   );
24 
25   return $form;
26 }
27 ?>

In order to save the configuration back to the $conf storage for the pane, you will also need a submit handler

 1 <?php
 2 /**
 3  * The submit form stores the data in $conf.
 4  */
 5 function examplemodule_twitter_timeline_edit_form_submit($form, &amp;$form_state) {
 6   foreach (array_keys($form_state['plugin']['defaults']) as $key) {
 7     if (isset($form_state['values'][$key])) {
 8       $form_state['conf'][$key] = $form_state['values'][$key];
 9     }
10   }
11 }
12 ?>

There you have it, now you can configure the pane username, and the amount of tweets to show, all of which have sane defaults and helpful descriptions for your content authors. This is what this step looks like:

Step 6: Implemeting the render callback

This is the guts of the pane, and is responsible for producing markup to be rendered on the page. I have taken a simplitest approach to this and have not used a theme function (and template), in reality I would encourage this as well.

 1 <?php
 2 /**
 3  * Run-time rendering of the body of the block (content type)
 4  * See ctools_plugin_examples for more advanced info
 5  */
 6 function examplemodule_twitter_timeline_render($subtype, $conf, $panel_args, $context = NULL) {
 7   $block = new stdClass();
 8 
 9   // initial content is blank
10   $block->title = '';
11   $block->content = '';
12 
13   // Include twitter javascript - by linking to the external file.
14   drupal_add_js('//widgets.twimg.com/j/2/widget.js', 'external');
15 
16   // Add in the content
17   $block->content .= '
18     <script type="text/javascript">
19       var t = new TWTR.Widget({
20         version: 2,
21         type: "profile",
22         rpp: ' . check_plain($conf['tweets_to_show']) . ',
23         interval: 30000,
24         width: "300",
25         height: "300",
26         theme: {
27           shell: {
28             background: "#ededed",
29             color: "#6a6a6a"
30           },
31           tweets: {
32             background: "#fafafa",
33             color: "#6a6a6a",
34             links: "#6a6a6a"
35           }
36         },
37         features: {
38           avatars: false,
39           hashtags: true,
40           scrollbar: false,
41           loop: true,
42           live: true,
43           behavior: "default"
44         }
45       });
46 
47       t.render().setUser("' . check_plain($conf['username']) . '").start();
48     </script>';
49 
50   return $block;
51 }
52 ?>

Here is a sample panel page, with the twitter timelien pane on the right hand side

And as you can imagine, it is relatively easy to add more panes onto the panel, here is another on the same page

Full module download

I thought this post might be a bit code heavy, so I decided to include the full source of the module in case you want to download and install it yourself. Feel free to rename it, extend it, do what you want with it.

Final thoughts

In this tutorial you have seen how easy it is to make a fully custom ctools content type plugin, from scratch. And hopefully begin to see how this is more powerful then traditional blocks.

What are your experiences with ctools content types, and helpful advice for others? Did this tutorial help you at all? Let me know in the comments.