Since Version 2.4, the Drupal 6 and 7 branches have an API to allow 3rd party modules to integrate with Page Title.

There are 3 exposed hooks which allow your own module to alter the Page Title Pattern, Page Title token value and add settings to the Settings page.

The 4 hooks are:

  • hook_page_title_api()
  • hook_page_title_pattern_alter(&$pattern, &$types)
  • hook_page_title_alter(&$title)
  • hook_page_title_settings()

Between these 4 hooks you easily integrate your own module with Page Title.

hook_page_title_api()

This function, currently, isn't required, but it is recommended. Essentially, you could implement the following 3 hooks in your module file and they would work. The point of the API hook is it allows you to bundle your Page Title support into a separate include file. This file only gets included if Page Title is enabled. If your module got deployed onto a site without Page Title enabled, you have only added a few lines of code to the module file (to implement the API hook) - there is nothing else for PHP to worry about compiling.

You would implement this hook in your module in a similar way to this.

/**
 * Implementation of hook_page_title_api().
 */
function example_page_title_api() {
  return array(
    'api' => 1,
    'path' => drupal_get_path('module', 'example') .'/includes',
  );
}

Some notes:

  • the 'path' item is optional. If it is left out, it will default to the implementing modules folder. In the example above the path is being set to an "includes" subfolder of the "example" module.
  • If this hook is defined, Page Title will try to include a file in the "path" folder called {MODULE_NAME}.page_title.inc. In the example above, Page Title will look for a file /sites/all/modules/example/includes/example.page_title.inc (assuming that "example" is installed in /sites/all/modules/example)

The following 3 hooks can either be implemented in your example.module file OR, preferably, in the example.page_title.inc file.

hook_page_title_pattern_alter(&$pattern, &$types)

This allows you to alter the PATTERN of a Page Title. The patterns are used to define token templates for specific contexts. The following snippet is from the node.page_title.inc file:

/**
 * Implementation of hook_page_title_pattern_alter().
 */
function node_page_title_pattern_alter(&$pattern, &$types) {
  $menu_item = menu_get_item();

  // Test if this is a node page.
  if ( !strncmp($menu_item['path'], 'node/%', 6) &&
       $node = menu_get_object() ) {
    $types['node'] = $node;

    // If the node has any taxonomy, grab the first term for user in tokens.
    // TODO: Handle multiple terms? Only pass specific terms per content type?
    if (!empty($types['node']->taxonomy)) {
      $types['taxonomy'] = current($types['node']->taxonomy);
    }

    $pattern = variable_get('page_title_type_'. $node->type, '');
  }
}

So in this file, we get the menu item, ensure we are on a "node/123"-like page and that we can get a node object from the menu argument. Once we have that, we can populate the $types object with relevant objects from the $node and we can set the Page Title Pattern to whatever is set for this specific node type.

The important thing to remember here is that both $pattern and $types are both passed in by reference, so any modifications you make also happen to the original variables; nothing gets returned.

hook_page_title_alter(&$title)>

This hook allows you to alter the value which gets set for the [page-title] token (or, if in Drupal 7, [current-page:page-title]). Usually, in this hook, you will determine the context and pull out a value which is set in the {page_title} table using the page_title_load_title($id, $type) function OR by getting an object from the Menu API system and pulling from that; this is how node.page_title.inc works:

/**
 * Implementation of hook_page_title_alter().
 */
function node_page_title_alter(&$title) {
  $menu_item = menu_get_item();

  // Test if this is a node page.
  if ( !strncmp($menu_item['path'], 'node/%', 6) &&
       ($node = menu_get_object()) &&
       !empty($node->page_title) &&
       variable_get('page_title_type_'. $node->type .'_showfield', 0)) {
    // If the node has a custom page title and the node type is configured
    // to have a custom page title (ie, it's not a leftover from a previous
    // setting), then use it.
    $title = $node->page_title;
  }
}

Similarly to above, we get the menu item, check the "context" using the URL, try to get a node object from the menu, ensure that the page title is set and ensure that the node type in question has the Page Title field set to visible. If all that is TRUE, then we set the $title (which, again, is passed by reference) to the $node->page_title value.

hook_page_title_settings()

This hook allows you to expose extra Page Title Pattern's on the Admin configuration page. The following is a snippet from node.page_title.inc (again!).

/**
 * Implementation of hook_page_title_settings().
 */
function node_page_title_settings() {
  $settings = array();

  $types = node_get_types();
  foreach ($types as $type) {
    $settings['page_title_type_'. $type->type] = array(
      'label' => 'Content Type - %type',
      'label arguments' => array('%type' => $type->name),
      'scopes' => array('global', 'node', 'taxonomy'),
      'show field' => TRUE,
      'description' => 'This pattern will be used for all %type node-type pages',
      'description arguments' => array('%type' => $type->name),
    );
  }

  return $settings;
}

So, for nodes we loop over all content types and define one setting for each.

The key in the $settings array will be used to store the setting in the variables table, so ensure this is going to be unique (it's usually good practice to prefix it with page_title_). The keys to the array are all optional; if they are not provided, they inherit from the following defaults:

array(
  'label' => '',
  'label arguments' => array(),
  'required' => FALSE,
  'show field' => FALSE,
  'description' => '',
  'description arguments' => array(),
  'weight' => 0,
  'default' => '',
);

More of the keys are fairly self explanatory, however for clarity…

  • label and label arguments - these get pased into the t() function. label is a string and label arguments is an array of replacement tokens.
  • requried - is this pattern a required pattern. Usually this is FALSE so that Page Title will "fall back" to the default (which IS required).
  • show field - show a checkbox be displayed for this key to allow an entity to provide it's own Page Title token value? This is used for Nodes, Users and Terms (but is not used for "static" patterns such as Forum Root). The value for this setting will be the key with _showfield suffixed.
  • description and description arguments - this is similar to title; the pair of fields get passed to the t() function. This appears on the admin form as the description text for the field.
  • weight - all settings are sorted by their weight and then by their label (alphabetically). All of the Page Title pattern weights are zero except Default, Frontpage and Pager Suffix which are -50, -49 and -48 respectively (forcing them to the top).
  • default - what is the default pattern if there is not set. Usually this is blank.