$Id$ Description ----------- The Taxonomy Filter module is designed to present an easy-to-use interface for narrowing down taxonomy listings to find topics that are tagged by multiple terms. This is helpful for sites that use multiple vocabularies to create a multi-faceted information architecture. The standard Drupal taxonomy module has the ability to do this with the following URL format: /taxonomy/term/x,y which will display a listing of all nodes tagged with terms x and y. However, not many visitors to your site will be aware of this functionality. The Taxonomy Filter module allows your users to enjoy this functionality without needing to know the URL syntax described above. It does this by displaying a block of links that reference multiple terms from one or more vocabularies. The vocabulary filters are defined in the module's configuration settings. There the site administrator can specify that a vocabulary be 'filtered' by one or more vocabularies. The arrangement of the links in the block can also be specified by selecting one of the four menu templates -- default, cloud, context and dynamic. For example, if vocabulary A is set to be 'filtered' by vocabulary B (which may be vocabulary A), then whenever someone views the taxonomy listing of a term in vocabulary A they will see a 'filter' menu of terms from vocabularies A and B. This allows the visitor to narrow down the listing by choosing another term - effectively showing them the intersection set of nodes from the two terms. Changes for Drupal 6.x ---------------------- * A complete redesign and rewrite. Taxonomy Filter is now a pluggable framework with an API for other modules to extend. See API.txt for coding details. * Advanced features are now implemented by separate submodules that can be enabled individually. * A new submodule (Multi Term) is provided that allows Taxonomy Filter to filter by more than two terms at once. * The configuration settings are now consolidated in their own section of the administration menu rather than being part of the vocabulary edit forms. Submodules ---------- There are two kinds of submodules shipped with Taxonomy Filter: * Template modules - modules that display the menu links in different ways. Currently, these are: cloud, context and dynamic. * Enhancement modules - modules that alter the functionality of each menu. They can add extra information or features to the menu items, the menus them- selves or the whole block. The two enhancement modules are: tf_count that adds result counts to the output and tf_multi that allows for filtering by more than two terms. Configuration ------------- Menu templates define the basic layout and functionality of a type of menu and provided by Taxonomy Filter core or a submodule. Menus are created from menu templates. A single template can be used to create multiple menus with different settings. On /admin/settings/taxonomy_filter page there are listings of all the template types available, and all the menus that have been created from those templates. Once you have created one or more menus, you can map them to vocabulary listings on the /admin/settings/taxonomy_filter/mappings page. For each vocabulary you can specify which menu it will use for display and which listings it will appear on. Optional Advanced Configuration ------------------------------- On the /admin/settings/taxonomy_filter/advanced page you can configure how the module handles URLs. There are options for specifying which URL patterns to enable the taxonomy_filter menu for, and how to format the URLs produced by the menu. NOTE: you don't need to change these settings if you only use the standard core taxonomy module to produce your taxonomy listings. URLs to listen on: This setting allows you to enable the block on listings produced by code other than the core taxonomy module - eg custom views, or the taxonomy_menu module. Each line is a URL pattern and the first one that matches will be used. Each pattern can contain the following tokens: %tids : for matching the term id(s) parameter used for creating the menu. %depth : for matching the depth parameter in the URL. %op : for matching the op parameter - eg 'page' or 'feed'. Usually not needed. * : matches anything at that parameter position. The %tids token is the only one that is required for generating the menu. Example: taxonomy/term/%tids/%depth matches the standard taxonomy module listings, and won't waste resources on generating the menu for feed URLs where it isn't needed. This is the default. taxonomy_menu/*/%tids will match listing urls generated by the taxonomy_menu module. URL format for menu links: This setting is similar to the above but is a template for how the URLs created by the menu are formatted. The available tokens are %tids and %depth. Only %tids is required. Example: taxonomy/term/%tids/%depth will create links for the standard taxonomy module. This is the default. Known Issues ------------ * This code has not been fully refined and automated tests have not been written. * The taxonomy depth handling might not be implemented to the same level as the Drupal 5.x version.