Panels context

Writing a custom panel context

Jesper bisgaard

I recently had to create a list of items based on data entered in a field and since the list would live in a panel I decided to create a new context to deliver the id to my views contextual filter.

I was guided by Yuriy Gerasimov on how to write the context and I changed a few things in order to make my case work.

Writing the context i very easy and requires only a very small module, so here is how I went about it:

First we need to create a new module, we could call it custom_context_example. I presume you know how to create a custom module otherwise lookup how on

Well in the custom_context_example.module we need to tell ctools that we are providing a new context type. We do this by defining the hook_ctools_plugin_directory and specifying the local path to our context folder.

  * Implements hook_ctools_plugin_directory().
function custom_context_example_ctools_plugin_directory($module, $plugin) {
  if ($module == 'ctools' && $plugin == 'contexts') {
    return "plugins/contexts";

Next we create the plugins and contexts folder. In the contexts folder we can now create the context inc file. Lets call it

The first thing we need to do here is define the plugin for ctools:

 * Array to describe plugin.
$plugin = array(
  'title' => t('Custom context example'),
  'description' => t('Provide token for referenced item.'),
  'context' => 'ctools_plugin_create_custom_context_example',
  'context name' => 'custom_context_example',
  'keyword' => 'custom_context_example', // Provides a list of items which are exposed as keywords.
  'convert list' => 'custom_context_example_convert_list', // Convert keywords into data.
  'convert' => 'custom_context_example_convert',

Next we need to write the create context function as well as the convert list and the actual convertion.

The create context functiion ctools_plugin_create_context_example starts with defining the base context.

function ctools_plugin_create_custom_context_example($empty, $data = NULL, $conf = FALSE) {
  $context = new ctools_context('custom_context_example');
  $context->plugin = 'custom_context_example';
  $context->data = new stdClass();

next we need to get the object which contains the reference for this context, in this case I knew that the panel would be part of a term view but depending your case you would have to change the next part to match.

  $term = menu_get_object('taxonomy_term', 2)
  if(!empty($term) && !empty($term->field_custom_context_example_data)) {
    $field_lang = field_language('taxonomy_term', $term, 'field_custom_context_example_data');
    $data= $term->field_custom_context_example_data[$field_lang][0]['value'];
    $query = db_select('aggregator_category', 'a')
      ->condition('a.title', $category, '=')
      ->fields('a', array('cid', 'title', 'description'));
    $result = $query->execute();
    foreach ($result as $record) {
      $context->data->cid = $record->cid;
      $context->data->title = $record->title;
      $context->data->description = $record->description;
  }  else {
    $context->data->cid = null;
    $context->data->title = '';
    $context->data->description = '';
  return $context;

For this example I have allowed writers to enter the name of a aggregator category in a text field and now in the context creation function we can use the value in the field to query the aggregator_category table to get the record matching the entered value. On a side not in order for this to function a validation of the entered value should be added to the field, to ensure that the entered value exists as a category.

It this context is used where there is no term available e.g. the panel page admin UI we will set the default cid to null and the other values to empty strings, this enables us to envoke the

When the filter value is not available

options in view and it should be noted that the function must always be able to run or you will get an error in the admin UI, which is also a reason for the fallback to a null value.

Once we have the record we can create and fill the appropriate values in our context data object. This values will be used later in the token function. It is also important to note that the keys for the values should correspond to the columns in the table since this enables you to use them as contextual filter values in views.

Next we will add the two token functions:

function custom_context_example_convert_list() {
  return array(
    'cid' => t('Feed term id'),
    'title' => t('Feed term title'),
    'description' => t('Feed term description'),
function custom_context_example_convert($context, $type) {
  switch ($type) {
    case 'title':
      return $context->data->title;
    case 'description':
      return $context->data->description;
    case 'cid':
      return $context->data->cid;

and that is it. Now you can use the context as in your panel pages to provide context based on dynamic values. I hope this helps some of you out there.

Subscribe to Panels context