diff --git a/API.txt b/API.txt index e585cd4..5235f59 100644 --- a/API.txt +++ b/API.txt @@ -5,8 +5,8 @@ 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. +It may be helpful to review some examples of integration from +pathauto.pathauto.inc. ================== @@ -14,29 +14,16 @@ pathauto_node.inc, pathauto_taxonomy.inc, and pathauto_user.inc files. ================== If all you want is to enable tokens for your module you will simply -need to implement two functions: +need to implement two hooks: - hook_token_values - hook_token_list + hook_tokens() - http://api.drupal.org/api/function/hook_tokens + hook_token_info() - http://api.drupal.org/api/function/hook_token_info -See the token.module and it's API.txt for more information about this -process. - -If the token is intended to generate a path expected to contain slashes, -the token name must end in 'path', 'path-raw' or 'alias'. This indicates to -Pathauto that the slashes should not be removed from the replacement value. - -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. +If you are upgrading a module from Drupal 6, see also +https://drupal.org/documentation/modules/token/update/6/7 ================== -2 - Settings hook - To create aliases for your module +2a - Settings hook - To create aliases for your module's custom paths ================== You must implement hook_pathauto($op), where $op is always (at this time) 'settings'. Return an object (NOT an array) containing the @@ -45,71 +32,69 @@ of settings for your module and define the variables for saving your settings: module - The name of your module (e.g., 'node') +token_type - The token type (e.g. 'node', 'user') that can be used. groupheader - The translated label for the settings group (e.g., t('Content path settings') patterndescr - The translated label for the default pattern (e.g., t('Default path pattern (applies to all content types with blank patterns below)') patterndefault - A translated default pattern (e.g., t('[cat]/[title].html')) -token_type - The token type (e.g. 'node', 'user') that can be used. patternitems - For modules which need to express multiple patterns (for example, the node module supports a separate pattern for each content type), an array whose keys consist of identifiers for each pattern (e.g., the content type name) and values consist of the translated label for the pattern -bulkname - For modules which support a bulk update operation, the - translated label for the action (e.g., t('Bulk update content 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 content items which do not already have aliases.')) +batch_update_callback - A batch update process function. See + http://api.drupal.org/api/drupal/includes--form.inc/group/batch/7 + for information about how to write a batch process function or look + at pathauto.pathauto.inc for examples. +batch_file - The file where the batch_update_callback exists. ================== -2 - $alias = pathauto_create_alias($module, $op, $placeholders, $src, $type=NULL) +2b - $alias = pathauto_create_alias($module, $op, $source, $data, $type = NULL, $language = LANGUAGE_NONE) ================== 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 +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., [term:path]), - 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(), +$module - The name of your module (e.g., 'node'). +$op - Operation being performed on the content being aliased ('insert', + 'update', 'return', or 'bulkupdate'). +$source - An internal Drupal path to be aliased. +$data - An array of keyed objects to pass to token_replace(). For simple + replacement scenarios, 'node',' 'user', and others are common keys, with + an accompanying node or user object being the value. Some token types, like + 'site', do not require any explicit information from $data and can be + replaced even if it is empty. +$type - For modules which provided pattern items in hook_pathauto(), the relevant identifier for the specific item to be aliased (e.g., - $node->type) + $node->type). +$langauge - A string specifying the path's language (the abbreviation, like + 'en' for English). pathauto_create_alias() returns the alias that was created. +pathauto_create_alias() is defined in pathauto.inc, so you must include that +file before calling the function by calling +module_load_include('inc', 'pathauto'); + ================== -3 - Bulk update function +3 - Delete individual aliases - pathauto_path_delete_all() ================== -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(). +To delete a URL alias and any of its sub-paths, call +pathauto_path_delete_all($source). For example, given a source like +'node/1', this function will delete any aliases of 'node/1' or that have any +sources that match 'node/1/%'. (The % is a database wildcard, so this matches +'node/1/view' as well as 'node/1/revision/2'.) Call this when the item your +module's page represents is deleted. ================== -4 - Bulk delete hook_path_alias_types() +4 - Bulk delete - hook_path_alias_types() ================== For modules that create new types of pages that can be aliased with pathauto, a @@ -118,32 +103,44 @@ 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. +(e.g.: "node/", "user/", etc.) and whose values describe the type of page +(e.g.: "Content", "Users"). Like all displayed strings, these descriptions +should be localized with t(). Use % to match interior pieces of a path, +like "user/%/track". This is a database wildcard (meaning "user/%/track" +matches "user/1/track" as well as "user/1/view/track"). ================== -Modules that extend node and/or taxonomy +5 - Altering paths - hook_pathauto_alias_alter(&$alias, array $context) ================== -NOTE: this is basically not true any more. If you feel you need this file an issue. +If you need to alter an alias before it is saved, implement +hook_pathauto_alias_alter(). + + $alias - A processed alias (with tokens replaced) to be modified. + $context - An array containing information about the alias: + - module: The name of the module providing the aliasing + - op: An operation as passed to pathauto_create_alias() (one of + 'insert', 'update', 'return', or 'bulkupdate'). + - source: The source path of the alias. + - data: An array containing the objects used to determine the tokens + to replace in the pattern. This is in the same format as the $data + parameter of pathauto_create_alias(). + - type: An identifier for the specific item (e.g. $node->type) if provided. + - language: A language identifier string (e.g. 'en' for English). + - pattern: The pattern string used to generate the alias. -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: +================== +6 - Altering punctuation - hook_pathauto_punctuation_chars_alter(array &$punctuation) +================== -$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))); +Implement hook_pathauto_punctuation_chars_alter(array &$punctuation) to alter +the list of characters Pathauto considers punctuation in aliases. -See contrib/pathauto_node_event.inc for an example of extending node -patterns. + $punctuation - An array of punctuation to be controlled by Pathauto during + replacement keyed by punctuation name. Each punctuation record should be + an array with the following key/value pairs: + - value: The raw value of the punctuation mark. + - name: The human-readable name of the punctuation mark. This must be + translated using t() already.