Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
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
Comment | File | Size | Author |
---|---|---|---|
#43 | 2218311-43.patch | 12.95 KB | Akram Khan |
#42 | 2218311-42.patch | 12.95 KB | Akram Khan |
#41 | 2218311-41.patch | 12.95 KB | Akram Khan |
#40 | 2218311-40.patch | 12.98 KB | Akram Khan |
#37 | interdiff-2218311-36_37.txt | 1.02 KB | Anchal_gupta |
Comments
Comment #1
jhodgdonAdding 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
Comment #2
dawehnerBefore 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.
Comment #3
joachim CreditAttribution: joachim commentedThose 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.
Comment #4
jhodgdonRE #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.
Comment #5
paulh CreditAttribution: paulh commentedComment #6
paulh CreditAttribution: paulh commentedOk, to keep this moving I've added a stub, but I'm not sure about the function definition or signature. Guidance welcome.
Comment #7
jhodgdonOK, 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?
Comment #8
paulh CreditAttribution: paulh commentedSee if this does the job. Added callback description, @defgroup and function to routing.api.php.
Comment #10
paulh CreditAttribution: paulh commentedMissing semicolon!
Comment #11
jhodgdonOK, 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#defgroupc) 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)
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
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.
Comment #12
xjmThis 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.
Comment #13
jhodgdonWell, how else do you propose to document the signature of such a callback function? That is precisely what the "callback" functions are for.
Comment #14
dawehnerOne 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.
Comment #15
DamienMcKennaThis needs to mention that if the page output includes a #title then the _title_callback won't be used (per berdir in IRC).
Comment #16
Torenware CreditAttribution: Torenware as a volunteer commentedIt 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
Comment #17
Torenware CreditAttribution: Torenware as a volunteer commentedAfter 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.
Comment #18
joachim CreditAttribution: joachim commentedThe 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.
Comment #19
jhodgdonRE #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.
Comment #20
tim.plunkettAlso, 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().
Comment #21
jhodgdonGood... seems like all the questions have been answered. Maybe we can get this done?
Comment #27
rodrigoaguileraThere 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.
Comment #34
apadernoI am setting this issue as unassigned, since paulh hasn't worked on the issue since nine years ago.
Comment #35
apadernoThe 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.
Comment #36
Arti Anil Pattewar CreditAttribution: Arti Anil Pattewar at Srijan | A Material+ Company for Drupal India Association commentedRerolled patch for D9.5.
Attached rerolled patch.
Comment #37
Anchal_gupta CreditAttribution: Anchal_gupta at Srijan | A Material+ Company for Drupal India Association commentedI have fixed CS error.
Comment #38
Anchal_gupta CreditAttribution: Anchal_gupta at Srijan | A Material+ Company for Drupal India Association commentedComment #39
apadernoThe correct file is core/lib/Drupal/Core/Routing/routing.api.php.
Comment #40
Akram Khanupdating patch and address #39
Comment #41
Akram KhanComment #42
Akram Khanfixing CCF
Comment #43
Akram KhanFixing Custom Command failed. Address comment #39
Comment #44
Akram KhanNeeds Review
Comment #45
apadernoThe existing line is correct: The full core/lib/Drupal/Core/Routing/routing.api.php file documents the routing system, not just _title_callback.
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.
Comment #46
quietone CreditAttribution: quietone at PreviousNext commentedThis 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.