modules/taxonomy_filter/API.txt

$Id: API.txt,v 1.1 2008/07/13 22:52:33 styro Exp $

This file describes the Taxonomy Filter API for creating add-on modules.

Note: Please study the supplied add-on modules for examples of how to use this
API as the following descriptions may be a bit brief.


Module and hook naming
----------------------

You will note that the supplied add-on module names and their functions are all
prefixed with 'tf_' which does make some of their function names look a little
untidy. This is just to prevent namespace conflicts with other modules that may
already be or in the future exist in the Drupal CVS repository. This is because
these modules won't have their own drupal.org project to otherwise reserve their
own namespace.

Note: Your own modules do not have to follow this module naming convention.

The hooks provided by the Taxonomy Filter API are also prefixed with 'tf_' to
avoid namespace collisions with other contrib module frameworks.


Module placement
----------------

Your own add-on modules shouldn't need to be placed in the Taxonomy Filter
directory, and I would recommend they not be to avoid potential problems with
updates overwriting files.

You should (via your modules .info file) put your module in the Taxonomy Filter
group to make it easier to enable/disable Taxonomy Filter add-on modules.


Taxonomy Filter data structure descriptions
-------------------------------------------

block

An array containing all the data for the block. Contains an 'info' array of
common data and a 'sections' array containing each sections data structure.

section

Generally each menu is a section, but modules can also create, alter (or even
delete) sections. Each section contains an 'info' array of data relating to the
section and an 'items' array of individual menu items.

item

This array correlates to a menu item. Basically it contains a link plus some
surrounding information or markup.

link

This is the actual HTML link.


Hook descriptions
-----------------

hook_tf_template_info()

This hook is required for all add-on modules that provide a menu template. It should
return an associative array containing a user friendly name and description of
the menu template.


hook_tf_section($section_info, $block_info)

This is an optional hook for template modules. It allows them to supply a custom
array of term objects to the section factory function. Note: if the term objects
have a template_settings attribute, that will be copied into the section data
also.


hook_tf_item_alter(&$item, $section_info, $block_info, $context = NULL)

An optional standard Drupal style alter hook for each item before it gets
inserted into the section array. The $context is an optional parameter than can
be checked for elsewhere.


hook_tf_link_tids_alter(&$link_tids, $item_tid, $context)

This optional hook allows a add-on module to alter the term ids listed in its link.
The $context parameter will contain any value passed into the modules
tf_alter_item hook.


hook_tf_section_alter(&$section, $block_info)

An optional standard Drupal style alter hook for the section data. This runs
after the section has been created from all the (potentially altered) item data.


hook_tf_block_alter(&$block)

Once the (potentially altered) section data is assembled into the block array,
This optional hook allows the block itself to be altered.


hook_tf_settings()

Returns a FormAPI array that gets inserted in the menu edit form. This optional
hook allows add-on modules to collect their own settings.


hook_tf_settings_submit($form, &$form_state)

A standard FormAPI submit handler for the extra settings. Only required if the
module supplies a tf_settings hook.


Theme overrides
---------------

PHPTemplate in Drupal 6.x is cool.

Submodules can supply their own preprocess functions to add/alter template
variables and even add their own templates. See the shipped add-on modules for
examples.
1	$Id: API.txt,v 1.1 2008/07/13 22:52:33 styro Exp $
2
3	This file describes the Taxonomy Filter API for creating add-on modules.
4
5	Note: Please study the supplied add-on modules for examples of how to use this
6	API as the following descriptions may be a bit brief.
7
8
9	Module and hook naming
10	----------------------
11
12	You will note that the supplied add-on module names and their functions are all
13	prefixed with 'tf_' which does make some of their function names look a little
14	untidy. This is just to prevent namespace conflicts with other modules that may
15	already be or in the future exist in the Drupal CVS repository. This is because
16	these modules won't have their own drupal.org project to otherwise reserve their
17	own namespace.
18
19	Note: Your own modules do not have to follow this module naming convention.
20
21	The hooks provided by the Taxonomy Filter API are also prefixed with 'tf_' to
22	avoid namespace collisions with other contrib module frameworks.
23
24
25	Module placement
26	----------------
27
28	Your own add-on modules shouldn't need to be placed in the Taxonomy Filter
29	directory, and I would recommend they not be to avoid potential problems with
30	updates overwriting files.
31
32	You should (via your modules .info file) put your module in the Taxonomy Filter
33	group to make it easier to enable/disable Taxonomy Filter add-on modules.
34
35
36	Taxonomy Filter data structure descriptions
37	-------------------------------------------
38
39	block
40
41	An array containing all the data for the block. Contains an 'info' array of
42	common data and a 'sections' array containing each sections data structure.
43
44	section
45
46	Generally each menu is a section, but modules can also create, alter (or even
47	delete) sections. Each section contains an 'info' array of data relating to the
48	section and an 'items' array of individual menu items.
49
50	item
51
52	This array correlates to a menu item. Basically it contains a link plus some
53	surrounding information or markup.
54
55	link
56
57	This is the actual HTML link.
58
59
60	Hook descriptions
61	-----------------
62
63	hook_tf_template_info()
64
65	This hook is required for all add-on modules that provide a menu template. It should
66	return an associative array containing a user friendly name and description of
67	the menu template.
68
69
70	hook_tf_section($section_info, $block_info)
71
72	This is an optional hook for template modules. It allows them to supply a custom
73	array of term objects to the section factory function. Note: if the term objects
74	have a template_settings attribute, that will be copied into the section data
75	also.
76
77
78	hook_tf_item_alter(&$item, $section_info, $block_info, $context = NULL)
79
80	An optional standard Drupal style alter hook for each item before it gets
81	inserted into the section array. The $context is an optional parameter than can
82	be checked for elsewhere.
83
84
85	hook_tf_link_tids_alter(&$link_tids, $item_tid, $context)
86
87	This optional hook allows a add-on module to alter the term ids listed in its link.
88	The $context parameter will contain any value passed into the modules
89	tf_alter_item hook.
90
91
92	hook_tf_section_alter(&$section, $block_info)
93
94	An optional standard Drupal style alter hook for the section data. This runs
95	after the section has been created from all the (potentially altered) item data.
96
97
98	hook_tf_block_alter(&$block)
99
100	Once the (potentially altered) section data is assembled into the block array,
101	This optional hook allows the block itself to be altered.
102
103
104	hook_tf_settings()
105
106	Returns a FormAPI array that gets inserted in the menu edit form. This optional
107	hook allows add-on modules to collect their own settings.
108
109
110	hook_tf_settings_submit($form, &$form_state)
111
112	A standard FormAPI submit handler for the extra settings. Only required if the
113	module supplies a tf_settings hook.
114
115
116
117	Theme overrides
118	---------------
119
120	PHPTemplate in Drupal 6.x is cool.
121
122	Submodules can supply their own preprocess functions to add/alter template
123	variables and even add their own templates. See the shipped add-on modules for
124	examples.