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

jhodgdon’s picture

Title: Docs: Someone please document view routes » Someone please document view routes
Category: Feature request » Task

OK, 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?

GuyPaddock’s picture

Coming 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:

  1. Routes and paths are not directly related, unlike in D7 where the path was the ultimate decider of what got invoked.
  2. Arguments to routes in D8 are passed by name, whereas arguments in D7 are positional / numeric (i.e. pass path argument 3 to this function).

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:

  • How to handle passing arguments to routes like "node.add", which takes a node_type parameter (related to learning #2 above). I found out later, by looking at the docs for local tasks, that I can use the route_parameters YAML key, but I didn't see this anywhere in the docs for action links. It only talked about the route_name parameter (apparently there's also another argument for link_path?).
  • How to find out what the route is for dynamic things like views created by site builders.

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:

GuyPaddock’s picture

To find out what the route was for a view, I actually ended up doing this in a custom module:

/**
 * Implements hook_preprocess_HOOK().
 */
function my_module_preprocess_page(&$variables) {
  dpm(\Drupal::request());
}

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.

dawehner’s picture

Ideally 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.

jibran’s picture

Title: Someone please document view routes » Document views routes
Issue tags: +VDC
jhodgdon’s picture

Thanks 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?

jhodgdon’s picture

Assuming 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?

GuyPaddock’s picture

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

jhodgdon’s picture

We 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!

andypost’s picture

The code for route generation is buried in \Drupal\views\Plugin\views\display\PathPluginBase::collectRoutes

  public function collectRoutes(RouteCollection $collection) {
    $view_id = $this->view->storage->id();
    $display_id = $this->display['id'];

    $route = $this->getRoute($view_id, $display_id);

    if (!($route_name = $this->getOption('route_name'))) {
      $route_name = "view.$view_id.$display_id";
    }
    $collection->add($route_name, $route);

GuyPaddock’s picture

@andypost: +1 Thanks for pointing that out.

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.

mlncn’s picture

If 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?

guts.add_resource:
  route_name: 'node.add'
  route_parameters:
    node_type: 'resource'
  title: 'Add resource'
  appears_on:
    - view.search_resources_content.page_1

guts.go_home:
  route_name: 'entity.node.canonical'
  route_parameters:
    node: '8'
  title: 'Go home'
  appears_on:
    - view.search_resources_content.page_1

guts.add_resource_from_home:
  route_name: 'node.add'
  route_parameters:
    node_type: 'resource'
  title: 'Add resource'
  appears_on:
    -
      route_name: 'entity.node.canonical'
      route_parameters:
        node: '8'
mlncn’s picture

It 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.

dawehner’s picture

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

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.