4 - Developers: How to create a DraggableViews handler

This page will describe the DraggableViews Taxonomy handler that comes with the DraggableViews module. This page doesn't assume that the user knows how to build drupal modules.

First create a new folder for the new module:
yourdrupalsite/sites/all/modules/your-module-name
(The taxonomy handler is located in sites/all/modules/draggableviews/modules/draggableviews_taxonomy)

The files we need:

1. your-module-name.info
2. your-module-name.module
3. draggableviews_handler_your-module-name.inc

The content of your-module-name.info

; $Id: your-module-name.info,v 1.1 2009/08/19 14:17:58 YOUR_NAME Exp $
name = DraggableViews your-module-name handler
description = Provides Taxonomy support for both order fields and parent fields.
dependencies[] = draggableviews
dependencies[] = this-module-must-be-installed (you can add more lines starting with "dependencies[] = ")
package = Views
core = 6.x

The content of your-module-name.module

// $Id: your-module-name.module,v 1.1 2009/08/19 14:17:58 YOUR_NAME Exp $

/**
 * @file
 * DraggableViews your-module-name module provides taxonomy support for both order fields and parent fields.
 */

/**
 * Display help and module information
 * @param path which path of the site we're displaying help
 * @param arg array that holds the current path as would be returned from arg() function
 * @return help text for the path
 */
function your-module-name_help($path, $arg) {
  $output = '';
  switch ($path) {
    case "admin/help#draggableviews_your-module-name":
      $output  = '<p>'. t("Taxonomy support for both order fields and parent fields.") .'</p>';
      $output .= '<p>'. t("Hint: Use Views relations to turn the Taxonomy: Term ID field into a parent field.") .'</p>';
      break;
  }
  return $output;
}

/**
 * Implementing hook_draggableviews_handlers
 */
function your-module-name_draggableviews_handlers() {
  return array(
    'your-module-name' => array(
      'file' => 'draggableviews_handler_your-module-name.inc',
      'title' => t('Taxonomy 2'),
      'description' => 'Taxonomy handler.',
      'handler' => 'draggableviews_handler_your-module-name',
    ),
  );
}

The hook_draggableviews_handlers tells DraggableViews that this handler is available and where to find it. The file attribute can be omitted, it will default to "$handler.inc" ("draggableviews_handler_your-module-name.inc" in this case). The handler can be omitted too, it will default to "draggableviews_handler_your-module-name". The title is for the UI. The description will not be shown anywhere (..not yet).
You should omit the trailing ?> tag in this file.

The content of draggableviews_handler_your-module-name.inc

// $Id: draggableviews_handler_your-module-name.inc,v 1.1.2.1 2009/08/19 14:17:58 YOUR_NAME Exp $

/**
 * @file
 * The taxonomy handler.
 */

/*
 * Taxonomy handler.
 */
class draggableviews_handler_your-module-name extends draggableviews_handler {
  function init($field_name, &$view) {
    parent::init($field_name, $view);
  }

  function save($tid, $value) {
    switch ($this->type) {
      case 'order':
        db_query("UPDATE {term_data} SET weight=%d WHERE tid=%d", $value, $tid);
        break;
      case 'hierarchy':
        db_query("UPDATE {term_hierarchy} SET parent=%d WHERE tid=%d", $value, $tid);
        break;
    }
  }

  function get_form_element($value, $attributes = array()) {
    if (!isset($attributes['class'])) $attributes['class'] = $field['field_name'];

    switch ($this->type) {
      default:
        $options = array();
        for ($i = $this->range_start; $i <= $this->range_end; $i++) $options[$i] = $i;

        return array(
          '#type'  => 'select',
          '#name'  => $attributes['field_name'],
          '#value' => $value,
          '#options' => $options,
          '#attributes' => array('class' => $attributes['class']),
        );
        break;

      case 'hierarchy':
        return array(
          '#type' => 'hidden',
          '#name' => $attributes['field_name'],
          '#value' => $value,
          '#attributes' => array('class' => $attributes['class']),
        );
    }
  }
}

The $field_name and $view variables that will be passed to function init() contain all the information we might possibly need. Actually we would need two handlers: One for the order field and one for the parent field. This handler uses a switch where we distinguish between these two handlers.
In function get_form_element() you can return any custom input field as long as its containing value can be read from the tabledrag.js.

The method save($tid, $value) must be implemented.
The methods init() and get_form_element() can optionally be implemented. If you don't implement them the default implementation of the parent class will be used.
You should omit the trailing ?> tag in this file.