$Id: API.txt,v 1.5 2008-01-22 14:26:53 greggles Exp $ Implementing automatic aliases for a module There are three pieces a module must provide to support automatic aliasing (see pathauto_node.inc, pathauto_taxonomy.inc, and pathauto_user.inc for examples). Ideally this code will be integrated into a module, but a developer may extend a module they don't maintain by implementing these functions in a file of the form pathauto_.inc in the pathauto directory. Note that as of Pathauto 5-2 this API is vastly simplified. 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 for more information about this process. Legacy information is retained below - and it may apply if you have a complex module in which case you are encouraged to help the Pathauto maintainers figure out what the below text should say ;) ================== 1 - Settings hook ================== 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. $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 _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 ================== 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 ================== 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 _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.