Commit 633dd952 authored by webchick's avatar webchick

Issue #2216561 by jhodgdon: Fill in @defgroup/topic docs for Extending Drupal.

parent 6ac97601
......@@ -178,31 +178,58 @@ 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 the base 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.
* Your modules can implement hooks that are defined by Drupal core or other
* modules that they interact with. Your modules can also define their own
* hooks, in order to let other modules interact with them.
*
* 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
* (name of the module's directory, and .info.yml file without the extension)
* 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().
* To define a hook:
* - Choose a unique name for your hook. It should start with "hook_", followed
* by your module's short name.
* - Provide documentation in a *.api.php file in your module's main
* directory. See the "implementing" section above for details of what this
* should contain (parameters, return value, and sample function body).
* - Invoke the hook in your module's code.
*
* 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 extending
* @see themeable
* @see callbacks
* @see \Drupal\Core\Extension\ModuleHandlerInterface
* @see \Drupal::moduleHandler()
*
* @} End of "defgroup hooks".
* @}
*/
/**
......
......@@ -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,61 @@
*/
/**
* @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 below. For more information
* about creating modules, see https://drupal.org/developing/modules/8
* - 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.
*
* Here is a list of the ways that modules can 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.
* - 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
* @}
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment