How to write a term display plugin

This example builds a mini-panels plugin for taxonomy term displays. Please note that this is a good fully functional example of how to build term display plugins, however there are some specific issues I'm working out with mini-panels so you should not rely upon using this specific example for your sites, I will add this plugin to the taxonomy display module once I resolve the issues.

Purpose

The module you will create will add mini panels support to taxonomy display's term displays to be select-able by taxonomy administrators in the vocabularies' display options.

Step 1 - Your module

Note for seasoned developers: If you are a seasoned developer and want to jump straight into developing the plugin functionality into your module skip to step 2. Just be sure to add a "files[] = YOUR_MODULE_NAME.module" definition to your .info file if you do not currently have one. You'll also have to alter the implementation hook names to match your module.

Create your module:

Navigate to your Drupal installation's sites/all/modules directory and create a new directory called mymodule.
Change directoriese into mymodule.
Make a file named mymodule.info

Edit and save the following code to mymodule.info

name = My Module
description = An example module for building a Taxonomy Display plugin.
core = 7.x
dependencies[] = panels_mini
dependencies[] = taxonomy_display
files[] = mymodule.module

Make a file named mymodule.module

Edit and save the following code to mymodule.module

<?php

/**
 * @file
 * An example .module file for building adding a Taxonomy Display term display plugin.
 */

Step 2 - Tell taxonomy display about your plugin

The next step in building your module is providing a list to taxonomy display of any plugins your module provides. This is done by implementing the hook_taxonomy_display_plugins() function.

Add the code below to your mymodule.module file to tell taxonomy display about your plugin.

/**
 * Implements hook_taxonomy_display_plugins().
 */
function mymodule_taxonomy_display_plugins() {
  return array(
    // As a note at this same level of the array we could also add breadcrumb or
    // associated content plugins.
    'term' => array(
      // Our key here is the name of the class we will use for providing the
      // plugin. Note that the file it resides in will be defined in our .info
      // so that it can be loaded by Drupal.
      'MymoduleTermDisplayMiniPanel' => t('Mini panel example'),
    ),
  );
}

Step 3 - Create your plugin's class

Next we need to add the basic skeleton for your plugin's class. We will do so in a separate file, create term_display_mini_panel.inc in the your mymodule directory and put the following code within it:

<?php

/**
 * @file
 * Taxonomy Display term display plugin class.
 */

/**
 * Add a taxonomy display plugin to use mini panels for displaying the term.
 */
class MymoduleTermDisplayMiniPanel extends TaxonomyDisplayTermDisplayHandler {
  /**
   * Prepare our output data in a build array for when a term is viewed.
   *
   * @see TaxonomyDisplayTermDisplayHandler::displayTerm()
   */
  public function displayTerm($term, $options = NULL) {
    $build = array();

    return $build;
  }

  /**
   * Provide a form for user configuration of our plugin for the vocabulary.
   *
   * @see TaxonomyDisplayHandlerForm::formFieldset()
   */
  public function formFieldset(&$form, &$values, $options = NULL) {}

  /**
   * Prepare the values to be stored by Taxonomy Display on our behalf.
   *
   * Anything returned in this method will be provided to our displayTerm()
   * method above when a taxonomy term is viewed using our plugin.
   *
   * @see TaxonomyDisplayHandlerForm::formSubmit()
   */
  public function formSubmit($form, &$values) {}
}

Step 4 - Make MymoduleTermDisplayMiniPanel loadable

For your class to autoload when needed we next need to edit the mymodule.info file to add files[] = term_display_mini_panel.inc. Your .info file should now look like this:

name = My Module
description = An example module for building a Taxonomy Display plugin.
core = 7.x
dependencies[] = panels_mini
dependencies[] = taxonomy_display
files[] = mymodule.module
files[] = term_display_mini_panel.inc

At this point you could install your module in your Drupal site. If you weren't following a how to, this would allow you to test your code as you develop the next three steps which are where your plugin actually does something.

Step 5 - Provide a configuration form

Next edit your term_display_mini_panel.inc file to make alterations to MymoduleTermDisplayMiniPanel::formFieldset() which adds configuration to your plugin.

  /**
   * Provide a form for user configuration of our plugin for the vocabulary.
   *
   * @see TaxonomyDisplayHandlerForm::formFieldset()
   */
  public function formFieldset(&$form, &$values, $options = NULL) {
    // Provide a description so that the administrator has some reference as to
    // what they just selected.
    $form['#description'] = t('Use a mini-panel to display the term.');

    // Get options for a mini-panels select field.
    $mini_panels = panels_mini_load_all();
    $select_options = array();
    foreach ($mini_panels as $mini_panel) {
      if (!isset($mini_panel->disabled)) {
        $select_options[$mini_panel->name] = $mini_panel->admin_title;
      }
    }
    // Provide the mini-panels select field.
    $form['mini_panel'] = array(
      '#default_value' => isset($options['mini_panel']) ? $options['mini_panel'] : FALSE,
      '#description' => t('Select which mini-panel you would like to display the term.'),
      '#options' => $select_options,
      '#title' => t('Mini-panel'),
      '#type' => 'select',
    );
  }

Step 6 - Save administratively configured data

Taxonomy Display does all of the heavy lifting for saving the configuration form you added in step 5. The only thing you have to do is return $values in MymoduleTermDisplayMiniPanel::formSubmit():

  /**
   * Prepare the values to be stored by Taxonomy Display on our behalf.
   *
   * Anything returned in this method will be provided to our displayTerm()
   * method above when a taxonomy term is viewed using our plugin.
   *
   * @see TaxonomyDisplayHandlerForm::formSubmit()
   */
  public function formSubmit($form, &$values) {
    // We are using the exact keys that our formFieldset() implementation
    // defines and we want all of the values stored, so we have no need to alter
    // them before returning.
    return $values;
  }

Step 7 - Display terms through your plugin

Lastly you'll need to populate your build array for MymoduleTermDisplayMiniPanel::displayTerm(), if you know of good documentation on build arrays please post a documentation issue for taxonomy display so that I can link to it here.

  /**
   * Prepare our output data in a build array for when a term is viewed.
   *
   * @see TaxonomyDisplayTermDisplayHandler::displayTerm()
   */
  public function displayTerm($term, $options = NULL) {
    $build = array();

    // Note that $options is populated from the data returned in
    // MymoduleTermDisplayMiniPanel::formSubmit().
    $mini_panel = panels_mini_load($options['mini_panel']);

    // If mini-panel wasn't found or isn't valid
    if (empty($mini_panel)) {
      watchdog('mymodule', 'The mini-panel %minipanel configured for displaying taxonomy terms in the %vocabulary vocabulary is missing or invalid.',
          array('%minipanel' => $options['mini_panel'], '%vocabulary' => $term->vocabulary_machine_name),
          WATCHDOG_WARNING);
      return $build;
    }
    elseif (isset($mini_panel->disabled)) {
      watchdog('mymodule', 'The mini-panel %minipanel configured for displaying taxonomy terms in the %vocabulary vocabulary is disabled.',
          array('%minipanel' => $mini_panel->admin_title, '%vocabulary' => $term->vocabulary_machine_name),
          WATCHDOG_WARNING);
      return $build;
    }

    ctools_include('context');

    $context = ctools_context_load_contexts($mini_panel);

    // This is the portion of mini-panels integration that I am currently
    // uncertain of and am awaiting clarification, this should have no
    // affect for learning how to build a taxonomy display plugin.
    if (isset($context['requiredcontext_entity:taxonomy_term_1'])) {
      $context['requiredcontext_entity:taxonomy_term_1']->data = $term;
    }

    $mini_panel->display->context = $context;
    $mini_panel->display->css_id = panels_mini_get_id($mini_panel->name);

    $render = panels_render_display($mini_panel->display);
    
    // We use #markup to output HTML and wrap it within a sub-array of term.
    $build['term'] = array(
      '#markup' => $render,
      '#weight' => 0,
    );

    return $build;
  }