modules/pathauto/API.txt

$Id: API.txt,v 1.5 2008/01/22 14:26:53 greggles Exp $

This document explains how to provide "Pathauto integration" in a
module. You need this if you would like to provide additional tokens
or if your module has paths and you wish to have them automatically
aliased.  The simplest integration is just to provide tokens so we
cover that first.  More advanced integration requires an
implementation of hook_pathauto to provide a settings form.

It may be helpful to review some examples of integration from the
pathauto_node.inc, pathauto_taxonomy.inc, and pathauto_user.inc files.


==================
1 - Providing additional tokens
==================

If all you want is to enable tokens for your module you will simply
need to implement two functions:

  hook_token_values 
  hook_token_list

See the token.module and it's API.txt for more information about this
process.

When an object is created (whether it is a node or a user or a
taxonomy term) the data that Pathauto hands to the token_values in the
$object is in a specific format. This is the format that most people
write code to handle. However, during edits and bulk updates the data
may be in a totally different format. So, if you are writing a
hook_token_values implementation to add special tokens, be sure to
test creation, edit, and bulk update cases to make sure your code will
handle it.

==================
2 - Settings hook - To create aliases for your module
==================
You must implement hook_pathauto($op), where $op is always (at this
time) 'settings'. Return an object (NOT an array) containing the
following members, which will be used by pathauto to build a group
of settings for your module and define the variables for saving your
settings:

module - The name of your module (e.g., 'node')
groupheader - The translated label for the settings group (e.g.,
  t('Node path settings')
patterndescr - The translated label for the default pattern (e.g.,
  t('Default path pattern (applies to all node types with blank patterns below)')
patterndefault - A translated default pattern (e.g., t('[cat]/[title].html'))
placeholders - An array whose keys consist of the translated placeholders
  which will appear in patterns (e.g., t('[title]')) and values are 
  the translated description of the placeholders (e.g.,
  t('The title of the node, with spaces and punctuation.')
patternitems - For modules which need to express multiple patterns
  (for example, the node module supports a separate pattern for each
  node type), an array whose keys consist of identifiers for each
  pattern (e.g., the node type name) and values consist of the
  translated label for the pattern
supportsfeeds - Modules which support RSS feeds should set this to the
  string that's appended to a path for its feed (usually 'feed') , so 
  when administrators enable "Create feed aliases" an alias for this 
  content type's feed will be generated in addition to the base alias.
bulkname - For modules which support a bulk update operation, the
  translated label for the action (e.g., t('Bulk update node paths'))
bulkdescr - For modules which support a bulk update operation, a 
  translated, more thorough description of what the operation will do 
  (e.g., t('Generate aliases for all existing nodes which do not already have aliases.'))


==================
2 - $alias = pathauto_create_alias($module, $op, $placeholders, $src, $type=NULL)
==================

At the appropriate time (usually when a new item is being created for
which a generated alias is desired), call pathauto_create_alias() to
generate and create the alias.  See the user, taxonomy, and nodeapi hook 
implementations in pathauto.module for examples.

$module - The name of your module (e.g., 'node')
$op - Operation being performed on the item ('insert', 'update', or
  'bulkupdate')
$placeholders - An array whose keys consist of the translated placeholders
  which appear in patterns and values are the "clean" values to be 
  substituted into the pattern. Call pathauto_cleanstring() on any
  values which you do not know to be purely alphanumeric, to substitute
  any non-alphanumerics with the user's designated separator. Note that
  if the pattern has multiple slash-separated components (e.g., [catpath]),
  pathauto_cleanstring() should be called for each component, not the
  complete string.
  Example: $placeholders[t('[title]')] = pathauto_cleanstring($node->title);
$src - The "real" URI of the content to be aliased (e.g., "node/$node->nid")
$type - For modules which provided patternitems in hook_autopath(),
  the relevant identifier for the specific item to be aliased (e.g.,
  $node->type)

pathauto_create_alias() returns the alias that was created.


==================
3 - Bulk update function
==================

If a module supports bulk updating of aliases, it must provide a
function of this form, to be called by pathauto when the corresponding
checkbox is selected and the settings page submitted:

function <module>_pathauto_bulkupdate()

The function should iterate over the content items controlled by the
module, calling pathauto_create_alias() for each one. It is
recommended that the function report on its success (e.g., with a 
count of created aliases) via drupal_set_message().


==================
4 - Bulk delete hook_path_alias_types()
==================

For modules that create new types of pages that can be aliased with pathauto, a
hook implementation is needed to allow the user to delete them all at once.

function hook_path_alias_types()

This hook returns an array whose keys match the beginning of the source paths
(e.g.: "node/", "user/", etc.) and whose values describe the type of page (e.g.:
"content", "users"). Like all displayed strings, these descriptionsshould be 
localized with t(). Use % to match interior pieces of a path; "user/%/track". This
is a database wildcard, so be careful.


==================
Modules that extend node and/or taxonomy
==================

NOTE: this is basically not true any more.  If you feel you need this file an issue.

Many contributed Drupal modules extend the core node and taxonomy
modules. To extend pathauto patterns to support their extensions, they
may implement the pathauto_node and pathauto_taxonomy hooks.

To do so, implement the function <modulename>_pathauto_node (or _taxonomy),
accepting the arguments $op and $node (or $term). Two operations are
supported:

$op = 'placeholders' - return an array keyed on placeholder strings
(e.g., t('[eventyyyy]')) valued with descriptions (e.g. t('The year the 
event starts.')).
$op = 'values' - return an array keyed on placeholder strings, valued
with the "clean" actual value for the passed node or category (e.g., 
pathauto_cleanstring(date('M', $eventstart)));

See contrib/pathauto_node_event.inc for an example of extending node
patterns.

1	$Id: API.txt,v 1.5 2008/01/22 14:26:53 greggles Exp $
2
3	This document explains how to provide "Pathauto integration" in a
4	module. You need this if you would like to provide additional tokens
5	or if your module has paths and you wish to have them automatically
6	aliased. The simplest integration is just to provide tokens so we
7	cover that first. More advanced integration requires an
8	implementation of hook_pathauto to provide a settings form.
9
10	It may be helpful to review some examples of integration from the
11	pathauto_node.inc, pathauto_taxonomy.inc, and pathauto_user.inc files.
12
13
14	==================
15	1 - Providing additional tokens
16	==================
17
18	If all you want is to enable tokens for your module you will simply
19	need to implement two functions:
20
21	hook_token_values
22	hook_token_list
23
24	See the token.module and it's API.txt for more information about this
25	process.
26
27	When an object is created (whether it is a node or a user or a
28	taxonomy term) the data that Pathauto hands to the token_values in the
29	$object is in a specific format. This is the format that most people
30	write code to handle. However, during edits and bulk updates the data
31	may be in a totally different format. So, if you are writing a
32	hook_token_values implementation to add special tokens, be sure to
33	test creation, edit, and bulk update cases to make sure your code will
34	handle it.
35
36	==================
37	2 - Settings hook - To create aliases for your module
38	==================
39	You must implement hook_pathauto($op), where $op is always (at this
40	time) 'settings'. Return an object (NOT an array) containing the
41	following members, which will be used by pathauto to build a group
42	of settings for your module and define the variables for saving your
43	settings:
44
45	module - The name of your module (e.g., 'node')
46	groupheader - The translated label for the settings group (e.g.,
47	t('Node path settings')
48	patterndescr - The translated label for the default pattern (e.g.,
49	t('Default path pattern (applies to all node types with blank patterns below)')
50	patterndefault - A translated default pattern (e.g., t('[cat]/[title].html'))
51	placeholders - An array whose keys consist of the translated placeholders
52	which will appear in patterns (e.g., t('[title]')) and values are
53	the translated description of the placeholders (e.g.,
54	t('The title of the node, with spaces and punctuation.')
55	patternitems - For modules which need to express multiple patterns
56	(for example, the node module supports a separate pattern for each
57	node type), an array whose keys consist of identifiers for each
58	pattern (e.g., the node type name) and values consist of the
59	translated label for the pattern
60	supportsfeeds - Modules which support RSS feeds should set this to the
61	string that's appended to a path for its feed (usually 'feed') , so
62	when administrators enable "Create feed aliases" an alias for this
63	content type's feed will be generated in addition to the base alias.
64	bulkname - For modules which support a bulk update operation, the
65	translated label for the action (e.g., t('Bulk update node paths'))
66	bulkdescr - For modules which support a bulk update operation, a
67	translated, more thorough description of what the operation will do
68	(e.g., t('Generate aliases for all existing nodes which do not already have aliases.'))
69
70
71	==================
72	2 - $alias = pathauto_create_alias($module, $op, $placeholders, $src, $type=NULL)
73	==================
74
75	At the appropriate time (usually when a new item is being created for
76	which a generated alias is desired), call pathauto_create_alias() to
77	generate and create the alias. See the user, taxonomy, and nodeapi hook
78	implementations in pathauto.module for examples.
79
80	$module - The name of your module (e.g., 'node')
81	$op - Operation being performed on the item ('insert', 'update', or
82	'bulkupdate')
83	$placeholders - An array whose keys consist of the translated placeholders
84	which appear in patterns and values are the "clean" values to be
85	substituted into the pattern. Call pathauto_cleanstring() on any
86	values which you do not know to be purely alphanumeric, to substitute
87	any non-alphanumerics with the user's designated separator. Note that
88	if the pattern has multiple slash-separated components (e.g., [catpath]),
89	pathauto_cleanstring() should be called for each component, not the
90	complete string.
91	Example: $placeholders[t('[title]')] = pathauto_cleanstring($node->title);
92	$src - The "real" URI of the content to be aliased (e.g., "node/$node->nid")
93	$type - For modules which provided patternitems in hook_autopath(),
94	the relevant identifier for the specific item to be aliased (e.g.,
95	$node->type)
96
97	pathauto_create_alias() returns the alias that was created.
98
99
100	==================
101	3 - Bulk update function
102	==================
103
104	If a module supports bulk updating of aliases, it must provide a
105	function of this form, to be called by pathauto when the corresponding
106	checkbox is selected and the settings page submitted:
107
108	function <module>_pathauto_bulkupdate()
109
110	The function should iterate over the content items controlled by the
111	module, calling pathauto_create_alias() for each one. It is
112	recommended that the function report on its success (e.g., with a
113	count of created aliases) via drupal_set_message().
114
115
116	==================
117	4 - Bulk delete hook_path_alias_types()
118	==================
119
120	For modules that create new types of pages that can be aliased with pathauto, a
121	hook implementation is needed to allow the user to delete them all at once.
122
123	function hook_path_alias_types()
124
125	This hook returns an array whose keys match the beginning of the source paths
126	(e.g.: "node/", "user/", etc.) and whose values describe the type of page (e.g.:
127	"content", "users"). Like all displayed strings, these descriptionsshould be
128	localized with t(). Use % to match interior pieces of a path; "user/%/track". This
129	is a database wildcard, so be careful.
130
131
132	==================
133	Modules that extend node and/or taxonomy
134	==================
135
136	NOTE: this is basically not true any more. If you feel you need this file an issue.
137
138	Many contributed Drupal modules extend the core node and taxonomy
139	modules. To extend pathauto patterns to support their extensions, they
140	may implement the pathauto_node and pathauto_taxonomy hooks.
141
142	To do so, implement the function <modulename>_pathauto_node (or _taxonomy),
143	accepting the arguments $op and $node (or $term). Two operations are
144	supported:
145
146	$op = 'placeholders' - return an array keyed on placeholder strings
147	(e.g., t('[eventyyyy]')) valued with descriptions (e.g. t('The year the
148	event starts.')).
149	$op = 'values' - return an array keyed on placeholder strings, valued
150	with the "clean" actual value for the passed node or category (e.g.,
151	pathauto_cleanstring(date('M', $eventstart)));
152
153	See contrib/pathauto_node_event.inc for an example of extending node
154	patterns.
155