README.txt

   1 TAXONOMY MENU
   2 =============
   3 (README.txt: 19th of October 2010, Version 6.x-2.9)
   4
   5 -------------- Content ------------------
   6 INTRO
   7 INSTALLATION
   8 - New
   9 - Upgrade
  10 CONFIGURATION
  11 - Where to find the configuration screen?
  12 - Adjustments and options
  13 PATH TYPES and INTEGRATION WITH VIEWS MODULE
  14 - Menu Path Type: Default
  15 - Menu Path Type: Hierarchy
  16 - Menu Path Type: Custom
  17 INTEGRATION WITH OTHER MODULES
  18 - TAXONOMY MANAGER
  19 - TAXONOMY REDIRECT
  20 - CONTENT TAXONOMY
  21 - TAXONOMY BREADCRUMBS
  22 - HIERARCHICAL SELECT
  23 - i18n
  24 - DOMAIN ACCESS
  25 - PATHAUTO
  26 ADDITIONAL NOTES
  27 PROSPECT TO PLANNED FUNCTIONS
  28 ------------- End Content -----------------
  29
  30 INTRO
  31 =====
  32 This module adds links (menu entries) to taxonomy terms to the global navigation menu.
  33 With the current version users can create one group of menu entries and add specific options
  34 for each vocabulary. More functionality is being planned with further versions.
  35
  36 INSTALLATION
  37 ============
  38
  39 NEW
  40
  41 1) Place this module directory in your "modules" folder (this will usually be
  42    "sites/all/modules/"). Don't install your module in Drupal core's "modules"
  43    folder, since that will cause problems and is bad practice in general. If
  44    "sites/all/modules" doesn't exist yet, just create it.
  45
  46 2) Enable the Taxonomy Menu module in Drupal at:
  47    administration -> site configuration -> modules (admin/build/modules)
  48    The Drupal core taxonomy module is required.
  49    The modules Taxonomy Menu Custom Path and Taxonomy Menu Hierarchy provide
  50    additional path configuration types (see the "INTEGRATION WITH VIEWS MODULE" section below).
  51
  52 3) Create a new vocabulary or edit an existing one.
  53
  54 4) Choose which vocabularies to appear in the menu at:
  55    administration -> content management -> taxonomy
  56    (admin/content/taxonomy)
  57
  58 UPGRADE
  59 Please read UPGRADE.txt
  60
  61 CONFIGURATION
  62 =============
  63
  64 LOCATION OF CONFIGURATION SCREEN
  65  All configuration options are on the vocabulary's edit screen:
  66   admin/content/taxonomy   (or)
  67   admin/content/taxonomy/edit/vocabulary/$vid
  68
  69 ADJUSTMENTS AND OPTIONS
  70  Menu: Select under which menu the vocabulary's terms should appear.
  71   With the current version users can create one group of menu entries for each vocabulary.
  72
  73  Menu Path Type: Select how the url for the term path should be created.
  74   Included are Default, Hierarchy and Custom Path.
  75   To use Hierarchy and/or Custom Path you need to enable the related modules first.
  76   Menu Path Type = Default: The path will be taxonomy/term/% while Term ID will be passed as argument.
  77   (multiple arguments possible). This path type uses standard taxonomy display - views is not needed.
  78
  79   For other path types and their options see: INTEGRATION WITH VIEWS MODULE
  80   For developers: This is extendable using hook_taxonomy_menu_path().
  81   See developers documentation for more information. (http://drupal.org/node/380652)
  82
  83  Synchronize changes to this vocabulary: If selected, the menu will auto update when you
  84   change a node or term. It is recommended to always have this selected.
  85   When you change the generated menu with the core menu function, i.e. move it or change the structure,
  86   these changes most probably get lost when adding a new taxonomy term because Taxonomy Menu rebuilds
  87   the menu without knowing about the changes made elsewhere.
  88
  89  Display Number of Nodes: Displays the number of nodes next to the term in the menu.
  90   If option "Display Descendants" is enabled also descendants will be counted.
  91
  92  Hide Empty Terms: Does not create menu links for terms with no nodes attached to them.
  93
  94  Item for Vocabulary: Create a menu link for the vocabulary.
  95   This will be the parent menu item.
  96
  97  Auto Expand Menu Item: Enables the 'Expand' option when creating the menu links.
  98   This is useful if using 'suckerfish' menus (pull down menus) in the primary links.
  99
 100  Display Descendants:  Alters the URL to display all of child terms.
 101  <base path>/$tid $tid $tid $tid
 102   When this is set, the Path Alias (module PATHAUTO) is not applied.
 103
 104  Select to rebuild the menu on submit: Deletes all of menu items and relationships between
 105   the menu and terms and recreates them from the vocabulary's terms.
 106   This will create new mlid's for each item, so be careful if using other modules to extend
 107   the menu functionality.
 108
 109 PATH TYPES and INTEGRATION WITH VIEWS MODULE
 110 ============================================
 111
 112 MENU PATH TYPE: DEFAULT
 113  The path will be taxonomy/term/% while Term ID will be passed as argument (multiple arguments possible).
 114  This path type can be used without having the VIEWS module installed.
 115  VIEWS provides a view named taxonomy_term (A view to emulate Drupal core's handling of taxonomy/term)
 116  The path of the view is 'taxonomy/term/%', the argument is 'Term ID (with depth)' and 'Depth Modifier' -
 117  but only TERM ID will be passed as an argument.
 118  One can adjust this view to ones needs - but it might be a problem, to have only one view for all all
 119  taxonomy menu links. So it is recommended to use the option MENU PATH TYPE: CUSTOM for individual
 120  views per vocabulary.
 121
 122 MENU PATH TYPE: CUSTOM
 123  With this path type, one can create individual views for each vocabulary.
 124  You need to have a view (page) with path 'custom path/%' and an argument 'Term ID' BEFORE you create
 125  the taxonomy menu. Enable the option "Allow multiple terms per argument" while adding the argument
 126  'Term ID' and choose a title like "Terms". Other options should be left by default unless really
 127  needs to change sth..
 128  Fields and filters can be added and options can be set according to ones needs.
 129  Back to Taxonomy Menu:
 130  Enter your 'custom path' in the field "Base Path for Custom Path:" - leave out '/%'.
 131  For example when your view path is 'interests/%' you enter only 'interests' here.
 132  To use the 'Display Depth in Custom Path:' option, you need to have 'Taxonomy: Term ID depth modifier'
 133  as second argument within your view.
 134
 135 MENU PATH TYPE: HIERARCHY
 136  This path type is mainly being created for developers use.
 137  This should only be applied if you have custom code or a block that relies on the category/vid/tid/tid/tid.
 138  If you would like the url to be this path, the recommendation is to use PathAuto with
 139  'category/[vocab-raw]/[copath-raw]'. Use the field "Base Path for Hierarchy Path" to see the base URL
 140  that will match the view or page callback. The view or page callback MUST be created before the taxonomy menu.
 141
 142  --- How to set up a view for MENU PATH TYPE: HIERARCHY (and only for this!)-----
 143
 144  The vocabulary might be like:
 145  Vocabulary
 146  Term-1
 147  -- Term-1.1
 148  -- --Term-1.1.1
 149  -- --Term-1.1.2
 150  -- Term-1.2
 151  Term-2
 152  -- Term-2.1
 153
 154  What is needed:
 155  Modules: TAXONOMY MENU with TAXONOMY MENU HIERARCHY and VIEWS
 156
 157  Steps:
 158  * Create a view with a path: category/% (where the term "category" can be chosen)
 159  * Add fields and filters according your needs
 160  * Add the following arguments:
 161    - Vocabulary ID (Title: %1)
 162    - Term ID (Title: %2)
 163    - Term ID (Title: %3)
 164    - Term ID (Title: %4)
 165    - More arguments of this types might be needed, if the vocabulary has a greater depth than 3.
 166
 167  * Go to admin/content/taxonomy
 168    - Select the vocabulary you want to have a menu for.
 169    - Select "Menu:" (where the menu should show up)
 170    - Select "Menu Path Type: Hierarchy"
 171    - Enter "Base Path for Hierarchy Path: category" (or what you have chosen as path for view)
 172    - Optional: Display Number of Nodes / Auto Expand Menu Item
 173    - Check "Item for vocabulary"
 174    - Do NOT check "display descendants"
 175
 176  After saving the menu should appear.
 177  Now comes the BUT: most probably you don�t see any nodes when klicking the menu items.
 178  For Term-1 the path is: ..category/vid/tid, for Term-1.1.1 it is category/vid/tid/tid/tid
 179  Everything behind "category" will be taken as arguments in views.
 180  So only those nodes will be shown that are linked to the taxonomy terms Term-1 AND Term-1.1
 181  AND Term1.1.1. within the vocabulary (it is a logical AND function, whereas multiple arguments
 182  TermID TermID TermID is a logical OR function).
 183  Once you have linked your nodes to the taxonomy terms in the described way, they will be shown
 184  when clicking on the menu items. It produces nice breadcrumbs and page titles (remember to set
 185  the titles for the arguments in views as described) - and it always displays descendants.
 186  The only module that supports the saving of a whole term lineage when selecting a deep level
 187  item seems to be HIERARCHICAL SELECT. See chapter INTEGRATION WITH OTHER MODULES
 188
 189 INTEGRATION WITH OTHER MODULES
 190 ==============================
 191
 192 TAXONOMY MANAGER
 193 Helpful to organize taxonomy terms - Taxonomy Menu module does not interfere with it functions.
 194 (http://drupal.org/project/taxonomy_manager)
 195
 196 TAXONOMY REDIRECT
 197 Changes the taxonomy default URL to match the custom Taxonomy Menu Path can be controlled
 198 by Taxonomy Redirect.
 199 (http://drupal.org/project/taxonomy_redirect)
 200
 201 CONTENT TAXONOMY
 202 It is a nice and very helpful module to link taxonomy terms to nodes.
 203 Taxonomy Menu does not interface with the content taxonomy tables, so be sure to enable the option
 204 "Save values additionally to the core taxonomy system (into the 'term_node' table)"
 205 otherwise the related taxonomy terms will not be accessible for Taxonomy Menu.
 206 (http://drupal.org/project/content_taxonomy)
 207
 208 HIERARCHICAL SELECT with submodule HS_TAXONOMY
 209 Supports the selection of terms in an hierarchical structured vocabulary.
 210 For using "MENU PATH TYPE: HIERARCHY" within Taxonomy Menu the HS options "Save term lineage"
 211 and "Force the user to choose a term from a deepest level" should be enabled.
 212 (http://drupal.org/project/hierarchical_select)
 213
 214 TAXONOMY BREADCRUMBS
 215 Advanced breadcrumbs can be controlled by this module.
 216 (http://drupal.org/project/taxonomy_breadcrumbs)
 217
 218 MENU BREADCRUMBS
 219 Helpful to create menu breadcrumbs outside the main navigation menu especially
 220 when using Custom or Hierarchical path.
 221 (http://drupal.org/project/menu_breadcrumbs)
 222
 223 i18n
 224 At the moment the multiple language support seems to work only when the Taxonomy Menu option
 225 "item for vocabulary" is disabled.
 226
 227 DOMAIN ACCESS
 228 ....
 229
 230 PATHAUTO
 231  Menu Items are Path Alias aware and compatible with PATHAUTO.
 232  Have a look at the various path types, which URL is passed to the code.
 233  Default is taxonomy/term/$tid.
 234  (http://drupal.org/project/pathauto)
 235
 236 ADDITIONAL NOTES
 237 ================
 238  * Taxonomy Menu does not handle the menu call backs. It only creates the links to the menus.
 239    This means that everything that is displayed on the page (including title, content, breadcrumbs, etc)
 240    are not controlled by Taxonony Menu.
 241  * The router item must be created before Taxonomy Menu creates the links.  Failure to so so
 242    will cause the menu items to not be created.
 243  * Router items can be created by either a view or another modules hook_menu.
 244
 245 PROSPECT TO PLANNED FUNCTIONS (6.x-3.0 version)
 246 ===============================================
 247 - concept of "Menu Groups"
 248 - any number of Menu Groups per vocabulary
 249 - more than one vocabulary within one Menu Group
 250 - more options to define the url path
 251 - other options