[Summary view] [Print] [Text view]

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