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