diff --git a/core/includes/menu.inc b/core/includes/menu.inc index 11c9f07..9e28389 100644 --- a/core/includes/menu.inc +++ b/core/includes/menu.inc @@ -13,8 +13,8 @@ /** * Returns an array containing the names of system-defined (default) menus. * - * @deprecated in drupal:9.3.0 and is removed from drupal:10.0.0. Use - * \Drupal\system\Entity\Menu::loadMultiple() instead. + * @deprecated in drupal:9.3.0 and is removed from drupal:10.0.0. + * Use \Drupal\system\Entity\Menu::loadMultiple() instead. * * @see https://www.drupal.org/node/3027453 */ diff --git a/core/lib/Drupal/Core/Routing/routing.api.php b/core/lib/Drupal/Core/Routing/routing.api.php index d1239af..c082759 100644 --- a/core/lib/Drupal/Core/Routing/routing.api.php +++ b/core/lib/Drupal/Core/Routing/routing.api.php @@ -2,143 +2,118 @@ /** * @file - * Hooks and documentation related to the routing system. + * Sets a dynamic route title using _title_callback in the route defaults. + * Callback for providing a route title in a *.routing.yml file. + * + * @see menu + * + * @ingroup callbacks */ /** - * @defgroup routing Routing API + * @defgroup menu Menu and routing system * @{ - * Route page requests to code based on URLs. - * - * @section sec_overview Overview and terminology - * The Drupal routing system defines how Drupal responds to URL requests that - * the web server passes on to Drupal. The routing system is based on the - * @link http://symfony.com Symfony routing system. @endlink The central idea is - * that Drupal subsystems and modules can register routes (basically, URL - * paths and context); they can also register to respond dynamically to - * routes, for more flexibility. When Drupal receives a URL request, it will - * attempt to match the request to a registered route, and query dynamic - * responders. If a match is made, Drupal will then instantiate the required - * classes, gather the data, format it, and send it back to the web browser. - * Otherwise, Drupal will return a 404 or 403 response. - * - * The following sections of this topic provide an overview of the routing API. - * For more detailed information, see - * https://www.drupal.org/developing/api/8/routing - * - * @section sec_register Registering simple routes - * To register a route, add lines similar to this to a module_name.routing.yml - * file in your top-level module directory: - * @code - * dblog.overview: - * path: '/admin/reports/dblog' - * defaults: - * _controller: '\Drupal\dblog\Controller\DbLogController::overview' - * _title: 'Recent log messages' - * requirements: - * _permission: 'access site reports' - * @endcode - * Some notes: - * - The first line is the machine name of the route. Typically, it is prefixed - * by the machine name of the module that defines the route, or the name of - * a subsystem. - * - The 'path' line gives the URL path of the route (relative to the site's - * base URL). Generally, paths in Drupal are treated as case-insensitive, - * which overrides the default Symfony behavior. Specifically: - * - If different routes are defined for /example and /EXAmplE, the exact - * match is respected. - * - If there is no exact match, the route falls back to a case-insensitive - * match, so /example and /EXAmplE will return the same page. - * Relying on case-sensitive path matching is not recommended because it - * negatively affects user experience, and path aliases do not support case- - * sensitive matches. The case-sensitive exact match is currently supported - * only for backwards compatibility and may be deprecated in a later release. - * - The 'defaults' section tells how to build the main content of the route, - * and can also give other information, such as the page title and additional - * arguments for the route controller method. There are several possibilities - * for how to build the main content, including: - * - _controller: A callable, usually a method on a page controller class - * (see @ref sec_controller below for details). - * - _form: A form controller class. See the - * @link form_api Form API topic @endlink for more information about - * form controllers. - * - _entity_form: A form for editing an entity. See the - * @link entity_api Entity API topic @endlink for more information. - * - The 'requirements' section is used in Drupal to give access permission - * instructions (it has other uses in Symfony components). Most routes have a - * simple permission-based access scheme, as shown in this example. See the - * @link user_api Permission system topic @endlink for more information about - * permissions. - * - * See https://www.drupal.org/node/2092643 for more details about *.routing.yml - * files, and https://www.drupal.org/node/2122201 for information on how to - * set up dynamic routes. The @link events Events topic @endlink is also - * relevant to dynamic routes. - * - * @section sec_placeholders Defining routes with placeholders - * Some routes have placeholders in them, and these can also be defined in a - * module_name.routing.yml file, as in this example from the Block module: + * Define the navigation menus, and route page requests to code based on URLs. + * + * The Drupal routing system defines how Drupal responds to URLs passed to the + * browser. The menu system, which depends on the routing system, is used for + * navigation. The Menu module allows menus to be created in the user interface + * as hierarchical lists of links. + * + * @section registering_paths Registering router paths + * To register a path, you need to add lines similar to this in a + * module.routing.yml file: * @code - * entity.block.edit_form: - * path: '/admin/structure/block/manage/{block}' + * block.admin_display: + * path: '/admin/structure/block' * defaults: - * _entity_form: 'block.default' - * _title: 'Configure block' + * _content: '\Drupal\block\Controller\BlockListController::listing' * requirements: - * _entity_access: 'block.update' + * _permission: 'administer blocks' * @endcode - * In the path, '{block}' is a placeholder - it will be replaced by the - * ID of the block that is being configured by the entity system. See the - * @link entity_api Entity API topic @endlink for more information. - * - * @section sec_controller Route controllers for simple routes - * For simple routes, after you have defined the route in a *.routing.yml file - * (see @ref sec_register above), the next step is to define a page controller - * class and method. Page controller classes do not necessarily need to - * implement any particular interface or extend any particular base class. The - * only requirement is that the method specified in your *.routing.yml file - * returns: - * - A render array (see the - * @link theme_render Theme and render topic @endlink for more information). - * This render array is then rendered in the requested format (HTML, dialog, - * modal, AJAX are supported by default). In the case of HTML, it will be - * surrounded by blocks by default: the Block module is enabled by default, - * and hence its Page Display Variant that surrounds the main content with - * blocks is also used by default. - * - A \Symfony\Component\HttpFoundation\Response object. - * As a note, if your module registers multiple simple routes, it is usual - * (and usually easiest) to put all of their methods on one controller class. - * - * If the route has placeholders (see @ref sec_placeholders above) the - * placeholders will be passed to the method (using reflection) by name. - * For example, the placeholder '{my_var}' in a route will become the $my_var - * parameter to the method. - * - * Additionally, if a parameter is typed to one of the following special classes - * the system will pass those values as well. - * - * - \Symfony\Component\HttpFoundation\Request: The raw Symfony request object. - * It is generally only useful if the controller needs access to the query - * parameters of the request. By convention, this parameter is usually named - * $request. - * - \Psr\Http\Message\ServerRequestInterface: The raw request, represented - * using the PSR-7 ServerRequest format. This object is derived as necessary - * from the Symfony request, so if either will suffice the Symfony request - * will be slightly more performant. By convention this parameter is usually - * named $request. - * - \Drupal\Core\Routing\RouteMatchInterface: The "route match" data from - * this request. This object contains various standard data derived from - * the request and routing process. Consult the interface for details. - * - * Most controllers will need to display some information stored in the Drupal - * database, which will involve using one or more Drupal services (see the - * @link container Services and container topic @endlink). In order to properly - * inject services, a controller should implement - * \Drupal\Core\DependencyInjection\ContainerInjectionInterface; simple - * controllers can do this by extending the - * \Drupal\Core\Controller\ControllerBase class. See - * \Drupal\dblog\Controller\DbLogController for a straightforward example of - * a controller class. - * - * @} + * @todo Add more information here, especially about controllers and what all + * the stuff in the routing.yml file means. + * + * @section Defining menu links + * Once you have a route defined, you can use module.menu_links.yml to + * define links for your module's paths in the main Navigation menu or other + * menus. + * + * @todo The rest of this topic has not been reviewed or updated for Drupal 8.x + * and is not correct! + * @todo It is quite likely that hook_menu() will be replaced with a different + * hook, configuration system, or plugin system before the 8.0 release. + * + * Drupal's menu system follows a simple hierarchy defined by paths. + * Implementations of hook_menu() define menu items and assign them to + * paths (which should be unique). The menu system aggregates these items + * and determines the menu hierarchy from the paths. For example, if the + * paths defined were a, a/b, e, a/b/c/d, f/g, and a/b/h, the menu system + * would form the structure: + * - a + * - a/b + * - a/b/c/d + * - a/b/h + * - e + * - f/g + * Note that the number of elements in the path does not necessarily + * determine the depth of the menu item in the tree. + * + * When responding to a page request, the menu system looks to see if the + * path requested by the browser is registered as a menu item with a + * callback. If not, the system searches up the menu tree for the most + * complete match with a callback it can find. If the path a/b/i is + * requested in the tree above, the callback for a/b would be used. + * + * The found callback function is called with any arguments specified + * in the "page arguments" attribute of its menu item. The + * attribute must be an array. After these arguments, any remaining + * components of the path are appended as further arguments. In this + * way, the callback for a/b above could respond to a request for + * a/b/i differently than a request for a/b/j. + * + * For an illustration of this process, see page_example.module. + * + * Access to the callback functions is also protected by the menu system. + * The "access callback" with an optional "access arguments" of each menu + * item is called before the page callback proceeds. If this returns TRUE, + * then access is granted; if FALSE, then access is denied. Default local task + * menu items (see next paragraph) may omit this attribute to use the value + * provided by the parent item. + * + * In the default Drupal interface, you will notice many links rendered as + * tabs. These are known in the menu system as "local tasks", and they are + * rendered as tabs by default, though other presentations are possible. + * Local tasks function just as other menu items in most respects. It is + * convention that the names of these tasks should be short verbs if + * possible. In addition, a "default" local task should be provided for + * each set. When visiting a local task's parent menu item, the default + * local task will be rendered as if it is selected; this provides for a + * normal tab user experience. This default task is special in that it + * links not to its provided path, but to its parent item's path instead. + * The default task's path is only used to place it appropriately in the + * menu hierarchy. + * + * Everything described so far is stored in the menu_router table. The + * menu_links table holds the visible menu links. By default these are + * derived from the same hook_menu definitions, however you are free to + * add more with menu_link_save(). + * + * To declare a callback for a route title, detail a function with the signature + * of callback_set_route_title(). + * + * @see https://drupal.org/developing/api/8/routing + */ + +/** + * Callback for providing a route title. + * + * @param + * $get_title (can be a string, entity, int, interface) + * + * @return string + * The page title string (translated, filtered or encoded if necessary). */ +function callback_set_route_title($get_title) { + return $title; +}