#314870 by Rob Loach, drewish, catch, and sun: Add hook API documentation to Drupal core.

CHANGELOG.txt

@@ -31,6 +31,8 @@ Drupal 7.0, xxxx-xx-xx (development version)
     * Added an edit tab to taxonomy term pages.
     * Redesigned password strength validator.
     * Redesigned the add content type screen.
+- Documentation:
+    * Hook API documentation now included in Drupal core.
 - News aggregator:
     * Added OPML import functionality for RSS feeds.
     * Optionally, RSS feeds may be configured to not automatically generate feed blocks.

modules/block/block.api.php

+<?php
+// $Id$
+
+/**
+ * @file
+ * Hooks provided by the Block module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Declare a block or set of blocks.
+ *
+ * Any module can export a block (or blocks) to be displayed by defining
+ * the _block hook. This hook is called by theme.inc to display a block,
+ * and also by block.module to procure the list of available blocks.
+ *
+ * @param $op
+ *   What kind of information to retrieve about the block or blocks.
+ *   Possible values:
+ *   - 'list': A list of all blocks defined by the module.
+ *   - 'configure': Configuration form for the block.
+ *   - 'save': Save the configuration options.
+ *   - 'view': Process the block when enabled in a region in order to view its contents.
+ * @param $delta
+ *   Which block to return (not applicable if $op is 'list'). This is a
+ *   descriptive string used to identify blocks within each module and also
+ *   within the theme system. The $delta for each block is defined within
+ *   the array that your module returns when $op is 'list' (see below).
+ * @param $edit
+ *   If $op is 'save', the submitted form data from the configuration form.
+ * @return
+ *   - If $op is 'list': An associative array whose keys define the $delta
+ *     for each block and whose values contain the block descriptions. Each
+ *     block description is itself an associative array, with the following
+ *     key-value pairs:
+ *     - 'info': (required) The human-readable name of the block.
+ *     - 'cache': A bitmask of flags describing how the block should behave with
+ *       respect to block caching. The following shortcut bitmasks are provided
+ *       as constants in block.module:
+ *       - BLOCK_CACHE_PER_ROLE (default): The block can change depending on the
+ *         roles the user viewing the page belongs to.
+ *       - BLOCK_CACHE_PER_USER: The block can change depending on the user
+ *         viewing the page. This setting can be resource-consuming for sites
+ *         with large number of users, and should only be used when
+ *         BLOCK_CACHE_PER_ROLE is not sufficient.
+ *       - BLOCK_CACHE_PER_PAGE: The block can change depending on the page
+ *         being viewed.
+ *       - BLOCK_CACHE_GLOBAL: The block is the same for every user on every
+ *         page where it is visible.
+ *       - BLOCK_NO_CACHE: The block should not get cached.
+ *     - 'weight', 'status', 'region', 'visibility', 'pages':
+ *       You can give your blocks an explicit weight, enable them, limit them to
+ *       given pages, etc. These settings will be registered when the block is first
+ *       loaded at admin/block, and from there can be changed manually via block
+ *       administration.
+ *       Note that if you set a region that isn't available in a given theme, the
+ *       block will be registered instead to that theme's default region (the first
+ *       item in the _regions array).
+ *   - If $op is 'configure': optionally return the configuration form.
+ *   - If $op is 'save': return nothing.
+ *   - If $op is 'view': return an array which must define a 'subject' element
+ *     and a 'content' element defining the block indexed by $delta.
+ *
+ * The functions mymodule_display_block_exciting and _amazing, as used in the
+ * example, should of course be defined somewhere in your module and return the
+ * content you want to display to your users. If the "content" element is empty,
+ * no block will be displayed even if "subject" is present.
+ *
+ * After completing your blocks, do not forget to enable them in the
+ * block admin menu.
+ *
+ * For a detailed usage example, see block_example.module.
+ */
+function hook_block($op = 'list', $delta = '', $edit = array()) {
+  if ($op == 'list') {
+    $blocks['exciting'] = array(
+      'info' => t('An exciting block provided by Mymodule.'),
+      'weight' => 0,
+      'status' => 1,
+      'region' => 'left',
+      // BLOCK_CACHE_PER_ROLE will be assumed for block 0.
+    );
+
+    $blocks['amazing'] = array(
+      'info' => t('An amazing block provided by Mymodule.'),
+      'cache' => BLOCK_CACHE_PER_ROLE | BLOCK_CACHE_PER_PAGE,
+    );
+
+    return $blocks;
+  }
+  elseif ($op == 'configure' && $delta == 'exciting') {
+    $form['items'] = array(
+      '#type' => 'select',
+      '#title' => t('Number of items'),
+      '#default_value' => variable_get('mymodule_block_items', 0),
+      '#options' => array('1', '2', '3'),
+    );
+    return $form;
+  }
+  elseif ($op == 'save' && $delta == 'exciting') {
+    variable_set('mymodule_block_items', $edit['items']);
+  }
+  elseif ($op == 'view') {
+    switch ($delta) {
+      case 'exciting':
+        $block = array(
+          'subject' => t('Default title of the exciting block'),
+          'content' => mymodule_display_block_exciting(),
+        );
+        break;
+      case 'amazing':
+        $block = array(
+          'subject' => t('Default title of the amazing block'),
+          'content' => mymodule_display_block_amazing(),
+        );
+        break;
+    }
+    return $block;
+  }
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */

modules/comment/comment.api.php

+<?php
+// $Id$
+
+/**
+ * @file
+ * Hooks provided by the Comment module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Act on comments.
+ *
+ * This hook allows modules to extend the comments system.
+ *
+ * @param $a1
+ *   Dependent on the action being performed.
+ *   - For "validate","update","insert", passes in an array of form values submitted by the user.
+ *   - For all other operations, passes in the comment the action is being performed on.
+ * @param $op
+ *   What kind of action is being performed. Possible values:
+ *   - "insert": The comment is being inserted.
+ *   - "update": The comment is being updated.
+ *   - "view": The comment is being viewed. This hook can be used to add additional data to the comment before theming.
+ *   - "validate": The user has just finished editing the comment and is
+ *     trying to preview or submit it. This hook can be used to check or
+ *     even modify the node. Errors should be set with form_set_error().
+ *   - "publish": The comment is being published by the moderator.
+ *   - "unpublish": The comment is being unpublished by the moderator.
+ *   - "delete": The comment is being deleted by the moderator.
+ * @return
+ *   Dependent on the action being performed.
+ *   - For all other operations, nothing.
+ */
+function hook_comment(&$a1, $op) {
+  if ($op == 'insert' || $op == 'update') {
+    $nid = $a1['nid'];
+  }
+
+  cache_clear_all_like(drupal_url(array('id' => $nid)));
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */

modules/filter/filter.api.php

+<?php
+// $Id$
+
+/**
+ * @file
+ * Hooks provided by the Filter module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Define content filters.
+ *
+ * Content in Drupal is passed through all enabled filters before it is
+ * output. This lets a module modify content to the site administrator's
+ * liking.
+ *
+ * This hook contains all that is needed for having a module provide filtering
+ * functionality.
+ *
+ * Depending on $op, different tasks are performed.
+ *
+ * A module can contain as many filters as it wants. The 'list' operation tells
+ * the filter system which filters are available. Every filter has a numerical
+ * 'delta' which is used to refer to it in every operation.
+ *
+ * Filtering is a two-step process. First, the content is 'prepared' by calling
+ * the 'prepare' operation for every filter. The purpose of 'prepare' is to
+ * escape HTML-like structures. For example, imagine a filter which allows the
+ * user to paste entire chunks of programming code without requiring manual
+ * escaping of special HTML characters like @< or @&. If the programming code
+ * were left untouched, then other filters could think it was HTML and change
+ * it. For most filters however, the prepare-step is not necessary, and they can
+ * just return the input without changes.
+ *
+ * Filters should not use the 'prepare' step for anything other than escaping,
+ * because that would short-circuits the control the user has over the order
+ * in which filters are applied.
+ *
+ * The second step is the actual processing step. The result from the
+ * prepare-step gets passed to all the filters again, this time with the
+ * 'process' operation. It's here that filters should perform actual changing of
+ * the content: transforming URLs into hyperlinks, converting smileys into
+ * images, etc.
+ *
+ * An important aspect of the filtering system are 'input formats'. Every input
+ * format is an entire filter setup: which filters to enable, in what order
+ * and with what settings. Filters that provide settings should usually store
+ * these settings per format.
+ *
+ * If the filter's behaviour depends on an extensive list and/or external data
+ * (e.g. a list of smileys, a list of glossary terms) then filters are allowed
+ * to provide a separate, global configuration page rather than provide settings
+ * per format. In that case, there should be a link from the format-specific
+ * settings to the separate settings page.
+ *
+ * For performance reasons content is only filtered once; the result is stored
+ * in the cache table and retrieved the next time the piece of content is
+ * displayed. If a filter's output is dynamic it can override the cache
+ * mechanism, but obviously this feature should be used with caution: having one
+ * 'no cache' filter in a particular input format disables caching for the
+ * entire format, not just for one filter.
+ *
+ * Beware of the filter cache when developing your module: it is advised to set
+ * your filter to 'no cache' while developing, but be sure to remove it again
+ * if it's not needed. You can clear the cache by running the SQL query 'DELETE
+ * FROM cache_filter';
+ *
+ * @param $op
+ *  Which filtering operation to perform. Possible values:
+ *   - list: provide a list of available filters.
+ *     Returns an associative array of filter names with numerical keys.
+ *     These keys are used for subsequent operations and passed back through
+ *     the $delta parameter.
+ *   - no cache: Return true if caching should be disabled for this filter.
+ *   - description: Return a short description of what this filter does.
+ *   - prepare: Return the prepared version of the content in $text.
+ *   - process: Return the processed version of the content in $text.
+ *   - settings: Return HTML form controls for the filter's settings. These
+ *     settings are stored with variable_set() when the form is submitted.
+ *     Remember to use the $format identifier in the variable and control names
+ *     to store settings per input format (e.g. "mymodule_setting_$format").
+ * @param $delta
+ *   Which of the module's filters to use (applies to every operation except
+ *   'list'). Modules that only contain one filter can ignore this parameter.
+ * @param $format
+ *   Which input format the filter is being used in (applies to 'prepare',
+ *   'process' and 'settings').
+ * @param $text
+ *   The content to filter (applies to 'prepare' and 'process').
+ * @param $langcode
+ *   The language code associated with the content, e.g. 'en' for English.  This
+ *   enables filters to be language aware and can be used to implement language
+ *   specific text replacements.
+ * @param $cache_id
+ *   The cache id of the content.
+ * @return
+ *   The return value depends on $op. The filter hook is designed so that a
+ *   module can return $text for operations it does not use/need.
+ *
+ * For a detailed usage example, see filter_example.module. For an example of
+ * using multiple filters in one module, see filter_filter() and
+ * filter_filter_tips().
+ */
+function hook_filter($op, $delta = 0, $format = -1, $text = '', $langcode = '', $cache_id = 0) {
+  switch ($op) {
+    case 'list':
+      return array(0 => t('Code filter'));
+
+    case 'description':
+      return t('Allows users to post code verbatim using &lt;code&gt; and &lt;?php ?&gt; tags.');
+
+    case 'prepare':
+      // Note: we use the bytes 0xFE and 0xFF to replace < > during the
+      // filtering process. These bytes are not valid in UTF-8 data and thus
+      // least likely to cause problems.
+      $text = preg_replace('@<code>(.+?)</code>@se', "'\xFEcode\xFF' . codefilter_escape('\\1') . '\xFE/code\xFF'", $text);
+      $text = preg_replace('@<(\?(php)?|%)(.+?)(\?|%)>@se', "'\xFEphp\xFF' . codefilter_escape('\\3') . '\xFE/php\xFF'", $text);
+      return $text;
+
+    case "process":
+      $text = preg_replace('@\xFEcode\xFF(.+?)\xFE/code\xFF@se', "codefilter_process_code('$1')", $text);
+      $text = preg_replace('@\xFEphp\xFF(.+?)\xFE/php\xFF@se', "codefilter_process_php('$1')", $text);
+      return $text;
+
+    default:
+      return $text;
+  }
+}
+
+/**
+ * Provide tips for using filters.
+ *
+ * A module's tips should be informative and to the point. Short tips are
+ * preferably one-liners.
+ *
+ * @param $delta
+ *   Which of this module's filters to use. Modules which only implement one
+ *   filter can ignore this parameter.
+ * @param $format
+ *   Which format we are providing tips for.
+ * @param $long
+ *   If set to true, long tips are requested, otherwise short tips are needed.
+ * @return
+ *   The text of the filter tip.
+ *
+ *
+ */
+function hook_filter_tips($delta, $format, $long = false) {
+  if ($long) {
+    return t('To post pieces of code, surround them with &lt;code&gt;...&lt;/code&gt; tags. For PHP code, you can use &lt;?php ... ?&gt;, which will also colour it based on syntax.');
+  }
+  else {
+    return t('You may post code using &lt;code&gt;...&lt;/code&gt; (generic) or &lt;?php ... ?&gt; (highlighted PHP) tags.');
+  }
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */

modules/help/help.api.php

+<?php
+// $Id$
+
+/**
+ * @file
+ * Hooks provided by the Help module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Provide online user help.
+ *
+ * By implementing hook_help(), a module can make documentation
+ * available to the engine or to other modules. All user help should be
+ * returned using this hook; developer help should be provided with
+ * Doxygen/api.module comments.
+ *
+ * @param $path
+ *   A Drupal menu router path the help is being requested for, e.g.
+ *   admin/node or user/edit. If the router path includes a % wildcard,
+ *   then this will appear in the path - for example all node pages will
+ *   have the path node/% or node/%/view.
+ *   Also recognizes special descriptors after a "#" sign. Some examples:
+ *   - admin/help#modulename
+ *     The module's help text, displayed on the admin/help page and through
+ *     the module's individual help link.
+ *   - user/help#modulename
+ *     The help for a distributed authorization module (if applicable).
+ * @param $arg
+ *   An array that corresponds to the return of the arg() function - if a module
+ *   needs to provide help for a page with additional parameters after the
+ *   Drupal path or help for a specific value for a wildcard in the path, then
+ *   the values in this array can be referenced.  For example you could provide
+ *   help for user/1 by looking for the path user/% and $arg[1] == '1'.  This
+ *   array should always be used rather than directly invoking arg(). Note that
+ *   depending on which module is invoking hook_help, $arg may contain only,
+ *   empty strings.  Regardless, $arg[0] to $arg[11] will always be set.
+ * @return
+ *   A localized string containing the help text. Every web link, l(), or
+ *   url() must be replaced with %something and put into the final t()
+ *   call:
+ *   $output .= 'A role defines a group of users that have certain
+ *     privileges as defined in %permission.';
+ *   $output = t($output, array('%permission' => l(t('user permissions'),
+ *     'admin/user/permission')));
+ *
+ * For a detailed usage example, see page_example.module.
+ */
+function hook_help($path, $arg) {
+  switch ($path) {
+    case 'admin/help#block':
+      return '<p>' . t('Blocks are boxes of content that may be rendered into certain regions of your web pages, for example, into sidebars. Blocks are usually generated automatically by modules (e.g., Recent Forum Topics), but administrators can also define custom blocks.') . '</p>';
+
+    case 'admin/build/block':
+      return t('<p>Blocks are boxes of content that may be rendered into certain regions of your web pages, for example, into sidebars. They are usually generated automatically by modules, but administrators can create blocks manually.</p>
+<p>If you want certain blocks to disable themselves temporarily during high server loads, check the "Throttle" box. You can configure the auto-throttle on the <a href="@throttle">throttle configuration page</a> after having enabled the throttle module.</p>
+<p>You can configure the behaviour of each block (for example, specifying on which pages and for what users it will appear) by clicking the "configure" link for each block.</p>', array('@throttle' => url('admin/settings/throttle')));
+  }
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */

modules/locale/locale.api.php

+<?php
+// $Id$
+
+/**
+ * @file
+ * Hooks provided by the Locale module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Allows modules to define their own text groups that can be translated.
+ *
+ * @param $op
+ *   Type of operation. Currently, only supports 'groups'.
+ */
+function hook_locale($op = 'groups') {
+  switch ($op) {
+    case 'groups':
+      return array('custom' => t('Custom'));
+  }
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */

modules/menu/menu.api.php

+<?php
+// $Id$
+
+/**
+ * @file
+ * Hooks provided by the Menu module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Define menu items and page callbacks.
+ *
+ * This hook enables modules to register paths, which determines whose
+ * requests are to be handled. Depending on the type of registration
+ * requested by each path, a link is placed in the the navigation block and/or
+ * an item appears in the menu administration page (q=admin/menu).
+ *
+ * This hook is called rarely - for example when modules are enabled.
+ *
+ * @return
+ *   An array of menu items. Each menu item has a key corresponding to the
+ *   Drupal path being registered. The item is an associative array that may
+ *   contain the following key-value pairs:
+ *
+ *   - "title": Required. The untranslated title of the menu item.
+ *   - "description": The untranslated description of the menu item.
+ *   - "page callback": The function to call to display a web page when the user
+ *     visits the path. If omitted, the parent menu item's callback will be used
+ *     instead.
+ *   - "page arguments": An array of arguments to pass to the page callback
+ *     function.  Integer values pass the corresponding URL component (see arg()).
+ *   - "access callback": A  function returning a boolean value that determines
+ *     whether the user has access rights to this menu item. Defaults to
+ *     user_access() unless a value is inherited from a parent menu item..
+ *   - "access arguments": An array of arguments to pass to the access callback
+ *     function. Integer values pass the corresponding URL component.
+ *   - "weight": An integer that determines relative position of items in the
+ *     menu; higher-weighted items sink. Defaults to 0. When in doubt, leave
+ *     this alone; the default alphabetical order is usually best.
+ *   - "menu_name": Optional. Set this to a custom menu if you don't want your
+ *     item to be placed in Navigation.
+ *   - "type": A bitmask of flags describing properties of the menu item.
+ *     Many shortcut bitmasks are provided as constants in menu.inc:
+ *     - MENU_NORMAL_ITEM: Normal menu items show up in the menu tree and can be
+ *       moved/hidden by the administrator.
+ *     - MENU_CALLBACK: Callbacks simply register a path so that the correct
+ *       function is fired when the URL is accessed.
+ *     - MENU_SUGGESTED_ITEM: Modules may "suggest" menu items that the
+ *       administrator may enable.
+ *     - MENU_LOCAL_TASK: Local tasks are rendered as tabs by default.
+ *     - MENU_DEFAULT_LOCAL_TASK: Every set of local tasks should provide one
+ *       "default" task, that links to the same path as its parent when clicked.
+ *     If the "type" key is omitted, MENU_NORMAL_ITEM is assumed.
+ *
+ * For a detailed usage example, see page_example.module.
+ *
+ * For comprehensive documentation on the menu system, see
+ * http://drupal.org/node/102338.
+ *
+ */
+function hook_menu() {
+  $items = array();
+
+  $items['blog'] = array(
+    'title' => 'blogs',
+    'page callback' => 'blog_page',
+    'access arguments' => array('access content'),
+    'type' => MENU_SUGGESTED_ITEM,
+  );
+  $items['blog/feed'] = array(
+    'title' => t('RSS feed'),
+    'page callback' => 'blog_feed',
+    'access arguments' => array('access content'),
+    'type' => MENU_CALLBACK,
+  );
+
+  return $items;
+}
+
+/**
+ * Alter the data being saved to the {menu_router} table after hook_menu is invoked.
+ *
+ * This hook is invoked by menu_router_build(). The menu definitions are passed
+ * in by reference.  Each element of the $callbacks array is one item returned
+ * by a module from hook_menu.  Additional items may be added, or existing items
+ * altered.
+ *
+ * @param $callbacks
+ *   Associative array of menu router definitions returned from hook_menu().
+ * @return
+ *   None.
+ */
+function hook_menu_alter(&$callbacks) {
+  // Example - disable the page at node/add
+  $callbacks['node/add']['access callback'] = FALSE;
+}
+
+/**
+ * Alter the data being saved to the {menu_links} table by menu_link_save().
+ *
+ * @param $item
+ *   Associative array defining a menu link as passed into menu_link_save().
+ * @param $menu
+ *   Associative array containg the menu router returned from menu_router_build().
+ * @return
+ *   None.
+ */
+function hook_menu_link_alter(&$item, $menu) {
+  // Example 1 - make all new admin links hidden (a.k.a disabled).
+  if (strpos($item['link_path'], 'admin') === 0 && empty($item['mlid'])) {
+    $item['hidden'] = 1;
+  }
+  // Example 2  - flag a link to be altered by hook_translated_menu_link_alter()
+  if ($item['link_path'] == 'devel/cache/clear') {
+    $item['options']['alter'] = TRUE;
+  }
+}
+
+/**
+ * Alter a menu link after it's translated, but before it's rendered.
+ *
+ * This hook may be used, for example, to add a page-specific query string.
+ * For performance reasons, only links that have $item['options']['alter'] == TRUE
+ * will be passed into this hook.  The $item['options']['alter'] flag should
+ * generally be set using hook_menu_link_alter().
+ *
+ * @param $item
+ *   Associative array defining a menu link after _menu_link_translate()
+ * @param $map
+ *   Associative array containing the menu $map (path parts and/or objects).
+ * @return
+ *   None.
+ */
+function hook_translated_menu_link_alter(&$item, $map) {
+  if ($item['href'] == 'devel/cache/clear') {
+    $item['localized_options']['query'] = drupal_get_destination();
+  }
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */

modules/search/search.api.php

+<?php
+// $Id$
+
+/**
+ * @file
+ * Hooks provided by the Search module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Define a custom search routine.
+ *
+ * This hook allows a module to perform searches on content it defines
+ * (custom node types, users, or comments, for example) when a site search
+ * is performed.
+ *
+ * Note that you can use form API to extend the search. You will need to use
+ * hook_form_alter() to add any additional required form elements. You can
+ * process their values on submission using a custom validation function.
+ * You will need to merge any custom search values into the search keys
+ * using a key:value syntax. This allows all search queries to have a clean
+ * and permanent URL. See node_form_alter() for an example.
+ *
+ * @param $op
+ *   A string defining which operation to perform:
+ *   - 'name': the hook should return a translated name defining the type of
+ *     items that are searched for with this module ('content', 'users', ...)
+ *   - 'reset': the search index is going to be rebuilt. Modules which use
+ *     hook_update_index() should update their indexing bookkeeping so that it
+ *     starts from scratch the next time hook_update_index() is called.
+ *   - 'search': the hook should perform a search using the keywords in $keys