Taxonomy Menu: Developer Documentation

Starting on version 6.x-2 of Taxonomy Menu, an API was introduced. Four new hooks were introduced.

hook_taxonomy_menu_path
hook_taxonomy_menu_options
hook_taxonomy_menu_insert
hook_taxonomy_menu_update
hook_taxonomy_menu_delete

hook_taxonomy_menu_path:

Parameter:

None

Return

Returns an array of the functions and titles that are displayed in the path drop down. The function is then called when a taxonomy menu item is added or updated. It is passed $tid, $vid and then return a string.

Example

In this example, in the drop down selection on the vocabulary edit page, 'Default' will listed.
If 'Default' is selected as the path type then the function 'taxonomy_menu_path_default' is run. This function is passed the TermID and VocabID that is being added. The function then returns the path.

/**
 * Implementation of hook_taxonomy_menu_path. 
 *
 * @return array
 *  function name => Display Title
 *  a list of the path options.
 */
function taxonomy_menu_taxonomy_menu_path() {
  $output = array('taxonomy_menu_path_default' => t('Default'));

  return $output;
}

/**
 * Callback for hook_taxonomy_menu_path
 */
function taxonomy_menu_path_default($vid, $tid) {
  //if tid = 0 then we are creating the vocab menu item format will be taxonomy/term/$tid+$tid+$tid....
  if ($tid == 0) {
    //get all of the terms for the vocab
    $vtids = _taxonomy_menu_get_terms($vid);
    $end = implode(' ', $vtids);
    $path = "taxonomy/term/$end";
  }
  else {
    $path = taxonomy_term_path(taxonomy_get_term($tid));
  }

  return $path;
}

hook_taxonomy_menu_options

Parameters

Hook is invoked when the vocabulary edit screen is opened. It adds the options to the taxonomy menu/options area and handles the display saving of the data. The name of the variable is pulled from the key of the options array. The resulting variable name is 'taxonomy_menu_''_'.

Return

Array compatible with the FormAPI with a few exceptions. The '#type' is optional and will default to '#checkbox.' A 'default' key is introduced. This is an optional key that is used as the default value if the variable is not set.

Example

This example creates a variable called 'taxonomy_menu_hierarchy_base_$vid'

/**
 * Implements hook_taxonomy_menu_options()
 * 
 * @return array
 *   Uses the value to set the variable taxonomy_menu_<value>_$vid
 *   $options[value] = array(
 *     default
 *       Optional. This is what will be used if the variable is not set. if left
 *       empty then FALSE is used.
 *     #title
 *       Required.
 *     [any other form element]
 */
function taxonomy_menu_hierarchy_taxonomy_menu_options() {
  $options['hierarchy_base'] = array(
    '#title' => t('Base Path for Hierarchy Path'),
    '#description' => t('Only used when the Hierarchy path type is selected'),
    'default' => 'category',
    '#type' => 'textfield',
    '#weight' => -5,
  );
  
  return $options;
}

hook_taxonomy_menu_insert and hook_taxonomy_menu_update

Hook is invoked each time a menu item is created/updated.

Parameters

$item array with the following key/value pairs:
'tid' => the term id (if 0 then updating the vocab as an item)
'name' => new menu name
'description' => new menu description, used as to build the title attribute
'weight' => new menu weight
'vid' => the new vocabulary's id
'ptid' => the new parent tid
'mlid' => mlid that needs to be edited (hook_taxonomy_menu_update only)
'menu_name' => the menu that the link item will be inserted into
'options' => array of menu options that will be sent to menu_link_save

Return

Nothing is technically returned since the $item array is passed by reference. Just make changes to the $item array. Similar to hook_form_alter.

$item array with any changes. The 'remove' key is set to TRUE if the item should not be added to the menu.
$item array with the following key/value pairs:
'tid' => the term id (if 0 then updating the vocab as an item)
'name' => new menu name
'description' => new menu description, used as to build the title attribute
'weight' => new menu weight
'vid' => the new vocabulary's id
'ptid' => the new parent tid
'mlid' => mlid that needs to be edited (hook_taxonomy_menu_update only)
'menu_name' => the menu that the link item will be inserted into
'options' => array of menu options that will be sent to menu_link_save
'remove' => if this is set to TRUE then the $item is not added as a menu

Example

In this example implements 2 features:

1. The term is not added to the menu if the hide empty option is true and there are no nodes attached to the term.
2. The count of nodes is appended to the name of the node.

function taxonomy_menu_taxonomy_menu_insert(&$item) {
  //if tid is 0 then do not change any settings
  if ($item['tid'] > 0) {
    //get the number of node attached to this term
    $num = _taxonomy_menu_term_count($item['tid']);

    //if hide menu is selected and the term count is 0 and the term has no children then do not create the menu item
    if ($num == 0 &&
        variable_get('taxonomy_menu_hide_empty_terms_'. $item['vid'], FALSE) &&
        _taxonomy_menu_children_has_nodes($item['tid'], $item['vid'])) {

        $item['remove'] = TRUE;
        return $item;
    }

    //if display number is selected and $num > 0 then change the title
    if (variable_get('taxonomy_menu_display_num_'. $item['vid'], FALSE)) {
      //if number > 0 and display descendants, then count all of the children
      if (variable_get('taxonomy_menu_display_descendants_'. $item['vid'], FALSE)) {
        $num = taxonomy_term_count_nodes($item['tid']);
      }
      $item['name'] .= " ($num)";
    }
  }
}

hook_taxonomy_menu_delete

This hook is called when the menu item is being deleted.

Parameters:

$args array with the following key/value pairing.
'vid' => Vocab ID
'tid' => TermID
'mlid' => Menu ID

Returns:

Nothing.

Example:

This deletes the item from the taxonomy_menu table.

/**
 * hook_taxonomy_menu_delete
 *
 * @param $args
 *  array(
 *   'vid' => Vocab ID
 *   'tid' => TermID
 *   'mlid' => Menu ID
 *  )
 *
 */
function taxonomy_menu_taxonomy_menu_delete($args = array()) {
  menu_link_delete($args['mlid']);
  _taxonomy_menu_delete_item($args['vid'], $args['tid']);
}

/**
  * Delete all rows from {taxomony_menu} associated with this tid
  *
  * @param $vid
  * @param $tid
  */
function _taxonomy_menu_delete_item($vid, $tid) {
  db_query('DELETE FROM {taxonomy_menu} WHERE vid = %d AND tid = %d', $vid, $tid);
}

Recommendations/Notes

• The Rebuild option has a weight of 20. Keep your form elements weight above this
• Use hook_menu to create the page call back for the path used in hook_taxonomy_menu_path.
• Use hook_term_path to define a custom taxonomy path. Taxonomy Menu and Path Auto will honor the paths.