diff --git a/core/includes/module.inc b/core/includes/module.inc index d2cab6a..e7ddd45 100644 --- a/core/includes/module.inc +++ b/core/includes/module.inc @@ -178,31 +178,45 @@ function module_uninstall($module_list = array(), $uninstall_dependents = TRUE) /** * @defgroup hooks Hooks * @{ - * Allow modules to interact with the Drupal core. + * Define functions that alter the behavior of Drupal core. * - * Drupal's module system is based on the concept of "hooks". A hook is a PHP - * function that is named foo_bar(), where "foo" is the name of the module - * (whose filename is thus foo.module) and "bar" is the name of the hook. Each - * hook has a defined set of parameters and a specified result type. + * One way for modules to alter the core behavior of Drupal (or another module) + * is to use hooks. Hooks are specially-named functions that a module defines + * (this is known as "implementing the hook"), which are discovered and called + * at specific times to alter or add to Drupal's core behavior or data (this is + * known as "invoking the hook"). Each hook has a name (example: + * hook_batch_alter()), a defined set of parameters, and a defined return value. * - * To extend Drupal, a module need simply implement a hook. When Drupal wishes - * to allow intervention from modules, it determines which modules implement a - * hook and calls that hook in all enabled modules that implement it. + * To implement a hook: + * - Locate the documentation for the hook. Hooks are documented in *.api.php + * files, by defining functions whose name starts with "hook_" (these + * files and their functions are never loaded by Drupal -- they exist solely + * for documentation). The function should have a documentation header, as + * well as a sample function body. For example, in the core file + * system.api.php, you can find hooks such as hook_batch_alter(). Also, if + * you are viewing this documentation on an API reference site, the Core + * hooks will be listed in this topic. + * - Copy the function to your module's .module file. + * - Change the name of the function, substituting your module's short name + * for the "hook" part of the sample function name. For instance, to implemnt + * hook_batch_alter(), you would rename it to my_module_batch_alter(). + * - Edit the documentation for the function (normally, your implementation + * should just have one line saying "Implements hook_batch_alter()."). + * - Edit the body of the function, substituting in what you need your module + * to do. * - * The available hooks to implement are explained here in the Hooks section of - * the developer documentation. The string "hook" is used as a placeholder for - * the module name in the hook definitions. For example, if the module file is - * called example.module, then hook_help() as implemented by that module would - * be defined as example_help(). - * - * The example functions included are not part of the Drupal core, they are - * just models that you can modify. Only the hooks implemented within modules - * are executed when running Drupal. + * To invoke a hook, use methods on + * \Drupal\Core\Extension\ModuleHandlerInterface such as alter(), invoke(), + * and invokeAll(). You can obtain a module handler by calling + * \Drupal::moduleHandler(), or getting the 'module_handler' service on an + * injected container. * * @see themeable * @see callbacks + * @see \Drupal\Core\Extension\ModuleHandlerInterface + * @see \Drupal::moduleHandler() * - * @} End of "defgroup hooks". + * @} */ /** diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php index 1ecc9c1..c34a8d2 100644 --- a/core/modules/system/core.api.php +++ b/core/modules/system/core.api.php @@ -19,7 +19,7 @@ * * - @link architecture Drupal's architecture @endlink * - @link oo_conventions Object-oriented conventions used in Drupal @endlink - * - @link extending Extending Drupal @endlink + * - @link extending Extending and altering Drupal @endlink * - @link best_practices Security and best practices @endlink * * @section interface User interface @@ -452,15 +452,63 @@ */ /** - * @defgroup extending Extending Drupal + * @defgroup extending Extending and altering Drupal * @{ - * Overview of hooks, plugins, annotations, event listeners, and services. + * Overview of add-ons and alteration methods for Drupal + * + * Drupal's core behavior can be extended and altered via these three basic + * types of add-ons: + * - Themes: Themes alter the appearance of Drupal sites. They can include + * template files, which alter the HTML markup and other raw output of the + * site; CSS files, which alter the styling applied to the HTML; and + * JavaScript, Flash, images, and other files. For more information, see the + * @link theme_render Theme system and render API topic @endlink and + * https://drupal.org/theme-guide/8 + * - Modules: Modules add to or alter the behavior and functionality of Drupal, + * by using one or more of the methods listed in the section below. + * - Installation profiles: Installation profiles can be used to + * create distributions, which are complete specific-purpose packages of + * Drupal including additional modules, themes, and data. For more + * information, see https://drupal.org/documentation/build/distributions. + * + * @section extend_types Alteration mechanisms modules can use + * Here is a list of the mechanisms and methods that modules can use to alter + * or extend Drupal's core behavior, or the behavior of other modules: + * - Hooks: Specially-named functions that a module defines, which are + * discovered and called at specific times, usually to alter behavior or data. + * See the @link hooks Hooks topic @endlink for more information. + * - Plugins: Classes that a module defines, which are discovered and + * instantiated at specific times to add functionality. See the + * @link plugins Plugin API topic @endlink for more information. + * - Entities: Special plugins that define entity types for storing new types + * of content or configuration in Drupal. See the + * @link entity_api Entity API topic @endlink for more information. Note that + * there are also entity hooks and plugin types that you can use to add + * entity bundles or sub-types, alter display, etc. + * - Services: Classes that perform basic operations within Drupal, such as + * accessing the database and sending e-mail. See the + * @link container Dependency Injection Container and Services topic @endlink + * for more information. + * - Routing: Providing or altering "routes", which are URLs that Drupal + * responds to, or altering routing behavior with event listener classes. + * See the @link menu Routing and menu topic @endlink for more information. + * @} + */ + +/** + * @defgroup plugins Plugin API + * @{ + * Overview of the Plugin API * * @todo write this * * Additional documentation paragraphs need to be written, and functions, - * classes, and interfaces need to be added to this topic. This should be - * high-level and link to more detailed topics. + * classes, and interfaces need to be added to this topic. + * + * See https://drupal.org/developing/api/8/plugins and links therein for + * references. This should be an overview and link to details. + * + * @see annotation * @} */