Drupal activemenu.module README.txt
==============================================================================

Makes standard Drupal menus into AJAX-based tree menus. Can also be used for
custom AJAX menus.


Requirements
------------------------------------------------------------------------------
This module is written for Drupal 5.0+ and requires the jstools.module to be
enabled.


Installation
------------------------------------------------------------------------------
Create a directory modules/activemenu (or, for easy updating, 
modules/jstools/activemenu) and copy all the module's files into it. Enable the
module via the administer > modules page.


Developer Usage
-----------------------------------------------------------------------------
Activemenu.module by default handles the standard navigation menu and all
menus generated as blocks by the Menu module.

To create your own activemenus:

1. Write a handler function in a module to accept a path argument (passed as
   a POST variable, 'href') and return an array of sub-items. For an example,
   see activemenu_js(). The sub-items are in the format based on that returned
   by menu_get_item() and have three array keys: children (boolean), path
   (the url of the item), and title (this will be rendered as the text of the
   menu item link).

Example:

function examplemodule_js() {
  if (isset($_POST['href'])) {
    $items = array();
    $path = $_POST['href'];
    switch ($path) {
      case 'examplemodule/parent1':
        $items[] = array(
          'path' => 'examplemodule/parent1/child1',
          'title' => t('First child option'),
          'children' => TRUE
        );
        $items[] = array(
          'path' => 'examplemodule/parent1/child2',
          'title' => t('Second child option'),
          'children' => FALSE
        );
        break;
      case 'examplemodule/parent1/child1':
        $items[] = array(
          'path' => 'examplemodule/parent1/child1/grandchild1',
          'title' => t('First grandchild option'),
          'children' => FALSE
        );
        break;
    }
    print drupal_to_js($items);
  }
  exit();
}

2. Make your handler accessible to the menu system.

Example:

/**
 * Implementation of hook_menu().
 */
function examplemodule_menu($may_cache) {
  $items = array();
  if ($may_cache) {
    $items[] = array(
      'path' => 'examplemodule/js',
      'title' => t('examplemodule'),
      'access' => user_access('access content'),
      'type' => MENU_CALLBACK,
      'callback' => 'examplemodule_js'
     );
  }
  return $items;
}

3. Enclose the menu content in a div with class="activemenu". For the id of 
   the div, put the path to your handler function, with dashes in the place
   of forward slashes. Ensure that the menu includes list items (<li>) with
   class "collapsed" or "expanded" as appropriate--these are needed to
   trigger the activemenu behavior. NOte that you can create your links
   (the href value) with the standard l() or url() functions--the javascript
   will handle the fact that the rendered HTML includes the base path. In the
   following example, the link might have been generated by

   l(t('First parent'), 'examplemodule/parent1');

Example:

<div id="examplemodule-js" class="activemenu">
  <ul>
    <li class="collapsed"><a href="/basepath/examplemodule/parent1">First parent</a></li>
  </ul>
</div>