Club Drupal

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.

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.

==================

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('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.'))

==================

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., [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(),

  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.