Taxonomy Menu Version 3

Taxonomy Menu is in the middle of a complete rewrite. Speak now or forever hold your peace!

The new UI is complete. You can see a screencast here. Currently on the UI is complete. I wanted to get more opinions about how to proceed with the new API.

If there new features you would like to see in V3, add them to the issue queue now. I will go through all of the old postponed features and assign them to V3.

Rules of the Road

All changes will be done through patches. That includes all changes, no matter how small. Be sure to include what release the patch goes against. There will be periodic releases and only RTBC patches will be committed. This will include changes for myself.

Feel free to look at and log bugs based up the UI on the Issue Queue.

Release Status:

• unstable: This is used as the "UI" releases. This means that while the UI is functional, it does not create a menu.
• alpha: This will have the first version of the API. API is to be ironed out.
• beta: The API is frozen. New features and bug fixes will take place.
• rc: No new features, but fixes only. Documentation should be in high gear.
• stable: as bug free as possible. Documentation is at a very good place.

Current Issues

New Term Sets do not redirect correctly.

UI: To Do

Add Global level options.
Change hook_taxonomy_options API to include function names.
Term Set Sync Methods.
Replace Term Selection widget.
Advanced Help integration.
Option Alter code. Relates to the workflow below.

Definitions

Term Set

A Term Set is a list of terms for a particular vocabulary.

• Title: Title of Term Set.
• Vocabulary: Vocabulary to select the terms from.
• Terms: What terms are part of this Term Set
• Sync Method: This will be how the Term Set stays in sync with the vocabulary. Still in planning.
• Term Set Options: There are options available to the term set. The $form_state['values'] array will be sent to the function listed in hook_taxonomy_menu_options for this option.

Menu Group

A Menu Group is a list of term sets in a hierarchically format.

• Menu Group Name: The name of the menu group. This must be unique.
• Parent Menu Item: The Parent menu Item that the menu group is associated to.
• Path Type: How the path is created for the item.
• Path Options: Options that modify the path
• Term Sets: The list of Term Sets associated to the Menu Group.
• Group Options: Options that modify the $items array when the menu groups turns into menu items.

Options

Options modify a particular part of taxonomy menu. The options are contorted by hook_taxonomy_menu_options(). The return of the hook is the FromAPI with a few additional fields.

• default: optional. this is what will be used if the variable is not set. if empty then FALSE is used
• #title: required.
• option_type: GROUP/TERM_SET/PATH
• taxonomy_menu_path: if path is the option_type then this is callback function. If not filled in that 'all' is used.
• alter_function: This is the name of the function that will alter the item for path.
• any other form element

NOTE: The "alter_function" is not implemented yet.

• PATH: The Path options are modifiers to the path string. When the path is created, the string is sent through the function specified in hook_taxonomy_menu_options for the path.
• TERM: The Term options appear on the term set page. The are applied when the term set is created or saved. The $items array is sent by reference to the alter functions specified.
• GROUP: The Group options appear on the menu group page. They are applied when the menu is created. The $items array is sent through the alter functions. This is basically the last place to alter the $items before they are turned into menu links and saved. See the workflow below for more info.

Menu Creation Workflow

Current workflow:
An array of term objects is created from the vocab using taxonomy_get_tree
cycle through each term object:

1. Create $args array: array(term_object OR tid, menu_name, menu_link_id(if update) )
2. Create $item array from $args array
      array with the following key/value pairs:
    'tid' => the term id (if 0 then adding the vocab as an item)
    'name' => the term's name
    'description' => term description, used as to build the title attribute
    'weight' => item weight
    'vid' => the vocabulary's id
    'ptid' => the term's parent's term id
    'menu_name' => the menu that the link item will be inserted into
    'mlid' => if this is filled in then the mlid will be updated
    'remove' => if this is true then the menu link is hidden
3. Send $item array through an alter hook.
4. Create path for based up the function name path type.
5. Find the parent menu link id based upon the $item['ptid']
6. Create $link array from $item and path
7. Save Menu Link
8. Core menu_link_alter is run against the menu links

While this was worked is most situation, it's not flexible enough to bring taxonomy_menu to the next level. Here is the new workflow.

1. Term Set is created and Term Set Option Alter function are run This is not necessary since the items will pass through an alter statement when they are built.
2. List of active menu groups are pulled
3. The following is run per menu group.
1. Pull $items array for menu group. This is an array of term objects
   item_key: tsid:term_id => stdClass
stdClass
  ->name: term/vocab name.  This will be the menu link name
  ->attributes:  array of attributes for the menu link.
  ->weight: the order of the item within the depth
  ->depth: What level the item is.
  ->parent:  the parent item_key
  ->path_key:  the function that is called to create the path for this item
  ->path_args:  array of arguments that are sent to the path function.
2. $item array is sent through option alters. Option alters are pulled from hook_taxonomy_menu_options. The 'function' key to be specific. Here elements can be added/edited or removed.
3. Create path based upon $item->path_key and $item->path_args.
4. Send path to Path Option Alters. The path string is sent by reference to the function based up the selected path options.
5. Add path to $items
6. Order $items array passed upon the depth and weight
7. Cycle through the $items
8. Create $link based upon $item array. The array is copied and the following is changed:

• If there is a parent, it's menu link will have been arleady created so get it.
• Remove depth, parent, path_key and parent_args
• Create menu link and add to $item->mlid
• Save $items array to a back to the menu_group

The main change is sending the entire $items array through the alter function rather then just one at a time. While this will slow down the running of the hooks because each alter function will have to cycle through the list of $items each time, it will allow for more drastic changes to the $items array like the ability to add the node menu items.

One more major change I want to propose is a "Menu Type" The menu type's API will be the same as the path's API. It will allow for different methods of creating the menu. This is being done to allow other modules to integrate with Taxonomy Menu. Helping to consolidate other contributed modules. An example would be selecting "block" instead of "menu links" and the menu group would be in a new block instead of the menu link items. Taxonomy Blocks and Taxonomy Navigator will be merging with Taxonomy Menu. There will be one UI to create the menu items and multiple methods to create the output.