Problem/Motivation

This change record adds a '_title_callback' to routing https://drupal.org/node/2067859

This does not appear to have a callback documentation function in an api.php.

Update Actually the change record does not even document what the argument(s) is/are to the callback function and what it needs to return (translated? HTML-encoded? etc.). We need this information in order to document it on api.drupal.org as well.

Steps to reproduce

Proposed resolution

TBA

Remaining tasks

TBA

User interface changes

API changes

Data model changes

Release notes snippet

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

Adding a callback function doc would indeed be a good idea for this -- see
https://drupal.org/node/1354#callback-def
for how to do this.

The routing stuff is documented on
https://api.drupal.org/api/drupal/core!includes!menu.inc/group/menu/8
so that @defgroup is where the link would be made to this callback doc.

Both that @defgroup and this new callback doc should also be moved into a new .api.php file, routing.api.php, which is also being proposed on #2120253: Add documentation to entity routing to improve discoverability

dawehner’s picture

Before we get crazy let's think about whether we should just link to https://drupal.org/developing/api/8/routing which will be certainly always better as what core can provide us.

joachim’s picture

Those pages look great! But if you can't find in them, in under a minute, the answers to these questions:

- should the title callback return a string?
- a translated string?
- what happens to HTML entities in the return string?
- does it get any paramters

-- then we need a callback to formally document how you're meant to correctly implement it. It doesn't have to have much more than the params and the return and link to the main @routing docs topic.

jhodgdon’s picture

RE #2, the idea is that, like hooks, we document the function signature, parameters, and return value of "callbacks" that our APIs use. These are fully described at the top of the section on how to document them:
https://drupal.org/node/1354#callback-def

And yes, rather than making extremely long docs in @defgroup sections or in class/function docs headers, we should definitely link to pages under https://drupal.org/developing/api -- but still, any functions that a module would need to define in order to pass them into one of our APIs should have these callback dummy functions in an api.php file.

paulh’s picture

Assigned: Unassigned » paulh
paulh’s picture

Status: Active » Needs review
FileSize
394 bytes

Ok, to keep this moving I've added a stub, but I'm not sure about the function definition or signature. Guidance welcome.

jhodgdon’s picture

Status: Needs review » Needs work

OK, good start!

So... Let's see.

In the docs header, I think it should say "Callback for providing a route title in a *.routing.yml file".

I also think it should have "@see menu" in there rather than @see https://drupal.org/developing/api/8/routing (that will link within the API docs instead of heading out to drupal.org). And within the menu defgroup text (which is currently in core/modules/system/menu.inc but should be moved to this new routing.api.php file), we should add some text about title callbacks, and say something like "... the name of a function with the signature of callback_set_route_title()...". And that docblock should also have an @see to the d.o page.

So, the signature, let's see.

First of all, should we call it callback_set_route_title() or maybe just callback_route_title()? I'm undecided...

And to figure out what the signature is, I would suggest finding examples -- grep for "_title_callback" in routing.yml file. It looks like taxonomy and user modules have them. See what the parameters are for those functions; the return value should be the title (presumably translated).

Does that give you enough to go on for the next steps?

paulh’s picture

Status: Needs work » Needs review
FileSize
9.64 KB

See if this does the job. Added callback description, @defgroup and function to routing.api.php.

Status: Needs review » Needs work

The last submitted patch, 8: added-routing-api-php-file-for-callback-2218311-8.patch, failed testing.

paulh’s picture

Status: Needs work » Needs review
FileSize
9.65 KB

Missing semicolon!

jhodgdon’s picture

Priority: Normal » Critical
Issue summary: View changes
Status: Needs review » Needs work
Issue tags: +beta blocker, +Needs change record

OK, that's looking a bit better. A few things to fix:

a) At the top of the new routing.api.php file, there is a doc block that appears to be a stray? Should be removed?

b) When removing the @defgroup menu block from menu.api.php, we are removing the @defgroup menu ... @{ , which (besides defining the topic text) adds a bunch of functions in the file to the topic listing.

So we need to replace it by an @addtogroup menu block. See https://drupal.org/node/1354#defgroup

c) The information about the new title callback should go in the section of the docs that deals with the routing.yml file, not at the end. And it should be put into the routing.yml example, so we know how to tell the routing system that we have a title callback.

d)

+/**
+ * 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;
+}

Several problems here:
- Need 2 spaces of indentation in the @return section.
- I'm not sure what "filtered or encoded" means, and when it would be necessary?
- The parameter... I looked at several examples in node.routing.yml. It looks like the parameter is dynamically coming from the route specification. For instance, there is

node.view:
  path: '/node/{node}' 
  _title_callback: '\Drupal\node\Controller\NodeController::pageTitle'

And in that function there is an argument $node that is of type Node. Then there is another one whose argument is an integer that is the revision ID, and another whose argument is a node type object... Hm... This is not going to be easy to document, and the change notice doesn't really give us any documentation on what the argument is for this callback. That needs to be fixed first.

That is a beta blocker. Please fix the change notice at https://drupal.org/node/2067859 so it explains what the signature of the title callback function is (what the argument is and how it is derived). Then we can return to this issue and document this callback function on api.drupal.org.

xjm’s picture

This seems like an odd way to document this, and it seems like the only reason we're doing so is because it has the word "callback" in it. The _form and _content keys in the route definition also reference functions or methods that are essentially callbacks, but we wouldn't document them in this way, would we?

Also, I think this is a partial duplicate of #2076059: Missing documentation for 'title/title callback' using the route and render array and also a sub-issue of #2046367: Document the internals of the router. It doesn't seem explicitly beta-blocking to me on its own, since the change record does include a working example. We'd need to discuss whether the spotty router documentation overall should be beta-blocking. While I think #2046367: Document the internals of the router is definitely critical, it doesn't meet the beta blocker criteria per se.

jhodgdon’s picture

Well, how else do you propose to document the signature of such a callback function? That is precisely what the "callback" functions are for.

dawehner’s picture

One way to document such features would be a .routings.yml file inside system/api or somewhere similar. There you could describe each topic and refer
to some more details, maybe on the drupal.org handbook.

DamienMcKenna’s picture

This needs to mention that if the page output includes a #title then the _title_callback won't be used (per berdir in IRC).

Torenware’s picture

It appears this still is not done :-( In particular, the note at https://drupal.org/node/2067859 still does not contain useful information about how the signature is set. I'm not getting an argument for the callback right now, which is right annoying #($Jx

Torenware’s picture

After playing around with the debugger a while, it turns out that you will be passed the parameter in your routing entry, but only if the name of the parameter is exactly the same as the parameter used in your route.

See https://www.drupal.org/node/2067859#comment-10416241 for more detail as to how this works.

joachim’s picture

    if ($callback = $route->getDefault('_title_callback')) {
      $callable = $this->controllerResolver->getControllerFromDefinition($callback);
      $arguments = $this->controllerResolver->getArguments($request, $callable);
      $route_title = call_user_func_array($callable, $arguments);
    }

The title callback appears to receive some arguments, but I can't tell from this what they are. The documentation at https://www.drupal.org/node/2092643 doesn't mention parameters either.

jhodgdon’s picture

RE #18 - see #17.

So for example if your routing entry in the routing.yml file has a parameter named {foo} as part of the URL, and your title callback has an argument $foo, you'll get that argument filled in. Also ones from the arguments section of the routing.yml entry, again if the argument name exactly matches the name of the parameter in your callback.

tim.plunkett’s picture

Also, if it has a parameter \Symfony\Component\HttpFoundation\Request $request, it will get the current request as well.
See \Symfony\Component\HttpKernel\Controller\ControllerResolver::getArguments().

jhodgdon’s picture

Issue tags: -beta target

Good... seems like all the questions have been answered. Maybe we can get this done?

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

rodrigoaguilera’s picture

There is a user reporting something strange in this issue
https://www.drupal.org/project/page_manager/issues/2752227#comment-12650117

I'm not sure if the _title_callback should accept a string as an argument or it can be an object.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.6 was released on August 1, 2018 and is the final bugfix release for the Drupal 8.5.x series. Drupal 8.5.x will not receive any further development aside from security fixes. Sites should prepare to update to 8.6.0 on September 5, 2018. (Drupal 8.6.0-rc1 is available for testing.)

Bug reports should be targeted against the 8.6.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.8.x-dev

Drupal 8.6.x will not receive any further development aside from security fixes. Bug reports should be targeted against the 8.8.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.9.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.7 was released on June 3, 2020 and is the final full bugfix release for the Drupal 8.8.x series. Drupal 8.8.x will not receive any further development aside from security fixes. Sites should prepare to update to Drupal 8.9.0 or Drupal 9.0.0 for ongoing support.

Bug reports should be targeted against the 8.9.x-dev branch from now on, and new development or disruptive changes should be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.2.x-dev

Drupal 8 is end-of-life as of November 17, 2021. There will not be further changes made to Drupal 8. Bugfixes are now made to the 9.3.x and higher branches only. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.15 was released on June 1st, 2022 and is the final full bugfix release for the Drupal 9.3.x series. Drupal 9.3.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.4.x-dev branch from now on, and new development or disruptive changes should be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

apaderno’s picture

Title: document routing _title_callback » Document _title_callback
Version: 9.4.x-dev » 9.5.x-dev
Assigned: paulh » Unassigned

I am setting this issue as unassigned, since paulh hasn't worked on the issue since nine years ago.

apaderno’s picture

Issue tags: +Needs reroll

The patch also needs to be re-rolled since it doesn't apply anymore.

The Menu and routing system topic doesn't exist anymore; it has been split in Menu system and Routing API. It's the latter that needs to document _title_callback.

Arti Anil Pattewar’s picture

Rerolled patch for D9.5.
Attached rerolled patch.

Anchal_gupta’s picture

I have fixed CS error.

Anchal_gupta’s picture

Status: Needs work » Needs review
apaderno’s picture

Status: Needs review » Needs work
diff --git a/core/modules/system/routing.api.php b/core/modules/system/routing.api.php
new file mode 100644
index 0000000000..c082759f42
--- /dev/null
+++ b/core/modules/system/routing.api.php

The correct file is core/lib/Drupal/Core/Routing/routing.api.php.

Akram Khan’s picture

updating patch and address #39

Akram Khan’s picture

Akram Khan’s picture

Akram Khan’s picture

Fixing Custom Command failed. Address comment #39

Akram Khan’s picture

Status: Needs work » Needs review

Needs Review

apaderno’s picture

Status: Needs review » Needs work
 /**
  * @file
- * Hooks and documentation related to the routing system.
+ * Sets a dynamic route title using _title_callback in the route defaults.

The existing line is correct: The full core/lib/Drupal/Core/Routing/routing.api.php file documents the routing system, not just _title_callback.

/**
- * @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.

This issue isn't about replacing the current file content, but to add a section about _title_callback, which needs to be integrated into the existing sections.

quietone’s picture

Issue summary: View changes
Issue tags: +Needs issue summary update

This issue was discussed at a documentation triage meeting with myself and ambermatz. We agree that this issue is still valid. An Issue Summary update would be helpful for reviewers and triagers. This does appear to be about misleading documentation so leaving as a bug.

Version: 9.5.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.