modules/taxonomy_filter/README.txt

$Id: README.txt,v 1.7 2008/07/14 01:36:53 styro Exp $

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.
1	$Id: README.txt,v 1.7 2008/07/14 01:36:53 styro Exp $
2
3	Description
4	-----------
5
6	The Taxonomy Filter module is designed to present an easy-to-use interface for
7	narrowing down taxonomy listings to find topics that are tagged by multiple terms.
8	This is helpful for sites that use multiple vocabularies to create a multi-faceted
9	information architecture.
10
11	The standard Drupal taxonomy module has the ability to do this with the following
12	URL format:
13
14	/taxonomy/term/x,y
15
16	which will display a listing of all nodes tagged with terms x and y. However, not many
17	visitors to your site will be aware of this functionality.
18
19	The Taxonomy Filter module allows your users to enjoy this functionality without
20	needing to know the URL syntax described above. It does this by displaying a block
21	of links that reference multiple terms from one or more vocabularies. The
22	vocabulary filters are defined in the module's configuration settings. There the site
23	administrator can specify that a vocabulary be 'filtered' by one or more vocabularies.
24	The arrangement of the links in the block can also be specified by selecting one of
25	the four menu templates -- default, cloud, context and dynamic.
26
27	For example, if vocabulary A is set to be 'filtered' by vocabulary B (which may be
28	vocabulary A), then whenever someone views the taxonomy listing of a term in
29	vocabulary A they will see a 'filter' menu of terms from vocabularies A and B. This
30	allows the visitor to narrow down the listing by choosing another term - effectively
31	showing them the intersection set of nodes from the two terms.
32
33
34	Changes for Drupal 6.x
35	----------------------
36
37	* A complete redesign and rewrite. Taxonomy Filter is now a pluggable framework
38	with an API for other modules to extend. See API.txt for coding details.
39	* Advanced features are now implemented by separate submodules that can be
40	enabled individually.
41	* A new submodule (Multi Term) is provided that allows Taxonomy Filter to filter
42	by more than two terms at once.
43	* The configuration settings are now consolidated in their own section of the
44	administration menu rather than being part of the vocabulary edit forms.
45
46
47	Submodules
48	----------
49
50	There are two kinds of submodules shipped with Taxonomy Filter:
51
52	* Template modules - modules that display the menu links in different ways.
53	Currently, these are: cloud, context and dynamic.
54
55	* Enhancement modules - modules that alter the functionality of each menu.
56	They can add extra information or features to the menu items, the menus them-
57	selves or the whole block. The two enhancement modules are: tf_count that adds
58	result counts to the output and tf_multi that allows for filtering by more than
59	two terms.
60
61
62	Configuration
63	-------------
64
65	Menu templates define the basic layout and functionality of a type of menu and
66	provided by Taxonomy Filter core or a submodule.
67
68	Menus are created from menu templates. A single template can be used to create
69	multiple menus with different settings.
70
71	On /admin/settings/taxonomy_filter page there are listings of all the template
72	types available, and all the menus that have been created from those templates.
73
74	Once you have created one or more menus, you can map them to vocabulary listings
75	on the /admin/settings/taxonomy_filter/mappings page. For each vocabulary you
76	can specify which menu it will use for display and which listings it will appear
77	on.
78
79
80	Optional Advanced Configuration
81	-------------------------------
82
83	On the /admin/settings/taxonomy_filter/advanced page you can configure how the
84	module handles URLs. There are options for specifying which URL patterns to
85	enable the taxonomy_filter menu for, and how to format the URLs produced by the
86	menu.
87	NOTE: you don't need to change these settings if you only use the standard
88	core taxonomy module to produce your taxonomy listings.
89
90	URLs to listen on:
91
92	This setting allows you to enable the block on listings produced by code other
93	than the core taxonomy module - eg custom views, or the taxonomy_menu module.
94
95	Each line is a URL pattern and the first one that matches will be used. Each
96	pattern can contain the following tokens:
97
98	%tids : for matching the term id(s) parameter used for creating the menu.
99	%depth : for matching the depth parameter in the URL.
100	%op : for matching the op parameter - eg 'page' or 'feed'. Usually not needed.
101	* : matches anything at that parameter position.
102
103
104	The %tids token is the only one that is required for generating the menu.
105
106	Example: taxonomy/term/%tids/%depth
107
108	matches the standard taxonomy module listings, and won't waste resources on
109	generating the menu for feed URLs where it isn't needed. This is the default.
110
111	taxonomy_menu/*/%tids
112	will match listing urls generated by the taxonomy_menu module.
113
114	URL format for menu links:
115
116	This setting is similar to the above but is a template for how the URLs created
117	by the menu are formatted. The available tokens are %tids and %depth. Only
118	%tids is required.
119
120	Example: taxonomy/term/%tids/%depth
121
122	will create links for the standard taxonomy module. This is the default.
123
124
125	Known Issues
126	------------
127
128	* This code has not been fully refined and automated tests have not been written.
129
130	* The taxonomy depth handling might not be implemented to the same level as the
131	Drupal 5.x version.