Ctools context plugin creation

Ctools context plugin creation

In one of our blogs we have already touched upon the theme of creation plugins for Panels module, which can be implemented using Ctools. This time we will focus on adding one’s own context - this is another functionality provided by Chaos tool suite.

In Panels the term “context’ refers to a kind of wrapper around any meaningful object. The following contexts are embedded in the Panel module by default:

  • Comment;
  • File;
  • Node;
  • Node add form;
  • Node edit form;
  • String;
  • Taxonomy term;
  • Taxonomy vocabulary;
  • Token, User;
  • User edit form.

The list itself is not short but sometimes this is not enough. So there is a mechanism helping a Drupal Developer to add the needed element to the panel. As you can see above there is a context called 'Node add form' but there is nothing like this for the terms of taxonomy. So in this case we’ll describe a plugin that will add a form which allows to create the terms for any panel.

Similarly to other ctools plugins we need to write the following function:hook_ctools_plugin_directory():

 * Implements hook_ctools_plugin_directory().
function context_example_ctools_plugin_directory($module, $plugin) {
  if ($module == 'ctools' && !empty($plugin)) {
    return "plugins/{$plugin}";

Then in the directory with our module we need to create a folder called “plugins” where the "contexts" folder will be located. The next step is the creation of a plugin file. In our case it will have the following name: “".

Now you can start writing your own plugin. First of all you need to call an array $plugin which will contain all the necessary information about our context.

 * Plugins are described by creating a $plugin array which will be used
 * by the system that includes this file.
$plugin = array(
  // Visible title.
  'title'             => t('Taxonomy term add form'),
  // Description of context.
  'description'       => t('A taxonomy term add form.'),
  // Function to create context.
  'context'           => 'context_example_create_taxonomy_term_add_form',
  // Plugin settings form.
  'edit form'         => 'context_example_taxonomy_term_add_form_settings_form',
  // Keyword to use for %substitution.
  'keyword'           => 'taxonomy_add',
  // The unique identifier for this context for use by required context checks.
  'context name'      => 'taxonomy_term_add_form',
  // Provides a list of items which are exposed as keywords.
  'convert list'      => array('vocabulary' => t('Taxonomy vocabulary')),
  // Convert keywords into data.
  'convert'           => 'context_example_taxonomy_term_add_form_convert',
  // Placeholder form is used in panels preview, for example.
  'placeholder form'  => array(
    '#type'         => 'textfield',
    '#description'  => t('Enter the taxonomy vocabulary.'),

Above, in the element of the array we have called the settings form where taxonomy vocabulary for terms storing can be selected:

 * Settings form for context plugin.
function context_example_taxonomy_term_add_form_settings_form($form, &$form_state) {
  $conf         = $form_state['conf'];
  $vocabularies = taxonomy_vocabulary_get_names();
  $options      = array();

  // Provide the settings, where you will be able to select which of vocabularies will be used for taxonomy_term_add form.
  if (!empty($vocabularies)) {
    foreach ($vocabularies as $machine_name => $vocabulary) {
      $options[$machine_name] = $vocabulary->name;

    $form['vocabulary'] = array(
      '#type'           => 'select',
      '#title'          => t('Taxonomy vocabulary'),
      '#description'    => t('Select the taxonomy vocabulary for this form.'),
      '#default_value'  => !empty($conf['vocabulary']) ? $conf['vocabulary'] : '',
      '#required'       => TRUE,
      '#options'        => $options,

  return $form;

The results of this form have to be saved:

 * Submit handler for plugin settings form.
function context_example_taxonomy_term_add_form_settings_form_submit($form, &$form_state) {
  $form_state['conf']['vocabulary'] = $form_state['values']['vocabulary'];

Now we will deal with the function that is responsible for context creation:

 * It's important to remember that $conf is optional here, because contexts
 * are not always created from the UI.
function context_example_create_taxonomy_term_add_form($empty, $data = NULL, $conf = FALSE) {
  // We want to create the taxonomy add form, so we need to add the form contexts too.
  $context = new ctools_context(array('form', 'taxonomy_term_add_form'));
  // This is the plugin file name.
  $context->plugin = 'taxonomy_term_add_form';

  // Checking data from settings form.
  if (!empty($data['vocabulary'])) {
    // Get the The vocabulary object.
    $vocabulary = taxonomy_vocabulary_machine_name_load($data['vocabulary']);

    // Validate the taxonomy vocabulary exists and user has administrator access.
    if (!empty($vocabulary) && user_access('administer taxonomy')) {
      $form_state = array('build_info' => array('args' => array(array(), $vocabulary)));
      $form_id    = 'taxonomy_form_term';
      form_load_include($form_state, 'inc', 'taxonomy', 'taxonomy.admin');
      // Build a taxonomy_form_term form.
      $form       = drupal_build_form($form_id, $form_state);

      // All forms should place the form here.
      $context->form       = $form;
      $context->form_id    = $form_id;
      $context->form_title = t('Create a @name term', array('@name' => $vocabulary->name));
      // It's will be used in convert function.
      $context->data       = $data;

      return $context;

When calling the plugin we have described such keys of the array as 'keyword', 'convert list' and 'convert'. As in our case only machine name of the taxonomy vocabulary is available among context (we add it to settings_form) then the array can be immediately passed to 'convert list'. But if there are more variables or their value is to be generated than you can use a separate function with the appropriate settings. Thus, the description of these options will give us the following arguments in context:

taxonomy term add form

For example, a standard context Node looks like this:

node being viewed

Parameter 'convert' is responsible for converting the keyword into the data:

 * Convert a context into a string.
function context_example_taxonomy_term_add_form_convert($context, $type) {
  switch ($type) {
    // Convert a vocabulary keyword into the data.
    case 'vocabulary':
      return $context->data['vocabulary'];

That's it, the plugin is ready for use. A vivid example of its work and attached archive with the module can be found below.

Thank you for attention!

5 votes, Rating: 5

Read also


Some time ago we've learned how to develop ctools...


Drupal has transaction support starting from its 7th version. We will help you to learn how to use this functionality properly to achieve the desired result and not to get stumped


Apps is a module that can be looked at as a subsequent step in the evolution of...


The look of the login/registration form can now be changed using administration tool. This is possible with our Customize login form module.


In this article we will speak about Drupal core installation as a submodule. We will not dwell upon the very concept of a submodule here for long, nor try to consider its dis/advantages. What we...

Need a quote? Let's discuss the project

Are you looking for someone to help you with your Drupal Web Development needs? Let’s get in touch and discuss the requirements of your project. We would love to hear from you.

Join the people who have already subscribed!

Want to be aware of important and interesting things happening? We will inform you about new blog posts on Drupal development, design, QA testing and more, as well news about Drupal events.

No charge. Unsubscribe anytime