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.
So, I literally just spent about 3-4 hours trying to add action links to a custom view. The stumbling block? What to add for the "appears_on" value in the "*.links.action.yml" file.
It wasn't immediately apparent that the route for a view appears to be "view.[VIEW NAME].[DISPLAY NAME]". It makes intuitive sense, but I could not find it anywhere in the existing docs.
Comments
Comment #1
jhodgdonOK, that seems like a good thing to document. I'm not sure where to document it though. Do you have any suggestions? Where would you have looked, or where did you look, to figure this out?
Comment #2
GuyPaddock CreditAttribution: GuyPaddock at RedBottle Design, LLC for House at Work commentedComing from D7, there were a few things I didn't yet know with the new routes system, which I just learned today by trial and error:
Initially, I looked at the documentation for action links:
Providing module-defined actions
But that didn't really tell me a few things I needed to know, which were:
route_parameters
YAML key, but I didn't see this anywhere in the docs for action links. It only talked about theroute_name
parameter (apparently there's also another argument for link_path?).I ended up finding out about the missing parameters for action links and local tasks from this:
http://orangeweb.com.au/drupal-8-local-tasks
I still don't see all of those parameters documented in the official menu system / routing docs:
Comment #3
GuyPaddock CreditAttribution: GuyPaddock at RedBottle Design, LLC for House at Work commentedTo find out what the route was for a view, I actually ended up doing this in a custom module:
And then looking at the page route in the object. It turned out that for my view, "games", and display, "page_1", the route was "views.games.page_1", which makes a lot of sense and made me smile, but wasn't covered in either the menu system docs or the core Views docs:
Working with Views in Drupal 8
It might be good to indicate the convention for views routing in the views docs and then link back to the routing section for more details.
Comment #4
dawehnerIdeally I would really recommend you to have a look at the following project: http://drupal.org/project/webprofiler
It gives you the information about each route, depending on the active request.
On the other hand, it would be great to expand the documentation around the way how views routes are built together, this is certainly not trivial in general.
Comment #5
jibranComment #6
jhodgdonThanks for giving us some insight into your thought/search process GuyPaddock, that's very helpful! We've all been working with this stuff for months/years, and it's not always easy to get back to "If I was new at this, what would I need to know?".
So. Let's see if I can get this right, and summarize the documentation problem in this issue. The tasks here that were troublesome were:
a) Add an action link to a View page
b) Add an action link with placeholders to a page with placeholders in the path, like node/add/[something] having a link to my/module/[something]
The disconnect/missing information was:
1) Basic information about the routing system and its route machine names as compared to D7 that is path-based
2) Information about how to specify placeholders in an action link, so that the action link on, say, node/add/5 could have the 5 (node ID) in it too.
3) How to figure out what the route machine name is for something complicated like Views.
Is that right? Were there additional tasks or additional information that you found difficult to find?
Comment #7
jhodgdonAssuming that this is the correct list of missing information and tasks...
So... let's see. I hope that people know that for Drupal 8 at least, the developer starting point should probably be api.drupal.org. [If not, let's figure out why and fix that documentation].
So, if you go to api.drupal.org for Drupal 8, you'll see a nice list of topics:
https://api.drupal.org/api/drupal/8
From there, I think you'd find the "Routing, page controllers, and menu entries" topic as the one relevant to these tasks.
That page explains the basics of the routing system (with route machine names related to paths), and also has a section on routes with placeholders. The Local Actions section explains that you need to use the route machine name there.
So far, so good, I think... it looks to me as though we have the basics covered, and there are links there to additional documentation.
There's nothing about (2), placeholders in action links. And the action links section doesn't have a link to more information -- it should. Also the other admin links sections don't link to more information either. OK, that's a problem! They should be linking to sub-pages of https://www.drupal.org/developing/api/8/menu
So jumping there [we'll have to fix that lack-of-links problem], the local actions page is https://www.drupal.org/node/2133247
But that page doesn't have any information about placeholders either -- as you stated in comment #2 -- we need to add something.
And then there's the third piece, to discover what the route names are for dynamic routes like in Views. Back to the Routing and Menu topic, it mentions that some routes are in routing.yml files and some are dynamic, and it points to https://www.drupal.org/node/2122201 for info about dynamic routes, so hopefully you'd go there.
Reading that page, it tells me I'd need to look at the views.routing.yml file to find out what the dynamic route service is [it's views.route_subscriber:routes], and then it explains how that system works, so that's probably OK.
And also that page says down at the bottom that if I wanted to have a local action related to a dynamically-generated route, I'd need to respond to an onAlterRoutes event, which points me to https://www.drupal.org/node/2187643
There is a small section there telling what to do, and at least pointing to a real example.
So... Did I miss anything?
It seems like the main things we need to do are:
a) If your starting point was not api.drupal.org, figure out where you did start and make sure you get pointed to api.drupal.org instead as the starting point (which is the assumption we're making in Drupal 8 developer docs, because most people do get pointed there).
b) On the Routing and Menu topic page on api.drupal.org, add links from the menu links sections to the more detailed menu links pages on drupal.org. Those are missing.
c) On the menu links pages on drupal.org, add information on how to use placeholders in local tasks, actions, etc.
Anything else?
Comment #8
GuyPaddock CreditAttribution: GuyPaddock at RedBottle Design, LLC for House at Work commented@jhodgdon:
Regarding #6, looks like you've perfectly captured the disconnects / doc gaps.
Regarding #7, I've been working with Drupal since 4.5 and normally I do start with api.drupal.org, but I didn't for 8 because I don't know the names of any of the controllers / classes / components in the new Symfony-based Drupal design. I usually start with api.drupal.org when I know the name of a hook or class, so I can quickly get to the details of the hook / function signatures, data structures, etc. But, in this case, I didn't know exactly what I was looking for so I hopped over to the drupal.org community documentation looking for a high-level overview of how the new menu system works. (Actually, I did a lot of Googling for terms like "Drupal 8 routes", "Drupal 8 action links", "Drupal 8 views routes" and just landed in discussions and some of the docs on drupal.org, but not much from api.drupal.org).
Another consideration is that the "Routing, page controllers, and menu entries" topic appears to be written from the perspective of declaring new routes rather than consuming routes / referencing routes. I did come across that page but I wasn't creating a new route, so I disregarded it.
For (2), the issue with placeholders was actually that I didn't come across a page that documents the "route_parameters" options. I think you noted that, though, so no need for me to keep driving on that point.
For (3), I actually did get quickly accustomed to looking in *.routing.yml files for routes, and did open views.routing.yml. I even came across the "views.route_subscriber:routes" callback line and searched for "route_subscriber" in the "views" module. The problem was, when I landed in the service that views defines for that subscriber, I didn't see anything that really seemed related to how view routes get named. That service just seemed like a hodgepodge of different views-related callback handlers but nothing that said anything about view route names. So then I was roadblocked.
For the onAlterRoutes example, yes, I did see that, but my intention was just to find out the name of an existing route rather than modify one or declare a new one, so I disregarded it.
Comment #9
jhodgdonWe did a lot of work in the Drupal 8 cycle to make it so that api.drupal.org is a good starting point (hopefully!) for learning about Drupal 8's structure, classes, etc. There's a newly organized landing page, and a number of topics that hopefully give you an intro to all the D8 APIs. So please make that your new starting point. ;)
I agree that the Routing topic is oriented towards making new routes, but if you're working with routes you'd need to know how they're created (you'd need to look at routing.yml files to find the route machine names, for instance), so I actually think that is OK.
Anyway... we do need to do some work to address a few things... thanks again for your comments!
Comment #10
andypostThe code for route generation is buried in
\Drupal\views\Plugin\views\display\PathPluginBase::collectRoutes
Comment #11
GuyPaddock CreditAttribution: GuyPaddock at RedBottle Design, LLC for House at Work commented@andypost: +1 Thanks for pointing that out.
Comment #14
mlncn CreditAttribution: mlncn at Agaric for Teachers with GUTS commentedIf i may add a further request to documenting GuyPaddock's original request regarding appears_on...
What to put for appears_on for a route that takes a parameter? Not when the target route of the action link takes a parameter, but when the route the action link is supposed to appear on requires a parameter?
In my guts.links.action.yml, the first two links work— is there any way that the third (which uses the route name and route parameters of the second for the appears_on route) can also work?
Comment #15
mlncn CreditAttribution: mlncn at Agaric for Teachers with GUTS commentedIt appears that appears_on supports route names only, and there's no way to provide parameters. The code that consumes it takes only a route name.
Comment #16
dawehner@mlncn
Do you mind creating an issue for that itself? I'm wondering whether we could add a
isApplicable
method to local action to determine things more dynamically.