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, our web development services company 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: “taxonomy_term_add_form.inc".

Now you can start writing your own plugin. First 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:

For example, a standard context Node looks like this:

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!